Initial commit with LFS

.gitattributes

@@ -0,0 +1,2 @@
+data/processed/top_similar_items.pkl filter=lfs diff=lfs merge=lfs -text
+home-page-recos.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,21 @@
+venv/
+__pycache__/
+*.pyc
+.env
+.gemini/
+.gemini-*
+backup/
+blogs/
+requirements/
+GEMINI.md
+reproduce_issue.py
+
+# Data paths
+data/ml-*/
+data/*.zip
+data/processed/similarity_matrix.pkl
+
+# Keep processed artifacts (except the massive raw matrix)
+!data/processed/
+!data/processed/*.json
+!data/processed/top_similar_items.pkl

README.md

@@ -0,0 +1,48 @@
+# AI-Powered Explainable Recommendations
+
+This project is a high-fidelity demonstration of how Large Language Models (LLMs) can bridge the "explainability gap" in recommendation systems. It transforms opaque collaborative filtering data into transparent, persona-aligned narratives.
+
+![Demo Application](home-page-recos.jpg)
+
+## 🚀 Overview
+
+Instead of providing a "black box" list of suggestions, this system uses LLMs to synthesize natural language explanations based on user personas and collaborative filtering logic.
+
+### Key Features
+- **Specialist Centroids**: Personas built by aggregating top "specialists" for specific genres.
+- **Layered Re-ranking**: Incorporates Genre Affinity Boosts and Recency Bias.
+- **Narrative Synthesis**: Uses LiteLLM to generate 3-sentence explanations in "Logic-Driven" or "Social-Behavioral" styles.
+
+## 🛠 Tech Stack
+
+- **Interface**: [Gradio](https://gradio.app/)
+- **Recommendation Engine**: Python (`pandas`, `numpy`, `scikit-learn`)
+- **LLM Integration**: [LiteLLM](https://github.com/BerriAI/litellm)
+- **Data Source**: [MovieLens Latest Small](https://grouplens.org/datasets/movielens/latest/)
+- **Visuals**: [TMDB API](https://www.themoviedb.org/documentation/api) for movie posters.
+
+## 📁 Quick Start
+
+1.  **Environment Setup**:
+    Create a `.env` file:
+    ```env
+    HF_TOKEN=your_huggingface_token
+    TMDB_API_KEY=your_tmdb_api_key
+    ```
+2.  **Install Dependencies**:
+    ```bash
+    pip install -r requirements.txt
+    ```
+3.  **Data Preparation**:
+    ```bash
+    python data_prep.py
+    ```
+4.  **Run the Application**:
+    ```bash
+    python app.py
+    ```
+
+## 📜 Acknowledgments & Data Sources
+
+- **Dataset**: This project uses the **MovieLens Latest Dataset - Small** provided by [GroupLens Research](https://grouplens.org/datasets/movielens/).
+- **Images**: Movie posters are retrieved using the **TMDB API**. *Note: This product uses the TMDB API but is not endorsed or certified by TMDB.*

app.py

@@ -0,0 +1,531 @@
+# app.py - OPTIMIZED VERSION with Specialist Centroids & Normalized Ratings
+# Key optimization: Uses pre-computed top_similar_items for O(1) lookups
+# Layer 3 Normalization: Σ(Similarity × Rating) / Σ|Similarity| for proper collaborative filtering
+
+import gradio as gr
+import json
+import os
+import time
+import requests
+import litellm
+from config import TMDB_API_KEY, LLM_MODEL_NAME, BASE_PROMPT, LOGIC_INJECTION, SOCIAL_INJECTION
+
+# --- Configuration & Constants ---
+PROCESSED_DIR = 'data/processed'
+POSTER_PLACEHOLDER = "https://placehold.co/150x225/000000/FFFFFF?text=Poster"
+
+# --- Data Loading & Helpers ---
+def load_data(filename, is_pickle=False):
+    import pickle
+    path = os.path.join(PROCESSED_DIR, filename)
+    try:
+        if is_pickle:
+            with open(path, 'rb') as f: 
+                return pickle.load(f)
+        else:
+            with open(path, 'r') as f: 
+                return json.load(f)
+    except FileNotFoundError:
+        raise FileNotFoundError(f"Could not find '{filename}'. Please ensure data_prep.py ran successfully.")
+
+def get_poster_url(movie_title):
+    """Fetches a movie poster URL from the TMDB API."""
+    if not TMDB_API_KEY or TMDB_API_KEY == "YOUR_TMDB_API_KEY":
+        return POSTER_PLACEHOLDER
+    
+    try:
+        search_title = movie_title
+        year = None
+        if '(' in movie_title and ')' in movie_title:
+            year_str = movie_title[movie_title.rfind('(')+1:movie_title.rfind(')')]
+            if year_str.isdigit():
+                year = int(year_str)
+                search_title = movie_title[:movie_title.rfind('(')].strip()
+
+        search_params = {'api_key': TMDB_API_KEY, 'query': search_title}
+        if year:
+            search_params['year'] = year
+            
+        response = requests.get("https://api.themoviedb.org/3/search/movie", 
+                              params=search_params, timeout=3)
+        response.raise_for_status()
+        data = response.json()
+        
+        if data['results'] and data['results'][0].get('poster_path'):
+            poster_path = data['results'][0].get('poster_path')
+            return f"https://image.tmdb.org/t/p/w500{poster_path}"
+
+    except requests.exceptions.RequestException as e:
+        print(f"TMDB API call failed: {e}")
+    
+    return POSTER_PLACEHOLDER
+
+# Load data at startup
+print("Loading pre-computed data...")
+persona_archetypes = load_data('persona_archetypes.json')
+home_recommendations = load_data('home_recommendations.json')
+cached_hooks = load_data('cached_hooks.json')
+movie_metadata = load_data('movie_metadata.json')
+top_similar_items = load_data('top_similar_items.pkl', is_pickle=True)
+user_avg_ratings = load_data('user_avg_ratings.json')
+print(f"✅ Loaded pre-computed similarity lookups for {len(top_similar_items)} movies")
+
+# --- LLM EXPLANATION FUNCTION ---
+def call_llm_with_fallback(full_prompt, movie_data, persona_name):
+    """Calls the LLM using LiteLLM and provides a fallback explanation."""
+    try:
+        print(f"DEBUG: Generating explanation for '{movie_data.get('movie_title', 'Unknown')}' using model: {LLM_MODEL_NAME}")
+        start_ts = time.time()
+        response = litellm.completion(
+            model=LLM_MODEL_NAME,
+            messages=[{"role": "user", "content": full_prompt}],
+            max_tokens=120,
+            temperature=0.1,
+            stream=False
+        )
+        print(f"DEBUG: Full LLM Response Object: {response}")
+        print(f"DEBUG: Explanation generated in {time.time() - start_ts:.4f}s")
+        report = response.choices[0].message.content
+        print("--- LLM Response ---")
+        print(report)
+        print("--------------------")
+        return report, False
+
+    except Exception as e:
+        error_message = f"LiteLLM API Error: {e}"
+        print(f"⚠️ {error_message}")
+        gr.Warning(error_message)
+        # Fallback logic
+        genres = movie_data.get('genres', ['Drama'])
+        primary_genre = genres[0] if genres else "Drama"
+        fallback_text = f"Recommended because you enjoyed similar {primary_genre} films. Highly rated by users with your preferences."
+        return fallback_text, True
+
+def generate_hook_on_the_fly(movie_title):
+    """Generates a short, snappy hook for a movie using LiteLLM."""
+    prompt = f"Generate a 5-10 word snappy, atmospheric hook for the movie: {movie_title}."
+    try:
+        print(f"DEBUG: Generating hook for '{movie_title}' using model: {LLM_MODEL_NAME}")
+        start_ts = time.time()
+        response = litellm.completion(
+            model=LLM_MODEL_NAME,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=25,
+            temperature=0.7,
+            stream=False,
+        )
+        #print(f"DEBUG: Full LLM Response Object: {response}")
+        print(f"DEBUG: Hook generated in {time.time() - start_ts:.4f}s")
+        hook = response.choices[0].message.content.strip().replace('"', '')
+        return hook
+    except Exception as e:
+        print(f"LiteLLM API call for on-the-fly hook failed: {e}")
+        return "A truly captivating film."
+
+def generate_explanation(movie_id, persona_name, style):
+    movie_id_str = str(movie_id)
+    movie_info = movie_metadata[movie_id_str]
+    style_injection = LOGIC_INJECTION if style == "Logic-Driven" else SOCIAL_INJECTION
+    
+    # Create a single, consolidated prompt to be more direct
+    full_prompt = f"""You are a digital movie concierge explaining a recommendation to a user.
+                    Your explanation must be exactly 3 sentences and a maximum of 60 words.
+                    Be punchy and engaging. Do not start with 'Based on your history'.
+                    {style_injection}
+
+            Explain why the user with {persona_name} persona would like the movie '{movie_info['movie_title']}' 
+            (Genres: {', '.join(movie_info['genres'])}). But do not mention the persona directly."""
+    
+    return call_llm_with_fallback(full_prompt, movie_info, persona_name)
+
+css = """
+body { background-color: #f8fafc; }
+.gradio-container { max-width: 1280px !important; margin: 0 auto !important; }
+.view-container { padding: 20px; border: none; border-radius: 8px; margin-top: 20px; background: white; box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1); }
+
+.movie-card-container {
+    background: white; 
+    border-radius: 1rem; 
+    overflow: hidden; 
+    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
+    display: flex !important;
+    flex-direction: column !important;
+    height: 100%;
+    padding: 1rem;
+    gap: 1rem;
+}
+.movie-card-content { display: flex; flex-direction: column; flex-grow: 1; background-color: #ffffff;}
+.poster-container { position: relative; aspect-ratio: 2/3; background: #f1f5f9; }
+.poster-img { width: 100%; height: 100%; object-fit: cover; }
+.movie-card-text-content {
+    display: flex;
+    flex-direction: column;
+    flex-grow: 1;
+}
+.movie-title { 
+    font-weight: 700; 
+    font-size: 1.125rem; 
+    color: #1e293b; 
+    flex-shrink: 0;
+    /* FIX: Set fixed height to handle multi-line titles */
+    height: 2.5em; 
+    line-height: 1.25em; 
+    overflow: hidden;
+}
+.movie-year { font-size: 0.875rem; color: #64748b; margin-top: 2px; flex-shrink: 0; }
+.catchy-phrase { 
+    font-style: italic; 
+    color: #4f46e5; 
+    font-size: 1rem; 
+    margin: 0.75rem 0; 
+    /* FIX: Remove flex-grow and display:flex, left-align, and set fixed height */
+    text-align: left;
+    height: 2.5em; /* Approx 2 lines */
+    line-height: 1.2em;
+    overflow: hidden;
+}
+.genre-pills-container { display: flex; flex-wrap: wrap; gap: 5px; margin-top: 0.5rem; flex-shrink: 0; }
+.genre-pill { background: #e2e8f0; color: #334155; padding: 4px 8px; border-radius: 9999px; font-size: 0.7rem; font-weight: 500; }
+.synthesis-pill { 
+    position: absolute; top: 12px; left: 12px; 
+    background: rgba(30, 41, 59, 0.8);
+    color: white; padding: 4px 10px; 
+    border-radius: 9999px; font-size: 12px; font-weight: 600;
+    backdrop-filter: blur(4px); 
+    border: 1px solid rgba(255, 255, 255, 0.2);
+}
+
+.gradio-button {
+    background-color: #1e293b !important;
+    color: white !important;
+    border: none !important;
+    border-radius: 0.5rem !important;
+    font-weight: 600 !important;
+    transition: background-color 0.2s ease-in-out !important;
+    padding: 10px !important;
+}
+.gradio-button:hover { background-color: #334155 !important; }
+
+#persona_selection_view { 
+    max-width: 800px; 
+    margin: 40px auto !important; 
+}
+
+#persona_selection_view h2 { color: #1e293b !important; }
+
+#home_title h2 { color: #1e293b !important; }
+
+#detail_view { padding: 20px; border: none; border-radius: 8px; margin-top: 20px; background: white; box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1); }
+#detail_poster img { max-height: 450px; }
+#home_title h1 { color: #1e293b !important; }
+#detail_title h2 { color: #1e293b !important; }
+#detail_explanation p { color: #334155 !important; }
+#detail_explanation { border: 1px solid #e2e8f0; padding: 1rem; border-radius: 0.5rem; }
+
+#detail_view label {
+    color: white !important;
+    font-weight: 600 !important;
+    font-size: 1rem !important;
+    padding: 0.5rem 0.5rem !important;
+}
+
+#detail_view .gr-radio {
+    margin: 1rem 0 !important;
+    padding: 1.5rem !important;
+}
+"""
+
+def generate_card_html(movie_data, latency_s=0.02, is_live=False):
+    """Generates HTML for a single movie card."""
+    badge_text = f"⚡️ Synthesis: {latency_s:.2f}s"
+    genres_html = "".join([f'<span class="genre-pill">{g}</span>' 
+                          for g in movie_data.get('genres', [])[:5]])
+    return f"""
+    <div class="movie-card-content">
+        <div class="poster-container">
+            <img src="{movie_data['poster']}" class="poster-img" />
+            <div class="synthesis-pill">{badge_text}</div>
+        </div>
+        <div class="movie-card-text-content">
+            <div class="movie-title">{movie_data['title']}</div>
+            <div class="genre-pills-container">{genres_html}</div>
+            <div class="catchy-phrase">"{movie_data.get('hook', 'A must-see film.')}"</div>
+        </div>
+    </div>
+    """
+
+def update_home_cards_ui(persona_name, recommendations, is_live=False, time_taken=0.02):
+    """Updates UI with movie cards for given recommendations."""
+    updates = []
+    hooks = cached_hooks.get(persona_name, {}) if not is_live else {}
+
+    for i in range(6):
+        if i < len(recommendations):
+            rec = recommendations[i]
+            movie_id = str(rec['movie_id'])
+            movie_info = movie_metadata[movie_id]
+            card_data = {
+                "title": movie_info['movie_title'],
+                "year": movie_info.get('year', ''),
+                "genres": movie_info.get('genres', []),
+                "poster": get_poster_url(movie_info['movie_title']),
+                "hook": hooks.get(movie_id, "A great movie awaits!")
+            }
+            if is_live:
+                card_data["hook"] = rec.get('hook', "A movie worth watching!")
+            html_content = generate_card_html(card_data, time_taken, is_live)
+            updates.append(gr.update(value=html_content, visible=True))
+            updates.append(gr.update(visible=True))  # Show button
+            updates.append(movie_id)
+        else:
+            updates.append(gr.update(visible=False))
+            updates.append(gr.update(visible=False))  # Hide button
+            updates.append(None)
+    return updates
+
+
+
+# --- UI Construction ---
+with gr.Blocks(css=css) as demo:
+    selected_persona = gr.State(None)
+    selected_movie_id = gr.State(None)
+    
+    gr.Markdown("# 🎬 AI-Powered Explainable Recommendations")
+
+    with gr.Column(visible=True, elem_id="persona_selection_view", elem_classes="view-container") as persona_view:
+        gr.Markdown("## Choose a Persona")
+        persona_buttons = [gr.Button(f"View Recommendations for {name}") 
+                          for name in persona_archetypes.keys()]
+        gr.Markdown("""
+            <div style="margin-top: 1.5rem; padding: 1rem; background-color: #f1f5f9; border-radius: 0.75rem; border: 1px solid #e2e8f0;">
+                <p style="color: #475569; font-size: 0.9rem; margin-bottom: 0.5rem; line-height: 1.5;">
+                    <strong style="color: #1e293b;">Note:</strong> Since this demo doesn't include user accounts, we use <b style="color: #1e293b;">User Personas</b> to showcase personalized recommendations. Each persona represents a unique set of movie preferences.
+                </p>
+                <a href="https://blogs-amoydutta.hashnode.dev/explainable-recommendations-in-practice-a-demo-driven-approach" target="_blank" style="color: #4f46e5; font-size: 0.9rem; font-weight: 600; text-decoration: none;">
+                    Learn more about how this demo works in our blog →
+                </a>
+            </div>
+        """)
+
+    with gr.Column(visible=False, elem_id="home_view", 
+                   elem_classes="view-container") as home_view:
+        with gr.Row():
+            back_to_persona_button = gr.Button("⬅️ Change Persona")
+            home_title = gr.Markdown(elem_id="home_title")
+
+        all_genres = sorted(list(set(g for m in movie_metadata.values() for g in m['genres'])))
+        all_genres.insert(0, "All (Cached Home Page)")
+        genre_dropdown = gr.Dropdown(all_genres, label="Select Genre", 
+                                    value="All (Cached Home Page)")
+
+        with gr.Column(elem_id="recommendations_grid") as recommendations_grid:
+            home_cards = []
+            for i in range(2):
+                with gr.Row():
+                    for j in range(3):
+                        with gr.Column(elem_classes="movie-card-container"):
+                            html = gr.HTML()
+                            btn = gr.Button("⚡ See Full Explanation")
+                            movie_id_state = gr.State(None)
+                            home_cards.append({"html": html, "btn": btn, "id": movie_id_state})
+
+        no_recommendations_message = gr.Markdown("""
+        <div style="width: 100%; display: flex; justify-content: center; align-items: center; padding: 4rem 0;">
+            <div style="text-align: center;">
+                <h3 style="color: #1e293b;">🤷&nbsp; No recommendations found</h3>
+                <p style="color: #64748b; font-size: 0.875rem;">Try selecting a different genre for this persona.</p>
+            </div>
+        </div>
+""", visible=False)
+
+    with gr.Column(visible=False, elem_id="detail_view", 
+                   elem_classes="view-container") as detail_view:
+        back_button = gr.Button("⬅️ Back to Recommendations")
+        with gr.Row():
+            detail_poster = gr.Image(POSTER_PLACEHOLDER, show_label=False, elem_id="detail_poster")
+            with gr.Column():
+                detail_title = gr.Markdown(elem_id="detail_title")
+                detail_explanation = gr.Markdown(elem_id="detail_explanation", label="The 'Why'")
+                narrative_style = gr.Radio(["Logic-Driven", "Social-Behavioral"], 
+                                          label="Narrative Style", value="Logic-Driven")
+                detail_fallback_info = gr.Markdown(visible=False, elem_id="detail_fallback", 
+                                                  value="⚠️ LLM explanation failed or is disabled. Showing template-based reason.")
+
+    # Build output list
+    all_card_outputs = [item for card in home_cards for item in (card['html'], card['btn'], card['id'])]
+    home_page_outputs = [persona_view, home_view, detail_view, selected_persona, home_title] + all_card_outputs
+    detail_outputs = [home_view, detail_view, selected_movie_id, detail_title, 
+                     detail_poster, detail_explanation, detail_fallback_info]
+
+    def select_persona_and_render_home(persona_name):
+        print(f'Loading Home page for persona: {persona_name}')
+        start_time = time.time()
+        recs = home_recommendations.get(persona_name, [])
+        home_page_updates = [gr.update(visible=False), gr.update(visible=True), 
+                            gr.update(visible=False), persona_name, f"# {persona_name}'s Recommendations"]
+        card_updates = update_home_cards_ui(persona_name, recs)
+        time_taken = time.time() - start_time
+        print(f"Home page for '{persona_name}' rendered in {time_taken:.4f}s ({time_taken * 1000:.2f}ms)")
+        return home_page_updates + card_updates
+
+    def filter_by_genre(genre, persona_name):
+        """Filter recommendations by genre using Layer 3 normalization.
+        
+        Formula: R = Σ(Similarity × Normalized_Rating) / Σ|Similarity|
+        - Uses specialist centroid's consolidated history (normalized ratings)
+        - Properly normalizes by total similarity to prevent hub-movie inflation
+        """
+        print(f"Starting genre filter for '{genre}'...")
+        start_time = time.time()
+        # Handle cached home page separately
+        if genre == "All (Cached Home Page)":
+            recs = home_recommendations.get(persona_name, [])
+            title = f"# {persona_name}'s Recommendations"
+            card_updates = update_home_cards_ui(persona_name, recs)
+            print(f"Genre filter '{genre}' completed in {time.time() - start_time:.4f}s (cached)")
+            return [title, gr.update(visible=True), gr.update(visible=False)] + card_updates
+        
+        if not persona_name:
+            return ["# Error: No persona selected", gr.update(visible=False), gr.update(visible=False)] + [gr.update(visible=False)] * 18
+        
+        archetype = persona_archetypes[persona_name]
+        history = archetype['consolidated_history']  # NORMALIZED ratings (-2 to +2 scale)
+        candidate_numerators = {}
+        candidate_denominators = {}
+        
+        for m_id_str, rating in history.items():
+            if rating < 0.5: continue
+            sims = top_similar_items.get(str(m_id_str), {})
+            for sim_id, score in sims.items():
+                if sim_id in history: continue
+                meta = movie_metadata.get(sim_id)
+                if meta and genre in meta['genres']:
+                    candidate_numerators[sim_id] = candidate_numerators.get(sim_id, 0) + (score * rating)
+                    candidate_denominators[sim_id] = candidate_denominators.get(sim_id, 0) + score
+
+        candidate_scores = {
+            m_id: candidate_numerators[m_id] / candidate_denominators[m_id] 
+            for m_id in candidate_numerators if candidate_denominators.get(m_id, 0) > 0
+        }
+
+        sorted_ids = sorted(candidate_scores.items(), key=lambda x: x[1], reverse=True)[:6]
+        time_taken = time.time() - start_time
+        print(f"Genre filter '{genre}' recoomendations completed in {time_taken:.4f}s")
+        
+        # Generate live recommendations with on-the-fly hooks
+        print(f"Starting hook generation for live recommendations for genre {genre}...")
+        start_time = time.time()
+        
+        live_recs = []
+        for m_id, _ in sorted_ids:
+            title = movie_metadata[m_id]['movie_title']
+            hook = generate_hook_on_the_fly(title)
+            live_recs.append({
+                "movie_id": int(m_id), 
+                "movie_title": title,
+                "hook": hook
+            })
+            time.sleep(0.5) # Gentle pause to prevent HF Backend Error 40001
+        
+        time_taken = time.time() - start_time
+        print(f"Hook generation for genre {genre} completed in {time_taken:.4f}s")
+        
+        
+        title_update = f"# {genre} Recommendations for {persona_name}"
+        
+        # Handle no recommendations
+        if not live_recs:
+            return [title_update, gr.update(visible=False), gr.update(visible=True)] + [gr.update()] * 18
+
+        card_updates = update_home_cards_ui(persona_name, live_recs, is_live=True, time_taken=time_taken)
+        return [title_update, gr.update(visible=True), gr.update(visible=False)] + card_updates
+
+    def transition_to_detail_view(movie_id):
+        if not movie_id:
+            return {k: gr.update() for k in detail_outputs}
+            
+        movie_info = movie_metadata[str(movie_id)]
+        poster_url = get_poster_url(movie_info['movie_title'])
+        
+        # Loading spinner HTML
+        loading_html = """
+        <div style="display: flex; align-items: center; justify-content: center; min-height: 200px; width: 100%; flex-direction: column; gap: 1rem; padding: 2rem;">
+            <div class="loader"></div>
+            <p style="color: #1e293b; font-size: 1.1rem; font-weight: 600;">Generating personalized explanation...</p>
+        </div>
+        <style>
+        .loader {
+            border: 4px solid #f3f3f3;
+            border-top: 4px solid #3b82f6;
+            border-radius: 50%;
+            width: 40px;
+            height: 40px;
+            animation: spin 1s linear infinite;
+        }
+        @keyframes spin {
+            0% { transform: rotate(0deg); }
+            100% { transform: rotate(360deg); }
+        }
+        </style>
+        """
+        
+        return {
+            home_view: gr.update(visible=False), 
+            detail_view: gr.update(visible=True), 
+            selected_movie_id: movie_id, 
+            detail_title: f"## {movie_info['movie_title']}", 
+            detail_poster: poster_url, 
+            detail_explanation: loading_html, 
+            detail_fallback_info: gr.update(visible=False)
+        }
+
+    def generate_final_explanation(movie_id, persona_name, style):
+        if not movie_id:
+             return "", gr.update(visible=False)
+        explanation, is_fallback = generate_explanation(movie_id, persona_name, style)
+        return explanation, gr.update(visible=is_fallback)
+
+    def back_to_home():
+        return {home_view: gr.update(visible=True), detail_view: gr.update(visible=False)}
+
+    def back_to_persona_selection():
+        return {persona_view: gr.update(visible=True), home_view: gr.update(visible=False)}
+
+    # Event wiring: Persona buttons
+    for i, button in enumerate(persona_buttons):
+        persona_name = list(persona_archetypes.keys())[i]
+        button.click(lambda name=persona_name: select_persona_and_render_home(name), 
+                    inputs=[], outputs=home_page_outputs)
+
+    # Event wiring: Genre filter
+    genre_dropdown.change(filter_by_genre, 
+                         inputs=[genre_dropdown, selected_persona], 
+                         outputs=[home_title, recommendations_grid, no_recommendations_message] + all_card_outputs)
+    
+    # Event wiring: "See Full Explanation" buttons
+    for card in home_cards:
+        card['btn'].click(transition_to_detail_view, 
+                         inputs=[card['id']], 
+                         outputs=detail_outputs
+        ).then(generate_final_explanation, 
+               inputs=[card['id'], selected_persona, narrative_style], 
+               outputs=[detail_explanation, detail_fallback_info])
+    
+    # Event wiring: Narrative style change
+    def on_style_change(style, movie_id, persona_name):
+        """Callback to regenerate explanation when the narrative style changes."""
+        if not movie_id:
+            return "", gr.update(visible=False)
+        explanation, is_fallback = generate_explanation(movie_id, persona_name, style)
+        return explanation, gr.update(visible=is_fallback)
+
+    narrative_style.change(on_style_change, 
+                          [narrative_style, selected_movie_id, selected_persona], 
+                          [detail_explanation, detail_fallback_info])
+    
+    # Event wiring: Back buttons
+    back_button.click(back_to_home, [], [home_view, detail_view])
+    back_to_persona_button.click(back_to_persona_selection, [], [persona_view, home_view])
+
+if __name__ == "__main__":
+    demo.launch(debug=True)

config.py

@@ -0,0 +1,28 @@
+# config.py
+# This file will store configuration variables, including API keys and prompt constants.
+
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# HuggingFace API token (loaded from .env file)
+HF_TOKEN = os.getenv("HF_TOKEN")
+
+# TMDB API Key (loaded from .env file)
+TMDB_API_KEY = os.getenv("TMDB_API_KEY")
+
+# LLM Model Name (as specified on Hugging Face)
+LLM_MODEL_NAME = "huggingface/meta-llama/Llama-3.2-3B-Instruct"
+#LLM_MODEL_NAME = "ollama/llama3.2"
+
+# Base prompt for LLM explanations
+BASE_PROMPT = """
+Digital Concierge for MovieLens. Explain the recommendation in exactly 3 sentences.
+Max 60 words. Be punchy. Do not start with 'Based on your history'.
+"""
+
+# Injections for narrative styles
+LOGIC_INJECTION = "Focus on technical alignment and genre overlap."
+SOCIAL_INJECTION = "Focus on community acclaim and fan-favorite status."

data/processed/cached_hooks.json

@@ -0,0 +1,26 @@
+{
+    "Action Junkie": {
+        "364": "In the shadows of the Pride Lands, a king reigns.",
+        "6539": "Thirteen curses, one ship, and a pirate's eternal fate awaits.",
+        "8368": "Shadows loom in Hogwarts, a darkness stalks the wizarding world.",
+        "5816": "Shadows stir at Hogwarts, terror prevails in secret chambers.",
+        "8961": "When superheroes disappear, family must use their greatest powers.",
+        "3578": "Felled by empire, reborn by bloodshed in ancient Rome."
+    },
+    "Romantic Dreamer": {
+        "4995": "A brilliant mind shattered by madness, love, and genius.",
+        "6942": "Seven interconnected love stories weave a tender, tangled tapestry together.",
+        "4306": "In a swampy world, an ogre's grumpy heart beats loud.",
+        "899": "Golden Raindrops Fall, Dreams Take Flight in a Sunny Hollywood.",
+        "80549": "High school deception sets off a chain reaction of lies.",
+        "237": "Love, lost, and longing on the City of Light."
+    },
+    "Cinephile Critic": {
+        "2858": "Beauty hides decay, beneath the banality of suburban fa\u00e7ade.",
+        "778": "Addicts, outcasts, and the beauty of Edinburgh's darkest underbelly collide.",
+        "47": "Darkness descends, seven sins ignite a blood-soaked Detroit nightmare.",
+        "4011": "London's underworld unravels in a bloody, hilarious, and twisted game.",
+        "68157": "German cinema is about to meet its bloody demise upstairs.",
+        "2502": "Love, Cubicles, and Rebellion in a Stifling Corporate Hellhole."
+    }
+}

data/processed/home_recommendations.json

@@ -0,0 +1,190 @@
+{
+    "Action Junkie": [
+        {
+            "movie_id": 364,
+            "movie_title": "Lion King, The (1994)",
+            "genres": [
+                "Adventure",
+                "Animation",
+                "Children",
+                "Drama",
+                "Musical",
+                "IMAX"
+            ],
+            "score": 0.37491641553335764
+        },
+        {
+            "movie_id": 6539,
+            "movie_title": "Pirates of the Caribbean: The Curse of the Black Pearl (2003)",
+            "genres": [
+                "Action",
+                "Adventure",
+                "Comedy",
+                "Fantasy"
+            ],
+            "score": 0.34449006856982856
+        },
+        {
+            "movie_id": 8368,
+            "movie_title": "Harry Potter and the Prisoner of Azkaban (2004)",
+            "genres": [
+                "Adventure",
+                "Fantasy",
+                "IMAX"
+            ],
+            "score": 0.3411372816823042
+        },
+        {
+            "movie_id": 5816,
+            "movie_title": "Harry Potter and the Chamber of Secrets (2002)",
+            "genres": [
+                "Adventure",
+                "Fantasy"
+            ],
+            "score": 0.31476111254911127
+        },
+        {
+            "movie_id": 8961,
+            "movie_title": "Incredibles, The (2004)",
+            "genres": [
+                "Action",
+                "Adventure",
+                "Animation",
+                "Children",
+                "Comedy"
+            ],
+            "score": 0.31073810656518414
+        },
+        {
+            "movie_id": 3578,
+            "movie_title": "Gladiator (2000)",
+            "genres": [
+                "Action",
+                "Adventure",
+                "Drama"
+            ],
+            "score": 0.26787650506146904
+        }
+    ],
+    "Romantic Dreamer": [
+        {
+            "movie_id": 4995,
+            "movie_title": "Beautiful Mind, A (2001)",
+            "genres": [
+                "Drama",
+                "Romance"
+            ],
+            "score": 0.1957933962287504
+        },
+        {
+            "movie_id": 6942,
+            "movie_title": "Love Actually (2003)",
+            "genres": [
+                "Comedy",
+                "Drama",
+                "Romance"
+            ],
+            "score": 0.18297972675304644
+        },
+        {
+            "movie_id": 4306,
+            "movie_title": "Shrek (2001)",
+            "genres": [
+                "Adventure",
+                "Animation",
+                "Children",
+                "Comedy",
+                "Fantasy",
+                "Romance"
+            ],
+            "score": 0.12709570186798258
+        },
+        {
+            "movie_id": 899,
+            "movie_title": "Singin' in the Rain (1952)",
+            "genres": [
+                "Comedy",
+                "Musical",
+                "Romance"
+            ],
+            "score": 0.11874943471592653
+        },
+        {
+            "movie_id": 80549,
+            "movie_title": "Easy A (2010)",
+            "genres": [
+                "Comedy",
+                "Romance"
+            ],
+            "score": 0.09955455760645583
+        },
+        {
+            "movie_id": 237,
+            "movie_title": "Forget Paris (1995)",
+            "genres": [
+                "Comedy",
+                "Romance"
+            ],
+            "score": 0.09745981035143099
+        }
+    ],
+    "Cinephile Critic": [
+        {
+            "movie_id": 2858,
+            "movie_title": "American Beauty (1999)",
+            "genres": [
+                "Drama",
+                "Romance"
+            ],
+            "score": 0.5709862785097057
+        },
+        {
+            "movie_id": 778,
+            "movie_title": "Trainspotting (1996)",
+            "genres": [
+                "Comedy",
+                "Crime",
+                "Drama"
+            ],
+            "score": 0.5420799528869238
+        },
+        {
+            "movie_id": 47,
+            "movie_title": "Seven (a.k.a. Se7en) (1995)",
+            "genres": [
+                "Mystery",
+                "Thriller"
+            ],
+            "score": 0.5304661006687574
+        },
+        {
+            "movie_id": 4011,
+            "movie_title": "Snatch (2000)",
+            "genres": [
+                "Comedy",
+                "Crime",
+                "Thriller"
+            ],
+            "score": 0.44253226900550885
+        },
+        {
+            "movie_id": 68157,
+            "movie_title": "Inglourious Basterds (2009)",
+            "genres": [
+                "Action",
+                "Drama",
+                "War"
+            ],
+            "score": 0.4239410030372689
+        },
+        {
+            "movie_id": 2502,
+            "movie_title": "Office Space (1999)",
+            "genres": [
+                "Comedy",
+                "Crime"
+            ],
+            "score": 0.4099722885772744
+        }
+    ]
+}

data/processed/persona_archetypes.json

@@ -0,0 +1,714 @@
+{
+    "Action Junkie": {
+        "specialist_ids": [
+            3,
+            529,
+            388,
+            112,
+            344
+        ],
+        "target_genres": [
+            "Action",
+            "Adventure",
+            "Sci-Fi"
+        ],
+        "consolidated_history": {
+            "1": -0.3961538461538463,
+            "2": -2.0923076923076924,
+            "6": 0.9076923076923076,
+            "7": -1.2000000000000002,
+            "16": 0.9076923076923076,
+            "17": -3.0923076923076924,
+            "19": 0.4076923076923076,
+            "21": -1.5923076923076924,
+            "25": -1.0923076923076924,
+            "31": -1.9358974358974357,
+            "32": 1.6038461538461537,
+            "36": -3.0923076923076924,
+            "39": -3.0923076923076924,
+            "47": 1.4076923076923076,
+            "50": 1.4076923076923076,
+            "62": 0.1038461538461537,
+            "65": -2.2,
+            "95": -0.6461538461538463,
+            "104": 0.1038461538461537,
+            "110": 0.3197881828316611,
+            "135": 0.7999999999999998,
+            "141": 0.1038461538461537,
+            "150": 0.4076923076923076,
+            "161": -2.0923076923076924,
+            "185": -1.5923076923076924,
+            "208": -1.0923076923076924,
+            "223": -2.0923076923076924,
+            "253": 0.9076923076923076,
+            "260": 1.4798587885544408,
+            "288": 0.4076923076923076,
+            "292": 0.4076923076923076,
+            "300": -3.0923076923076924,
+            "316": -0.26811594202898537,
+            "318": 1.2318840579710146,
+            "329": -1.0923076923076924,
+            "339": -2.0923076923076924,
+            "356": 0.5697881828316611,
+            "357": -3.0923076923076924,
+            "380": 1.2318840579710146,
+            "434": -3.0923076923076924,
+            "454": 0.4076923076923076,
+            "480": 1.4076923076923076,
+            "508": 0.9076923076923076,
+            "527": -1.9358974358974357,
+            "551": -0.09230769230769242,
+            "575": -1.6206896551724137,
+            "586": 1.2318840579710146,
+            "593": 0.4076923076923076,
+            "631": -2.6206896551724137,
+            "637": -0.20000000000000018,
+            "647": -1.9358974358974357,
+            "648": -0.20000000000000018,
+            "653": 0.7999999999999998,
+            "661": -0.20000000000000018,
+            "688": -1.9358974358974357,
+            "711": -0.20000000000000018,
+            "719": -1.2000000000000002,
+            "720": -1.9358974358974357,
+            "733": 1.7999999999999998,
+            "736": 0.7659420289855072,
+            "743": -0.20000000000000018,
+            "745": -1.1206896551724137,
+            "761": -2.2,
+            "778": -0.09230769230769242,
+            "780": 1.1038461538461537,
+            "784": -2.2,
+            "786": 1.7999999999999998,
+            "788": -1.1461538461538463,
+            "849": 2.5641025641025643,
+            "914": -1.9358974358974357,
+            "1073": -0.20000000000000018,
+            "1093": -1.9358974358974357,
+            "1124": -1.9358974358974357,
+            "1196": 1.4076923076923076,
+            "1197": 0.3793103448275863,
+            "1198": 1.4076923076923076,
+            "1203": -2.6206896551724137,
+            "1210": 1.319788182831661,
+            "1214": -2.7681159420289854,
+            "1263": -1.9358974358974357,
+            "1265": 1.2318840579710146,
+            "1270": 0.8197881828316611,
+            "1272": -1.9358974358974357,
+            "1275": 1.0641025641025643,
+            "1302": -1.9358974358974357,
+            "1356": 0.4076923076923076,
+            "1371": 0.5641025641025643,
+            "1393": 0.4076923076923076,
+            "1587": 2.0641025641025643,
+            "1703": 0.3793103448275863,
+            "1917": 1.4076923076923076,
+            "2012": 1.2318840579710146,
+            "2018": -1.9358974358974357,
+            "2028": 0.8197881828316611,
+            "2080": -1.9358974358974357,
+            "2090": -1.9358974358974357,
+            "2105": -0.4358974358974357,
+            "2288": 1.5641025641025643,
+            "2346": -1.6206896551724137,
+            "2353": 1.2318840579710146,
+            "2424": -1.9358974358974357,
+            "2541": -1.7681159420289854,
+            "2571": 1.319788182831661,
+            "2617": -1.7681159420289854,
+            "2628": 1.2318840579710146,
+            "2701": 0.7318840579710146,
+            "2712": 0.23188405797101463,
+            "2762": -0.7681159420289854,
+            "2851": 2.5641025641025643,
+            "2858": 1.2318840579710146,
+            "2916": 1.2318840579710146,
+            "3000": 0.7318840579710146,
+            "3024": 2.0641025641025643,
+            "3082": 0.23188405797101463,
+            "3147": 1.319788182831661,
+            "3160": -0.7681159420289854,
+            "3210": -1.9358974358974357,
+            "3703": 2.5641025641025643,
+            "3717": 0.4076923076923076,
+            "3793": 1.2318840579710146,
+            "3897": -0.7681159420289854,
+            "3948": -1.2681159420289854,
+            "3949": -2.6020066889632103,
+            "3996": -0.7681159420289854,
+            "4011": 0.23188405797101463,
+            "4014": -1.2681159420289854,
+            "4022": -0.7681159420289854,
+            "4034": -1.7681159420289854,
+            "4039": -0.6206896551724137,
+            "4226": -2.2681159420289854,
+            "4306": 1.3055972013993005,
+            "4518": 2.5641025641025643,
+            "4720": -2.7681159420289854,
+            "4848": -2.2681159420289854,
+            "4878": -1.7681159420289854,
+            "4973": 0.23188405797101463,
+            "4993": 1.4076923076923076,
+            "5010": -1.7681159420289854,
+            "5048": -1.9358974358974357,
+            "5181": 2.5641025641025643,
+            "5218": 0.8793103448275863,
+            "5299": -2.7681159420289854,
+            "5418": 0.23188405797101463,
+            "5459": 0.7318840579710146,
+            "5502": -2.7681159420289854,
+            "5618": 0.7318840579710146,
+            "5746": 2.5641025641025643,
+            "5764": 2.0641025641025643,
+            "5919": 2.5641025641025643,
+            "5952": 1.4076923076923076,
+            "5989": 0.23188405797101463,
+            "6158": -0.6206896551724137,
+            "6238": -1.9358974358974357,
+            "6377": 0.3793103448275863,
+            "6550": -0.1206896551724137,
+            "6662": -0.1206896551724137,
+            "6835": 2.5641025641025643,
+            "6951": -1.1206896551724137,
+            "7099": 0.7318840579710146,
+            "7153": 1.4076923076923076,
+            "7247": -0.6206896551724137,
+            "7899": 2.0641025641025643,
+            "7991": 2.5641025641025643,
+            "8360": 1.3055972013993005,
+            "8869": -1.1206896551724137,
+            "26409": 2.0641025641025643,
+            "33615": 1.3793103448275863,
+            "34150": 0.23188405797101463,
+            "43836": 0.3793103448275863,
+            "44022": 0.8793103448275863,
+            "53121": 1.3793103448275863,
+            "58559": 1.4076923076923076,
+            "59315": 0.7318840579710146,
+            "60069": -0.26811594202898537,
+            "60684": 1.2318840579710146,
+            "62999": 1.3793103448275863,
+            "63239": -0.6206896551724137,
+            "68157": 0.9076923076923076,
+            "68954": 0.8197881828316611,
+            "70286": -0.09230769230769242,
+            "70946": 2.5641025641025643,
+            "72378": -1.9358974358974357,
+            "72998": 0.4076923076923076,
+            "78637": 1.3793103448275863,
+            "79132": 0.9076923076923076,
+            "81847": 0.23188405797101463,
+            "84152": 1.2318840579710146,
+            "86298": 0.3793103448275863,
+            "86332": 0.23188405797101463,
+            "89745": 0.7318840579710146,
+            "91529": 1.4076923076923076,
+            "91542": 0.23188405797101463,
+            "95105": 1.3793103448275863,
+            "99114": 0.4076923076923076,
+            "103335": 1.3793103448275863,
+            "104245": -0.1206896551724137,
+            "108190": -0.7681159420289854,
+            "109487": 1.4076923076923076,
+            "111362": 1.2318840579710146,
+            "111443": -0.7681159420289854,
+            "111659": -0.7681159420289854,
+            "111759": 0.23188405797101463,
+            "112852": 1.2318840579710146,
+            "114180": -0.7681159420289854,
+            "115617": -0.09230769230769242
+        }
+    },
+    "Romantic Dreamer": {
+        "specialist_ids": [
+            358,
+            461,
+            175,
+            594,
+            578
+        ],
+        "target_genres": [
+            "Romance"
+        ],
+        "consolidated_history": {
+            "2": 0.07543103448275845,
+            "3": 0.07543103448275845,
+            "11": 1.0754310344827585,
+            "17": 0.07543103448275845,
+            "28": 0.5754310344827585,
+            "39": 0.5754310344827585,
+            "46": 0.5754310344827585,
+            "48": 0.5754310344827585,
+            "70": -0.42456896551724155,
+            "110": 1.0754310344827585,
+            "140": 0.5754310344827585,
+            "145": 0.07543103448275845,
+            "150": -0.42456896551724155,
+            "158": 0.5754310344827585,
+            "160": 1.0754310344827585,
+            "165": 0.5754310344827585,
+            "186": 0.3154932950191569,
+            "196": 0.07543103448275845,
+            "204": 0.5754310344827585,
+            "208": 1.0754310344827585,
+            "223": 0.07543103448275845,
+            "252": 1.0754310344827585,
+            "253": -3.4245689655172415,
+            "260": -2.4444444444444446,
+            "270": 0.5754310344827585,
+            "273": -0.9245689655172415,
+            "284": 0.5754310344827585,
+            "289": 0.5754310344827585,
+            "315": 0.5754310344827585,
+            "316": 0.07543103448275845,
+            "317": 0.07543103448275845,
+            "318": 1.5555555555555554,
+            "329": 0.07543103448275845,
+            "339": 1.0754310344827585,
+            "356": 2.0555555555555554,
+            "364": 1.0754310344827585,
+            "367": 0.07543103448275845,
+            "368": 0.07543103448275845,
+            "377": 0.5754310344827585,
+            "380": 0.5754310344827585,
+            "393": 0.5754310344827585,
+            "442": 1.0754310344827585,
+            "457": -0.9345067049808431,
+            "480": -0.6845067049808431,
+            "494": 1.0754310344827585,
+            "497": 0.07543103448275845,
+            "509": 0.07543103448275845,
+            "527": 0.5555555555555554,
+            "531": -0.04166666666666652,
+            "539": 1.065493295019157,
+            "552": 1.0754310344827585,
+            "586": 1.0754310344827585,
+            "587": 1.065493295019157,
+            "588": 0.5754310344827585,
+            "589": 1.0754310344827585,
+            "592": 0.5754310344827585,
+            "593": 1.065493295019157,
+            "594": 0.07543103448275845,
+            "595": 1.0754310344827585,
+            "597": 1.0754310344827585,
+            "605": -0.25609756097560954,
+            "613": -0.9629629629629628,
+            "648": 1.0754310344827585,
+            "653": 1.0754310344827585,
+            "671": -3.0416666666666665,
+            "736": 0.07543103448275845,
+            "762": 0.07543103448275845,
+            "780": 0.5754310344827585,
+            "786": 1.0754310344827585,
+            "799": -3.4245689655172415,
+            "830": 0.0370370370370372,
+            "839": 1.0754310344827585,
+            "858": 0.07543103448275845,
+            "902": 0.7439024390243905,
+            "919": 0.07543103448275845,
+            "920": 0.5754310344827585,
+            "990": 0.5754310344827585,
+            "1036": -0.6845067049808431,
+            "1088": 0.5754310344827585,
+            "1188": 0.5754310344827585,
+            "1208": -0.9245689655172415,
+            "1210": 0.07543103448275845,
+            "1213": 1.0555555555555554,
+            "1214": 0.07543103448275845,
+            "1220": 0.07543103448275845,
+            "1225": 0.07543103448275845,
+            "1240": 1.0754310344827585,
+            "1246": 1.5555555555555554,
+            "1259": 1.0555555555555554,
+            "1307": 1.0754310344827585,
+            "1320": -0.42456896551724155,
+            "1370": 0.5754310344827585,
+            "1393": 1.0754310344827585,
+            "1407": -3.4245689655172415,
+            "1429": 0.07543103448275845,
+            "1457": 0.5754310344827585,
+            "1497": 1.0754310344827585,
+            "1518": -0.42456896551724155,
+            "1527": -0.9245689655172415,
+            "1569": 0.5754310344827585,
+            "1580": 0.5754310344827585,
+            "1605": 0.07543103448275845,
+            "1608": 0.5754310344827585,
+            "1616": 0.5754310344827585,
+            "1626": 0.07543103448275845,
+            "1652": 0.5754310344827585,
+            "1676": 0.5754310344827585,
+            "1687": 0.07543103448275845,
+            "1704": 1.0555555555555554,
+            "1707": 0.07543103448275845,
+            "1721": 1.1596667367535745,
+            "1733": 1.0754310344827585,
+            "1784": 0.3154932950191569,
+            "1835": 1.0754310344827585,
+            "1876": 0.5754310344827585,
+            "1917": 0.5754310344827585,
+            "1923": 0.07543103448275845,
+            "1961": 0.5555555555555554,
+            "1974": -0.42456896551724155,
+            "2000": 0.5754310344827585,
+            "2001": 0.5754310344827585,
+            "2002": 1.0754310344827585,
+            "2028": 0.07543103448275845,
+            "2058": 0.5754310344827585,
+            "2059": 0.07543103448275845,
+            "2125": 0.5754310344827585,
+            "2144": -0.25609756097560954,
+            "2175": 0.5754310344827585,
+            "2196": 1.0754310344827585,
+            "2226": -2.2560975609756095,
+            "2268": 0.07543103448275845,
+            "2269": 1.0754310344827585,
+            "2300": 0.4583333333333335,
+            "2338": -2.2560975609756095,
+            "2340": 0.07543103448275845,
+            "2395": 0.07543103448275845,
+            "2396": 0.40966673675357446,
+            "2424": 1.0754310344827585,
+            "2432": 0.5754310344827585,
+            "2488": -3.4245689655172415,
+            "2491": 0.5754310344827585,
+            "2496": 0.5370370370370372,
+            "2526": -3.0416666666666665,
+            "2571": -0.6845067049808431,
+            "2572": 0.7439024390243905,
+            "2589": -0.42456896551724155,
+            "2617": -0.42456896551724155,
+            "2628": 0.07543103448275845,
+            "2640": 0.07543103448275845,
+            "2671": 1.0754310344827585,
+            "2706": -0.42456896551724155,
+            "2716": 0.07543103448275845,
+            "2717": 0.07543103448275845,
+            "2722": 0.07543103448275845,
+            "2762": 0.5654932950191569,
+            "2807": 1.0754310344827585,
+            "2808": 1.0754310344827585,
+            "2906": 1.0754310344827585,
+            "2985": 0.5754310344827585,
+            "2986": 0.5754310344827585,
+            "3004": 0.5754310344827585,
+            "3081": 0.7439024390243905,
+            "3147": 1.0555555555555554,
+            "3155": 0.5370370370370372,
+            "3257": 1.0754310344827585,
+            "3269": 0.5754310344827585,
+            "3353": 0.5754310344827585,
+            "3578": -0.9345067049808431,
+            "3594": 1.4583333333333335,
+            "3616": 0.5754310344827585,
+            "3791": 1.4583333333333335,
+            "3793": 0.5754310344827585,
+            "3824": 0.5754310344827585,
+            "3882": -0.25609756097560954,
+            "3948": 0.5754310344827585,
+            "3969": 0.9583333333333335,
+            "4025": 1.0754310344827585,
+            "4054": 0.5754310344827585,
+            "4069": 1.0754310344827585,
+            "4155": 1.0754310344827585,
+            "4200": 0.5754310344827585,
+            "4270": 0.5754310344827585,
+            "4308": 0.7439024390243905,
+            "4374": 0.5754310344827585,
+            "4517": -3.4245689655172415,
+            "4715": -0.9245689655172415,
+            "4748": 0.5754310344827585,
+            "4794": -3.4245689655172415,
+            "4823": 1.0754310344827585,
+            "4827": -0.9245689655172415,
+            "4902": -3.4245689655172415,
+            "4991": 0.07543103448275845,
+            "5066": 1.4096667367535745,
+            "5092": -0.4629629629629628,
+            "5105": -3.4245689655172415,
+            "5151": 0.5754310344827585,
+            "5299": -0.42456896551724155,
+            "5308": 1.0754310344827585,
+            "5309": 0.5370370370370372,
+            "5364": 0.5754310344827585,
+            "5409": 0.07543103448275845,
+            "5410": -3.0416666666666665,
+            "5527": 0.5754310344827585,
+            "5620": 0.5754310344827585,
+            "5657": 0.5754310344827585,
+            "5909": -3.4245689655172415,
+            "5943": 0.5754310344827585,
+            "5957": 1.0754310344827585,
+            "6006": 1.0754310344827585,
+            "6140": -3.4245689655172415,
+            "6148": -1.9245689655172415,
+            "6155": 1.0754310344827585,
+            "6287": 0.07543103448275845,
+            "6333": 0.5754310344827585,
+            "6373": 1.0754310344827585,
+            "6417": 0.07543103448275845,
+            "6549": 1.0754310344827585,
+            "6577": 0.07543103448275845,
+            "6639": -3.4245689655172415,
+            "6659": -1.9245689655172415,
+            "6665": 0.5754310344827585,
+            "6723": 0.07543103448275845,
+            "6751": -1.4629629629629628,
+            "6754": 1.0754310344827585,
+            "6765": 1.0754310344827585,
+            "6793": 0.07543103448275845,
+            "6967": -3.4245689655172415,
+            "6975": -3.4245689655172415,
+            "6994": 1.0754310344827585,
+            "6996": 0.07543103448275845,
+            "7017": 1.0754310344827585,
+            "7023": 0.5754310344827585,
+            "7031": 0.07543103448275845,
+            "7032": 0.07543103448275845,
+            "7046": -2.943765964240102,
+            "7101": -0.42456896551724155,
+            "7114": -3.4245689655172415,
+            "7115": -3.4245689655172415,
+            "7116": -3.4245689655172415,
+            "7149": 0.5754310344827585,
+            "7169": 1.266882183908046,
+            "7254": 0.24390243902439046,
+            "7255": 0.7439024390243905,
+            "7259": -0.04166666666666652,
+            "7293": 0.7439024390243905,
+            "7320": 0.5754310344827585,
+            "7323": 0.0370370370370372,
+            "7345": 0.07543103448275845,
+            "7361": 0.7439024390243905,
+            "7373": -3.4245689655172415,
+            "7395": 0.0370370370370372,
+            "7450": 0.5754310344827585,
+            "7564": -3.4245689655172415,
+            "7650": -3.4245689655172415,
+            "7742": -3.4245689655172415,
+            "7782": 0.5754310344827585,
+            "7883": -3.4245689655172415,
+            "7982": -3.4245689655172415,
+            "8035": -3.4245689655172415,
+            "8118": 0.07543103448275845,
+            "8132": 0.5754310344827585,
+            "8268": 0.5754310344827585,
+            "8362": -0.04166666666666652,
+            "8482": -3.4245689655172415,
+            "8521": -3.4245689655172415,
+            "8533": 0.785456836848062,
+            "8620": -3.4245689655172415,
+            "8636": 1.0754310344827585,
+            "8643": 1.016882183908046,
+            "8727": -1.9245689655172415,
+            "8778": 0.07543103448275845,
+            "8866": 0.5754310344827585,
+            "8869": 1.0754310344827585,
+            "8911": 1.4583333333333335,
+            "26095": -2.7560975609756095,
+            "31433": 0.5754310344827585,
+            "32289": 1.4583333333333335,
+            "33145": -0.04166666666666652,
+            "33679": -1.2560975609756095,
+            "33880": -0.04166666666666652,
+            "36525": 0.7439024390243905,
+            "38388": 1.4583333333333335,
+            "39427": -3.0416666666666665,
+            "42728": 1.7439024390243905,
+            "43904": -3.0416666666666665,
+            "44613": 1.4583333333333335,
+            "45668": 1.0370370370370372,
+            "45720": 0.5370370370370372,
+            "45880": 0.4583333333333335,
+            "47382": 1.4583333333333335,
+            "47610": 1.2439024390243905,
+            "48412": 0.24390243902439046,
+            "49130": 0.7439024390243905,
+            "49772": 1.0370370370370372,
+            "52328": 0.7439024390243905,
+            "52668": 0.0370370370370372,
+            "55052": 1.7439024390243905,
+            "56389": 0.0370370370370372,
+            "56715": 0.7439024390243905,
+            "56949": 0.4583333333333335,
+            "58107": 0.4583333333333335,
+            "58154": 0.5370370370370372,
+            "58998": -2.2560975609756095,
+            "60069": 0.7439024390243905,
+            "65350": -2.7560975609756095,
+            "66203": 0.7439024390243905,
+            "68157": -2.4444444444444446,
+            "68269": 0.5370370370370372,
+            "69757": 1.2439024390243905,
+            "69844": 0.24390243902439046,
+            "70599": 1.2439024390243905,
+            "70687": -2.2560975609756095,
+            "71579": 0.7439024390243905,
+            "71823": 0.5370370370370372,
+            "72407": -0.4629629629629628,
+            "73017": 1.0370370370370372,
+            "74458": 1.0555555555555554,
+            "75446": -1.4629629629629628,
+            "76251": 0.5370370370370372,
+            "78316": 0.0370370370370372,
+            "79879": -3.462962962962963,
+            "81562": 1.0370370370370372,
+            "81591": -1.2560975609756095,
+            "81845": 1.0370370370370372,
+            "85334": -2.7560975609756095,
+            "87028": -1.2560975609756095,
+            "88163": 0.7439024390243905,
+            "89386": -2.7560975609756095,
+            "91500": -2.4444444444444446,
+            "99114": 1.5555555555555554,
+            "104841": -2.4444444444444446,
+            "106782": 2.0555555555555554
+        }
+    },
+    "Cinephile Critic": {
+        "specialist_ids": [
+            338,
+            549,
+            296,
+            473,
+            394
+        ],
+        "target_genres": [
+            "Drama",
+            "Crime",
+            "Mystery",
+            "Thriller"
+        ],
+        "consolidated_history": {
+            "34": 0.04347826086956541,
+            "50": 1.4803047194351542,
+            "60": -1.4189189189189189,
+            "110": 0.7367149758454107,
+            "150": 0.04347826086956541,
+            "153": 0.04347826086956541,
+            "185": 0.04347826086956541,
+            "208": -1.9565217391304346,
+            "225": 1.0434782608695654,
+            "260": -1.6666666666666665,
+            "262": 0.08108108108108114,
+            "293": 0.9572072072072073,
+            "296": 0.9487179487179487,
+            "316": -0.9565217391304346,
+            "318": 1.202962577962578,
+            "339": 0.04347826086956541,
+            "344": -0.9565217391304346,
+            "356": 0.9384057971014492,
+            "367": 0.04347826086956541,
+            "380": 0.04347826086956541,
+            "410": -0.9565217391304346,
+            "454": -0.9565217391304346,
+            "457": 1.0434782608695654,
+            "480": 0.04347826086956541,
+            "527": -0.08974358974358972,
+            "553": 1.0434782608695654,
+            "588": -0.9565217391304346,
+            "589": -0.6666666666666665,
+            "590": -0.9565217391304346,
+            "592": 0.04347826086956541,
+            "593": 1.0641025641025643,
+            "595": -0.9565217391304346,
+            "858": 1.5641025641025643,
+            "1036": 0.3333333333333335,
+            "1196": -1.6666666666666665,
+            "1198": 0.8333333333333335,
+            "1201": 0.833333333333333,
+            "1203": 2.0641025641025643,
+            "1210": -1.6666666666666665,
+            "1221": 2.0641025641025643,
+            "1291": -0.6666666666666665,
+            "1704": 0.833333333333333,
+            "1760": -2.918918918918919,
+            "1895": -1.4189189189189189,
+            "2028": 0.8333333333333333,
+            "2136": -2.418918918918919,
+            "2253": -0.9189189189189189,
+            "2297": -0.41891891891891886,
+            "2300": -0.9189189189189189,
+            "2324": 0.833333333333333,
+            "2329": 1.0810810810810811,
+            "2485": -0.9189189189189189,
+            "2571": 0.8333333333333333,
+            "2581": -0.41891891891891886,
+            "2596": 0.5810810810810811,
+            "2628": -3.166666666666667,
+            "2959": 1.077962577962578,
+            "3264": -1.4189189189189189,
+            "3897": 1.5810810810810811,
+            "3988": -1.4189189189189189,
+            "4144": 0.833333333333333,
+            "4226": 1.3333333333333335,
+            "4873": 0.5810810810810811,
+            "4878": 0.5810810810810811,
+            "4880": 0.08108108108108114,
+            "4975": 0.5810810810810811,
+            "4979": 1.0810810810810811,
+            "5349": 0.06410256410256432,
+            "5378": -3.166666666666667,
+            "5445": -0.9358974358974357,
+            "5618": 0.33333333333333304,
+            "5785": 0.08108108108108114,
+            "5952": -0.0512820512820511,
+            "6281": -1.4189189189189189,
+            "6874": 1.5641025641025643,
+            "7147": 0.5810810810810811,
+            "7153": -0.4358974358974357,
+            "7156": 0.33333333333333304,
+            "7361": 1.5810810810810811,
+            "8784": 1.0641025641025643,
+            "8957": 0.5810810810810811,
+            "27773": 1.0641025641025643,
+            "27904": 0.5810810810810811,
+            "30749": 0.5641025641025643,
+            "30793": -0.4358974358974357,
+            "30810": 1.0810810810810811,
+            "31364": 0.833333333333333,
+            "33493": -3.166666666666667,
+            "34405": 0.5641025641025643,
+            "36535": 0.5810810810810811,
+            "40614": 0.08108108108108114,
+            "45501": 0.08108108108108114,
+            "46578": 1.0810810810810811,
+            "48082": 0.5810810810810811,
+            "48322": 0.08108108108108114,
+            "48385": 0.08108108108108114,
+            "48394": 0.33333333333333304,
+            "48516": 1.3333333333333335,
+            "58559": 0.3333333333333335,
+            "65261": 0.833333333333333,
+            "79132": 1.0833333333333333,
+            "122912": -1.4358974358974357,
+            "122916": -1.9358974358974357,
+            "122924": 1.3333333333333335,
+            "158813": -2.6666666666666665,
+            "160848": 0.33333333333333304,
+            "166528": -2.166666666666667,
+            "169034": 0.33333333333333304,
+            "170705": -0.4358974358974357,
+            "171765": -0.666666666666667,
+            "174053": 2.0641025641025643,
+            "175569": -1.4358974358974357,
+            "176371": -1.9358974358974357,
+            "177593": 2.0641025641025643,
+            "177765": -0.4358974358974357,
+            "180031": -0.666666666666667,
+            "183897": -1.4358974358974357,
+            "185029": -1.9358974358974357,
+            "187541": -1.9358974358974357,
+            "187593": -1.9358974358974357,
+            "189043": -0.4358974358974357,
+            "189111": 0.06410256410256432,
+            "190207": -1.4358974358974357,
+            "190209": 1.0641025641025643,
+            "190213": -1.9358974358974357,
+            "190215": -1.4358974358974357,
+            "190219": -1.9358974358974357,
+            "190221": -1.9358974358974357
+        }
+    }
+}

data/processed/top_similar_items.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0fe6573811e76b714860e29df2874b71e8ed224054197f4770f0323823765555
+size 440321

data/processed/user_avg_ratings.json

@@ -0,0 +1,612 @@
+{
+    "1": 4.366379310344827,
+    "2": 3.9482758620689653,
+    "3": 2.4358974358974357,
+    "4": 3.5555555555555554,
+    "5": 3.6363636363636362,
+    "6": 3.4936305732484074,
+    "7": 3.2302631578947367,
+    "8": 3.574468085106383,
+    "9": 3.260869565217391,
+    "10": 3.2785714285714285,
+    "11": 3.78125,
+    "12": 4.390625,
+    "13": 3.6451612903225805,
+    "14": 3.3958333333333335,
+    "15": 3.448148148148148,
+    "16": 3.7244897959183674,
+    "17": 4.20952380952381,
+    "18": 3.7320717131474104,
+    "19": 2.607396870554765,
+    "20": 3.590909090909091,
+    "21": 3.260722347629797,
+    "22": 2.5714285714285716,
+    "23": 3.6487603305785123,
+    "24": 3.65,
+    "25": 4.8076923076923075,
+    "26": 3.238095238095238,
+    "27": 3.5481481481481483,
+    "28": 3.020175438596491,
+    "29": 4.1419753086419755,
+    "30": 4.735294117647059,
+    "31": 3.92,
+    "32": 3.7549019607843137,
+    "33": 3.7884615384615383,
+    "34": 3.4186046511627906,
+    "35": 4.086956521739131,
+    "36": 2.6333333333333333,
+    "37": 4.142857142857143,
+    "38": 3.217948717948718,
+    "39": 4.0,
+    "40": 3.766990291262136,
+    "41": 3.2534562211981566,
+    "42": 3.565909090909091,
+    "43": 4.552631578947368,
+    "44": 3.3541666666666665,
+    "45": 3.8759398496240602,
+    "46": 4.0,
+    "47": 3.0535714285714284,
+    "48": 4.03030303030303,
+    "49": 4.261904761904762,
+    "50": 2.7806451612903227,
+    "51": 3.7757660167130918,
+    "52": 4.476923076923077,
+    "53": 5.0,
+    "54": 3.0303030303030303,
+    "55": 2.84,
+    "56": 3.8043478260869565,
+    "57": 3.392857142857143,
+    "58": 3.9017857142857144,
+    "59": 4.355140186915888,
+    "60": 3.727272727272727,
+    "61": 4.051282051282051,
+    "62": 4.081967213114754,
+    "63": 3.6309963099630997,
+    "64": 3.7688588007736943,
+    "65": 4.029411764705882,
+    "66": 4.0202898550724635,
+    "67": 3.9722222222222223,
+    "68": 3.233730158730159,
+    "69": 4.369565217391305,
+    "70": 4.32258064516129,
+    "71": 3.6,
+    "72": 4.155555555555556,
+    "73": 3.711904761904762,
+    "74": 4.271186440677966,
+    "75": 3.2318840579710146,
+    "76": 3.0840336134453783,
+    "77": 4.0,
+    "78": 3.1639344262295084,
+    "79": 4.203125,
+    "80": 4.2604790419161676,
+    "81": 2.769230769230769,
+    "82": 3.381057268722467,
+    "83": 3.309322033898305,
+    "84": 3.689419795221843,
+    "85": 3.7058823529411766,
+    "86": 3.9285714285714284,
+    "87": 3.9523809523809526,
+    "88": 4.035714285714286,
+    "89": 3.472972972972973,
+    "90": 4.074074074074074,
+    "91": 3.3956521739130436,
+    "92": 3.9375,
+    "93": 4.288659793814433,
+    "94": 3.0357142857142856,
+    "95": 4.0625,
+    "96": 3.8846153846153846,
+    "97": 4.194444444444445,
+    "98": 3.9130434782608696,
+    "99": 3.8679245283018866,
+    "100": 3.945945945945946,
+    "101": 3.557377049180328,
+    "102": 3.357142857142857,
+    "103": 3.907161803713528,
+    "104": 3.5073260073260073,
+    "105": 4.116343490304709,
+    "106": 4.4393939393939394,
+    "107": 3.911764705882353,
+    "108": 3.986842105263158,
+    "109": 3.220472440944882,
+    "110": 3.7254901960784315,
+    "111": 3.3397832817337463,
+    "112": 3.5923076923076924,
+    "113": 3.6466666666666665,
+    "114": 3.435483870967742,
+    "115": 3.767857142857143,
+    "116": 3.4367816091954024,
+    "117": 3.3393939393939394,
+    "118": 3.8181818181818183,
+    "119": 4.176744186046512,
+    "120": 3.409090909090909,
+    "121": 3.293103448275862,
+    "122": 4.546232876712328,
+    "123": 4.035714285714286,
+    "124": 3.99,
+    "125": 3.859722222222222,
+    "126": 3.289473684210526,
+    "127": 3.1136363636363638,
+    "128": 4.363636363636363,
+    "129": 3.9214285714285713,
+    "130": 3.5357142857142856,
+    "131": 3.4420289855072466,
+    "132": 3.0389048991354466,
+    "133": 3.0,
+    "134": 3.5714285714285716,
+    "135": 3.630824372759857,
+    "136": 3.315315315315315,
+    "137": 3.978723404255319,
+    "138": 3.522727272727273,
+    "139": 2.1443298969072164,
+    "140": 3.4991776315789473,
+    "141": 3.5386904761904763,
+    "142": 3.8157894736842106,
+    "143": 3.323943661971831,
+    "144": 3.62890625,
+    "145": 3.347826086956522,
+    "146": 3.140625,
+    "147": 3.375,
+    "148": 3.7395833333333335,
+    "149": 2.7241379310344827,
+    "150": 3.576923076923077,
+    "151": 3.542372881355932,
+    "152": 4.023809523809524,
+    "153": 2.217877094972067,
+    "154": 4.382352941176471,
+    "155": 3.608695652173913,
+    "156": 3.692211055276382,
+    "157": 3.4761904761904763,
+    "158": 3.423076923076923,
+    "159": 3.2731958762886597,
+    "160": 2.708237986270023,
+    "161": 3.8333333333333335,
+    "162": 4.2368421052631575,
+    "163": 3.0,
+    "164": 4.25,
+    "165": 3.5384615384615383,
+    "166": 4.073684210526316,
+    "167": 3.439306358381503,
+    "168": 4.462765957446808,
+    "169": 4.24907063197026,
+    "170": 3.34,
+    "171": 4.634146341463414,
+    "172": 3.826923076923077,
+    "173": 3.48,
+    "174": 3.656716417910448,
+    "175": 3.5416666666666665,
+    "176": 4.055555555555555,
+    "177": 3.375553097345133,
+    "178": 4.090909090909091,
+    "179": 3.782608695652174,
+    "180": 3.5625,
+    "181": 2.940677966101695,
+    "182": 3.5112589559877176,
+    "183": 3.824561403508772,
+    "184": 3.705223880597015,
+    "185": 3.5319148936170213,
+    "186": 4.079646017699115,
+    "187": 3.7751937984496124,
+    "188": 4.395833333333333,
+    "189": 4.1,
+    "190": 3.909090909090909,
+    "191": 3.7411764705882353,
+    "192": 4.045454545454546,
+    "193": 3.8,
+    "194": 3.475,
+    "195": 3.5294117647058822,
+    "196": 3.9375,
+    "197": 3.857142857142857,
+    "198": 3.491304347826087,
+    "199": 3.3953168044077136,
+    "200": 3.809880239520958,
+    "201": 4.1,
+    "202": 3.8188585607940446,
+    "203": 3.8444444444444446,
+    "204": 3.9578313253012047,
+    "205": 3.8703703703703702,
+    "206": 4.04,
+    "207": 2.875,
+    "208": 3.3076923076923075,
+    "209": 4.242857142857143,
+    "210": 4.079710144927536,
+    "211": 3.904494382022472,
+    "212": 3.590725806451613,
+    "213": 3.8273809523809526,
+    "214": 2.8636363636363638,
+    "215": 3.9081632653061225,
+    "216": 3.6646341463414633,
+    "217": 2.761827079934747,
+    "218": 3.3653846153846154,
+    "219": 3.165719696969697,
+    "220": 3.963768115942029,
+    "221": 4.126888217522659,
+    "222": 3.166,
+    "223": 3.2733333333333334,
+    "224": 4.2592592592592595,
+    "225": 3.6533333333333333,
+    "226": 3.4763313609467454,
+    "227": 4.202127659574468,
+    "228": 3.74,
+    "229": 3.7384615384615385,
+    "230": 2.8597122302158273,
+    "231": 3.8541666666666665,
+    "232": 3.2505800464037122,
+    "233": 3.3,
+    "234": 3.504950495049505,
+    "235": 3.646153846153846,
+    "236": 3.966666666666667,
+    "237": 3.36,
+    "238": 3.6818181818181817,
+    "239": 4.026881720430108,
+    "240": 3.9140625,
+    "241": 3.9802631578947367,
+    "242": 3.6,
+    "243": 4.138888888888889,
+    "244": 3.774193548387097,
+    "245": 2.7142857142857144,
+    "246": 4.252450980392157,
+    "247": 3.7466666666666666,
+    "248": 3.7450980392156863,
+    "249": 3.6964627151051626,
+    "250": 4.222222222222222,
+    "251": 4.869565217391305,
+    "252": 4.197368421052632,
+    "253": 4.351063829787234,
+    "254": 3.9803149606299213,
+    "255": 2.5681818181818183,
+    "256": 3.9454022988505746,
+    "257": 3.2,
+    "258": 4.2,
+    "259": 3.1206896551724137,
+    "260": 3.7598684210526314,
+    "261": 3.858490566037736,
+    "262": 3.1052631578947367,
+    "263": 3.716666666666667,
+    "264": 3.5625,
+    "265": 3.3496932515337425,
+    "266": 3.5,
+    "267": 4.175438596491228,
+    "268": 3.2713178294573644,
+    "269": 3.6206896551724137,
+    "270": 3.2,
+    "271": 3.186046511627907,
+    "272": 3.629032258064516,
+    "273": 4.0,
+    "274": 3.235884101040119,
+    "275": 4.086848635235732,
+    "276": 4.390243902439025,
+    "277": 3.5714285714285716,
+    "278": 3.875,
+    "279": 3.647727272727273,
+    "280": 3.9005102040816326,
+    "281": 3.2142857142857144,
+    "282": 4.033755274261603,
+    "283": 3.3142857142857145,
+    "284": 3.715909090909091,
+    "285": 3.9583333333333335,
+    "286": 3.7877358490566038,
+    "287": 2.6217105263157894,
+    "288": 3.1459715639810426,
+    "289": 3.625,
+    "290": 4.142322097378277,
+    "291": 4.258064516129032,
+    "292": 3.3015695067264574,
+    "293": 2.619047619047619,
+    "294": 2.610983981693364,
+    "295": 3.7439024390243905,
+    "296": 4.166666666666667,
+    "297": 2.5972222222222223,
+    "298": 2.363684771033014,
+    "299": 3.652173913043478,
+    "300": 4.296875,
+    "301": 3.3201754385964914,
+    "302": 4.0,
+    "303": 3.9056603773584904,
+    "304": 3.8703703703703702,
+    "305": 3.9246676514032495,
+    "306": 3.3169642857142856,
+    "307": 2.6656410256410257,
+    "308": 2.4260869565217393,
+    "309": 3.8398058252427183,
+    "310": 3.53125,
+    "311": 2.3392857142857144,
+    "312": 3.708520179372197,
+    "313": 3.4323529411764704,
+    "314": 3.046875,
+    "315": 3.3636363636363638,
+    "316": 3.0,
+    "317": 3.7301587301587302,
+    "318": 3.755972696245734,
+    "319": 4.428571428571429,
+    "320": 3.525,
+    "321": 3.5714285714285716,
+    "322": 3.411214953271028,
+    "323": 3.173469387755102,
+    "324": 3.142857142857143,
+    "325": 3.5444444444444443,
+    "326": 4.016447368421052,
+    "327": 4.104166666666667,
+    "328": 3.2254901960784315,
+    "329": 2.869565217391304,
+    "330": 3.6902834008097165,
+    "331": 3.6279761904761907,
+    "332": 3.599250936329588,
+    "333": 2.64,
+    "334": 3.418831168831169,
+    "335": 3.6785714285714284,
+    "336": 4.321428571428571,
+    "337": 4.207792207792208,
+    "338": 2.9358974358974357,
+    "339": 4.070080862533692,
+    "340": 4.214285714285714,
+    "341": 3.798076923076923,
+    "342": 2.9393939393939394,
+    "343": 4.059322033898305,
+    "344": 3.7681159420289854,
+    "345": 3.903225806451613,
+    "346": 3.682926829268293,
+    "347": 3.5555555555555554,
+    "348": 4.672727272727273,
+    "349": 3.72972972972973,
+    "350": 3.25,
+    "351": 3.6666666666666665,
+    "352": 3.7806122448979593,
+    "353": 3.488888888888889,
+    "354": 3.734513274336283,
+    "355": 3.8846153846153846,
+    "356": 4.02076124567474,
+    "357": 3.9569190600522193,
+    "358": 3.2560975609756095,
+    "359": 3.418918918918919,
+    "360": 3.36,
+    "361": 3.1804123711340204,
+    "362": 4.243119266055046,
+    "363": 3.3,
+    "364": 4.190476190476191,
+    "365": 2.7509025270758123,
+    "366": 3.9516129032258065,
+    "367": 3.8594594594594596,
+    "368": 2.8422174840085286,
+    "369": 3.391472868217054,
+    "370": 3.5483870967741935,
+    "371": 4.548780487804878,
+    "372": 3.3559322033898304,
+    "373": 3.19,
+    "374": 3.6363636363636362,
+    "375": 3.909090909090909,
+    "376": 4.06390977443609,
+    "377": 3.9122137404580153,
+    "378": 4.0,
+    "379": 3.388888888888889,
+    "380": 3.6732348111658455,
+    "381": 3.542194092827004,
+    "382": 3.508591065292096,
+    "383": 3.7941176470588234,
+    "384": 3.085714285714286,
+    "385": 3.4029850746268657,
+    "386": 2.75,
+    "387": 3.2585199610516065,
+    "388": 3.6206896551724137,
+    "389": 4.117647058823529,
+    "390": 3.8395061728395063,
+    "391": 3.715025906735751,
+    "392": 3.2,
+    "393": 3.841463414634146,
+    "394": 2.9565217391304346,
+    "395": 3.0491803278688523,
+    "396": 3.142857142857143,
+    "397": 3.9565217391304346,
+    "398": 4.25,
+    "399": 3.9444444444444446,
+    "400": 4.511627906976744,
+    "401": 3.5277777777777777,
+    "402": 3.8541666666666665,
+    "403": 3.764705882352941,
+    "404": 3.4,
+    "405": 4.008333333333334,
+    "406": 3.25,
+    "407": 4.113636363636363,
+    "408": 4.092198581560283,
+    "409": 3.8412698412698414,
+    "410": 4.059880239520958,
+    "411": 3.2598425196850394,
+    "412": 3.892156862745098,
+    "413": 4.410714285714286,
+    "414": 3.391957005189029,
+    "415": 4.085106382978723,
+    "416": 3.0686274509803924,
+    "417": 4.462686567164179,
+    "418": 3.639784946236559,
+    "419": 3.803225806451613,
+    "420": 3.8226950354609928,
+    "421": 4.108108108108108,
+    "422": 3.3225806451612905,
+    "423": 3.717391304347826,
+    "424": 3.6739130434782608,
+    "425": 3.5326797385620914,
+    "426": 3.6818181818181817,
+    "427": 3.1011904761904763,
+    "428": 2.64,
+    "429": 3.9827586206896552,
+    "430": 3.7413793103448274,
+    "431": 2.725,
+    "432": 3.646153846153846,
+    "433": 3.772727272727273,
+    "434": 3.781115879828326,
+    "435": 4.321428571428571,
+    "436": 3.1792452830188678,
+    "437": 3.80327868852459,
+    "438": 3.3551181102362206,
+    "439": 4.119047619047619,
+    "440": 3.893939393939394,
+    "441": 4.522222222222222,
+    "442": 1.275,
+    "443": 4.121621621621622,
+    "444": 3.8095238095238093,
+    "445": 3.857142857142857,
+    "446": 3.2142857142857144,
+    "447": 3.871794871794872,
+    "448": 2.8473712446351933,
+    "449": 3.289473684210526,
+    "450": 4.0,
+    "451": 3.7941176470588234,
+    "452": 4.556930693069307,
+    "453": 3.942122186495177,
+    "454": 3.7666666666666666,
+    "455": 3.456140350877193,
+    "456": 3.813953488372093,
+    "457": 3.46,
+    "458": 4.1525423728813555,
+    "459": 4.346153846153846,
+    "460": 4.201219512195122,
+    "461": 2.9444444444444446,
+    "462": 3.4065934065934065,
+    "463": 3.787878787878788,
+    "464": 3.753623188405797,
+    "465": 4.156521739130435,
+    "466": 3.9292035398230087,
+    "467": 3.409090909090909,
+    "468": 3.393939393939394,
+    "469": 3.6731182795698927,
+    "470": 3.5125,
+    "471": 3.875,
+    "472": 4.120689655172414,
+    "473": 3.418918918918919,
+    "474": 3.398956356736243,
+    "475": 4.409677419354839,
+    "476": 3.681159420289855,
+    "477": 3.736666666666667,
+    "478": 2.8181818181818183,
+    "479": 3.320441988950276,
+    "480": 3.27511961722488,
+    "481": 2.806451612903226,
+    "482": 3.40625,
+    "483": 3.618818681318681,
+    "484": 3.8145454545454545,
+    "485": 3.869565217391304,
+    "486": 4.017857142857143,
+    "487": 3.142857142857143,
+    "488": 3.8828828828828827,
+    "489": 3.017746913580247,
+    "490": 3.15929203539823,
+    "491": 4.15625,
+    "492": 3.8677685950413223,
+    "493": 3.6885245901639343,
+    "494": 4.2272727272727275,
+    "495": 4.009433962264151,
+    "496": 3.413793103448276,
+    "497": 3.5686274509803924,
+    "498": 4.057142857142857,
+    "499": 3.8333333333333335,
+    "500": 3.244186046511628,
+    "501": 3.2,
+    "502": 3.4285714285714284,
+    "503": 3.3421052631578947,
+    "504": 3.82183908045977,
+    "505": 4.17741935483871,
+    "506": 3.261904761904762,
+    "507": 3.380952380952381,
+    "508": 2.1458333333333335,
+    "509": 3.21627408993576,
+    "510": 2.9027777777777777,
+    "511": 4.125,
+    "512": 3.78,
+    "513": 3.890625,
+    "514": 3.3110831234256928,
+    "515": 4.846153846153846,
+    "516": 3.6923076923076925,
+    "517": 2.38625,
+    "518": 3.5416666666666665,
+    "519": 4.326923076923077,
+    "520": 3.881720430107527,
+    "521": 3.6,
+    "522": 3.83,
+    "523": 4.693333333333333,
+    "524": 3.4580152671755724,
+    "525": 3.542,
+    "526": 4.189655172413793,
+    "527": 4.119760479041916,
+    "528": 3.4726027397260273,
+    "529": 3.2,
+    "530": 3.7777777777777777,
+    "531": 3.772727272727273,
+    "532": 4.28,
+    "533": 4.381578947368421,
+    "534": 3.8048076923076923,
+    "535": 2.6666666666666665,
+    "536": 3.4,
+    "537": 4.0638297872340425,
+    "538": 4.472972972972973,
+    "539": 3.8026315789473686,
+    "540": 4.0,
+    "541": 3.3908045977011496,
+    "542": 3.5088495575221237,
+    "543": 4.453947368421052,
+    "544": 4.363636363636363,
+    "545": 3.369565217391304,
+    "546": 3.4375,
+    "547": 4.142857142857143,
+    "548": 4.096153846153846,
+    "549": 3.6666666666666665,
+    "550": 4.107142857142857,
+    "551": 3.7154471544715446,
+    "552": 3.11968085106383,
+    "553": 4.337349397590361,
+    "554": 4.0,
+    "555": 3.4550173010380623,
+    "556": 4.078125,
+    "557": 3.8518518518518516,
+    "558": 3.9285714285714284,
+    "559": 3.2857142857142856,
+    "560": 3.567685589519651,
+    "561": 3.372277227722772,
+    "562": 4.093073593073593,
+    "563": 3.300469483568075,
+    "564": 3.5796178343949046,
+    "565": 3.6551724137931036,
+    "566": 3.5405405405405403,
+    "567": 2.2454545454545456,
+    "568": 4.130434782608695,
+    "569": 4.0,
+    "570": 3.4162303664921465,
+    "571": 2.5714285714285716,
+    "572": 4.122580645161291,
+    "573": 4.212374581939799,
+    "574": 3.9565217391304346,
+    "575": 3.1666666666666665,
+    "576": 3.1,
+    "577": 3.5652173913043477,
+    "578": 3.962962962962963,
+    "579": 3.9726027397260273,
+    "580": 3.529816513761468,
+    "581": 4.375,
+    "582": 4.026785714285714,
+    "583": 3.294642857142857,
+    "584": 4.108433734939759,
+    "585": 4.336065573770492,
+    "586": 4.365384615384615,
+    "587": 3.9757575757575756,
+    "588": 3.25,
+    "589": 4.025,
+    "590": 3.355769230769231,
+    "591": 3.2777777777777777,
+    "592": 3.5851063829787235,
+    "593": 3.266990291262136,
+    "594": 3.9245689655172415,
+    "595": 4.2,
+    "596": 3.495133819951338,
+    "597": 3.9774266365688487,
+    "598": 3.8095238095238093,
+    "599": 2.6420500403551253,
+    "600": 2.991480996068152,
+    "601": 4.425742574257426,
+    "602": 3.3925925925925924,
+    "603": 3.5079533404029695,
+    "604": 3.48,
+    "605": 3.2104072398190047,
+    "606": 3.6573991031390136,
+    "607": 3.786096256684492,
+    "608": 3.1341756919374246,
+    "609": 3.27027027027027,
+    "610": 3.6885560675883258
+}

data_prep.py

@@ -0,0 +1,339 @@
+# data_prep.py - COMPLETE ARCHETYPE EDITION
+# Integrates: 20-rating threshold, Recency Bias Penalty, and Specialist Centroid Logic.
+
+import pandas as pd
+import numpy as np
+from sklearn.metrics.pairwise import cosine_similarity
+import json
+import pickle
+import os
+import re
+from tqdm import tqdm
+import time
+import litellm
+from config import HF_TOKEN, LLM_MODEL_NAME
+
+# --- CUSTOM JSON ENCODER ---
+class NumpyEncoder(json.JSONEncoder):
+    """Custom encoder for numpy data types to avoid JSON serializable errors."""
+    def default(self, obj):
+        if isinstance(obj, np.integer): return int(obj)
+        if isinstance(obj, np.floating): return float(obj)
+        if isinstance(obj, np.ndarray): return obj.tolist()
+        return super(NumpyEncoder, self).default(obj)
+
+# --- CONSTANTS & CONFIG ---
+MOVIELENS_DIR = 'data/ml-latest-small'
+PROCESSED_DIR = 'data/processed'
+MIN_RATINGS_THRESHOLD = 20    # Popularity filter for items
+MIN_USER_RATINGS = 20        # Minimum activity for specialist candidates
+DISCOVERY_ERA_YEAR = 1980    # Threshold for Recency Bias logic
+
+# Specialist Persona Targets (Used to find the top 5 specialists per category)
+PERSONA_TARGETS = {
+    "Action Junkie": ["Action", "Adventure", "Sci-Fi"],
+    "Romantic Dreamer": ["Romance"],
+    "Cinephile Critic": ["Drama", "Crime", "Mystery", "Thriller"]
+}
+
+os.makedirs(PROCESSED_DIR, exist_ok=True)
+
+# --- LLM HELPER ---
+def call_llm_for_hook(prompt):
+    """Calls the LLM via LiteLLM to generate snappy movie hooks."""
+    try:
+        print(f"DEBUG: Calling LLM for hook with model: {LLM_MODEL_NAME}")
+        start_ts = time.time()
+        response = litellm.completion(
+            model=LLM_MODEL_NAME,
+            messages=[{"role": "user", "content": prompt}],
+            api_key=HF_TOKEN,
+            max_tokens=40,
+            temperature=0.8
+        )
+        print(f"DEBUG: Full LLM Response Object: {response}")
+        print(f"DEBUG: LLM call completed in {time.time() - start_ts:.4f}s")
+        return response.choices[0].message.content.strip().replace('"', '')
+    except Exception as e:
+        return "A standout pick for your collection."
+
+def extract_year(title):
+    """Regex to pull (YYYY) from movie titles."""
+    match = re.search(r'\((\d{4})\)', title)
+    return int(match.group(1)) if match else 0
+
+# --- CORE PREPARATION ---
+def prepare_data():
+    print("Step 1: Loading raw MovieLens data...")
+    ratings = pd.read_csv(f'{MOVIELENS_DIR}/ratings.csv')
+    movies = pd.read_csv(f'{MOVIELENS_DIR}/movies.csv')
+    
+    # 2 Process Metadata
+    print("Step 2: Processing metadata and applying thresholds...")
+    movies['year'] = movies['title'].apply(extract_year)  # Extract (YYYY) from titles for recency bias
+    # Filter movies by popularity: count ratings per movie, then keep only those with ≥20 ratings
+    popular_ids = ratings.groupby('movieId').size()
+    popular_ids = popular_ids[popular_ids >= MIN_RATINGS_THRESHOLD].index
+    
+    filtered_movies = movies[movies['movieId'].isin(popular_ids)].copy()
+    movie_meta = {}
+    for _, row in filtered_movies.iterrows():
+        movie_meta[str(row['movieId'])] = {
+            'movie_title': row['title'],
+            'genres': row['genres'].split('|'),
+            'year': row['year']
+        }
+
+    # === RATING NORMALIZATION (User Bias Correction) ===
+    # Problem: Different users have different rating scales (generous vs. strict)
+    # Solution: Subtract each user's average rating from their individual ratings
+    # This creates deviation scores that are comparable across users
+    # Formula: normalized_rating = rating - user_avg_rating
+    print("  - Normalizing ratings to remove user bias...")
+    user_avg_ratings = ratings.groupby('userId')['rating'].mean().to_dict()
+    ratings['rating_normalized'] = ratings.apply(
+        lambda row: row['rating'] - user_avg_ratings.get(row['userId'], 0), axis=1
+    )
+    
+    # Use normalized ratings for all collaborative filtering steps
+    ratings_normalized = ratings[['userId', 'movieId', 'rating_normalized']].copy()
+    ratings_normalized.columns = ['userId', 'movieId', 'rating']
+    print("  - Normalization complete. All subsequent steps use deviation-adjusted ratings.\n")
+
+    # 3 Identify Specialist Persona Archetypes (The Centroid Logic)
+    print("Step 3: Identifying Specialist Centroids (Top 5 users per persona)...")
+    step_start = time.time()
+    persona_archetypes = {}
+    
+    for persona, target_genres in PERSONA_TARGETS.items():
+        # Find movies in target genres
+        genre_movies = movies[movies['genres'].str.contains('|'.join(target_genres))]['movieId']
+        
+        # Identify active users (MIN_USER_RATINGS ≥20 total ratings)
+        active_users = ratings_normalized.groupby('userId').size()
+        active_users = active_users[active_users >= MIN_USER_RATINGS].index
+        
+        # Calculate Specialization Score for each active user using NORMALIZED ratings
+        # Formula: Specialization(u) = (Genre Density) × (Genre Passion)
+        # Genre Density = (Ratings in Target Genre / Total Ratings by User)
+        # Genre Passion = AvgRating(u, Target Genre) - based on NORMALIZED ratings
+        specialization_scores = {}
+        
+        for user_id in active_users:
+            user_ratings = ratings_normalized[ratings_normalized['userId'] == user_id]
+            total_user_ratings = len(user_ratings)
+            
+            # Get genre ratings for this user
+            genre_ratings = user_ratings[user_ratings['movieId'].isin(genre_movies)]
+            genre_rating_count = len(genre_ratings)
+            
+            # Skip if user hasn't rated any genre movies
+            if genre_rating_count == 0:
+                continue
+            
+            # Calculate specialization components (using normalized ratings)
+            genre_density = genre_rating_count / total_user_ratings  # Proportion (normalized)
+            genre_passion = genre_ratings['rating'].mean()  # Average DEVIATION for genre
+            
+            # Specialization score (combined metric)
+            specialization_scores[user_id] = genre_density * genre_passion
+        
+        # Select top 5 specialists by specialization score
+        top_5_specialists = sorted(specialization_scores.items(), key=lambda x: x[1], reverse=True)[:5]
+        top_5_specialists = [user_id for user_id, score in top_5_specialists]
+        print(f"  - Found specialists for {persona}: {top_5_specialists}")
+        
+        # Aggregate their NORMALIZED ratings (The Centroid)
+        centroid_ratings = ratings_normalized[ratings_normalized['userId'].isin(top_5_specialists)]
+        # Create centroid vector: average NORMALIZED rating per movie from the 5 specialists
+        aggregated_history = centroid_ratings.groupby('movieId')['rating'].mean().to_dict()
+        
+        persona_archetypes[persona] = {
+            "specialist_ids": top_5_specialists,
+            "target_genres": target_genres,
+            "consolidated_history": aggregated_history
+        }
+    
+    print(f">>> Step 3 (Specialist Centroids) complete in {time.time() - step_start:.2f}s")
+
+    # Step 4: Pre-compute Item-Item Similarities for app.py
+    print("Step 4: Pre-computing Item-Item Similarities (O(1) Lookups)...")
+    step_start = time.time()
+    pivot = ratings_normalized.pivot(index='userId', columns='movieId', values='rating').fillna(0)
+    item_sim_matrix = cosine_similarity(pivot.T)
+
+    # Define m_ids early and create O(1) lookup mapping
+    m_ids = pivot.columns.tolist()
+    m_id_to_index = {m_id: idx for idx, m_id in enumerate(m_ids)}
+
+    # Genre coverage analysis with O(1) lookup (fixed performance issue)
+    # === STEP 4A: Genre Coverage Analysis for Adaptive K Selection ===
+    # Problem: How many similar items (K) should we pre-compute for genre filtering?
+    # - Too low (K=20): Genre filter may not find enough candidates for all genres
+    # - Too high (K=100): Wastes storage and compute for marginal benefit
+    # Solution: Empirically test different K values and pick the smallest K that ensures
+    # every genre has sufficient similar items available (≥1.0 average per movie).
+    # This ensures genre-filtered recommendations in app.py won't be starved for choices.
+    
+    print("Analyzing genre coverage for different K values...")
+    genre_coverage_analysis = {}
+    K_CANDIDATES = [20, 30, 50, 100]
+    optimal_k = 50  # Default fallback
+    
+    for genre in ["Action", "Drama", "Romance", "Comedy", "Sci-Fi", "Thriller"]:
+        genre_movie_ids = set(movies[movies['genres'].str.contains(genre)]['movieId'])
+        genre_coverage_analysis[genre] = {}
+        
+        # For each K candidate, measure coverage with O(1) lookup
+        for k in K_CANDIDATES:
+            coverage_count = 0
+            for m_id in m_ids:
+                m_idx = m_id_to_index[m_id]  # O(1) lookup instead of m_ids.index()
+                sim_scores = item_sim_matrix[m_idx]
+                top_k_indices = np.argsort(sim_scores)[-(k+1):-1]
+                genre_match = sum(1 for idx in top_k_indices if m_ids[idx] in genre_movie_ids)
+                coverage_count += genre_match
+            
+            avg_coverage = coverage_count / len(m_ids)
+            genre_coverage_analysis[genre][k] = avg_coverage
+
+    print("Avg similar items per movie in each genre:")
+    for genre, coverage_dict in genre_coverage_analysis.items():
+        print(f"  {genre}: {coverage_dict}")
+
+    # Adaptively select K: find smallest K that gives >=1.0 avg items per genre
+    TARGET_MIN_COVERAGE = 1.0  # At least 1 similar item per genre on average
+    for k in sorted(K_CANDIDATES):
+        min_coverage = min(genre_coverage_analysis[g][k] for g in genre_coverage_analysis.keys())
+        if min_coverage >= TARGET_MIN_COVERAGE:
+            optimal_k = k
+            print(f"\n✅ Optimal K selected: {optimal_k} (min genre coverage: {min_coverage:.2f})")
+            break
+    
+    print(f"Using K={optimal_k} for top similar items\n")
+
+    # Pre-compute similar items with adaptive K
+    top_sim_dict = {}
+    for i, m_id in enumerate(tqdm(m_ids, desc="Similarities")):
+        if str(m_id) not in movie_meta: continue
+        sim_scores = item_sim_matrix[i]
+        # Get top K similar (excluding self)
+        top_indices = np.argsort(sim_scores)[-(optimal_k+1):-1]
+        top_sim_dict[str(m_id)] = {str(m_ids[idx]): float(sim_scores[idx]) for idx in top_indices}
+
+    print(f">>> Step 4 (Item-Item Similarities with K={optimal_k}) complete in {time.time() - step_start:.2f}s\n")
+
+    # Save components
+    with open(f'{PROCESSED_DIR}/movie_metadata.json', 'w') as f: 
+        json.dump(movie_meta, f, indent=4)
+    with open(f'{PROCESSED_DIR}/persona_archetypes.json', 'w') as f: 
+        json.dump(persona_archetypes, f, cls=NumpyEncoder, indent=4)
+    with open(f'{PROCESSED_DIR}/user_avg_ratings.json', 'w') as f:
+        json.dump(user_avg_ratings, f, indent=4)
+    with open(f'{PROCESSED_DIR}/top_similar_items.pkl', 'wb') as f: 
+        pickle.dump(top_sim_dict, f)
+        
+    return persona_archetypes, movie_meta, pivot
+
+# --- RECOMMENDATION ENGINE ---
+def compute_home_recommendations(persona_archetypes, movie_meta, pivot):
+    print("Step 5: Computing Layer 4 Home Recs with Recency Bias...")
+    home_recs = {}
+    
+    for persona, data in persona_archetypes.items():
+        history = data['consolidated_history']
+        target_genres = data['target_genres']
+        
+        print(f"  - Building centroid and finding neighborhood for {persona}...")
+        # Construct Centroid Vector
+        centroid_vec = pd.Series(0.0, index=pivot.columns, dtype=float) # Init with float to avoid warning
+        for m_id, rating in history.items():
+            if m_id in centroid_vec: centroid_vec[m_id] = rating
+            
+        # Neighborhood Search (Find users similar to the centroid)
+        user_sims = cosine_similarity([centroid_vec], pivot)[0]
+        neighbor_idx = np.argsort(user_sims)[-50:]
+        neighbor_ratings = pivot.iloc[neighbor_idx]
+        
+        # Weighted Candidate Scores (Layer 3: Collaborative Prediction)
+        # Formula: R_{p,m} = Σ(Similarity × Rating) / Σ|Similarity|
+        # This normalizes by total similarity to get average weighted score
+        numerator = neighbor_ratings.multiply(user_sims[neighbor_idx], axis=0).sum()
+        denominator = user_sims[neighbor_idx].sum()
+        candidates = numerator / denominator if denominator > 0 else numerator
+        
+        print(f"  - Applying Layer 4 re-ranking for {persona}...")
+        final_list = []
+        for m_id, raw_score in candidates.items():
+            m_id_str = str(m_id)
+            if m_id_str not in movie_meta: continue
+            if m_id in history: continue # Don't recommend what they've seen
+            
+            meta = movie_meta[m_id_str]
+            
+            # Layer 4a: Genre Affinity Boost
+            genre_match = any(g in target_genres for g in meta['genres'])
+            genre_multiplier = 2.5 if genre_match else 0.4
+            
+            # Layer 4b: Recency Bias Logic (Claude's Penalty vs Bonus)
+            # Movies post-1980 get a bonus, older movies get a penalty proportional to age
+            if meta['year'] < DISCOVERY_ERA_YEAR:
+                # Penalty scales from 0.9 (1979) down to 0.5 (1930s)
+                age_factor = max(0.5, 1.0 - (DISCOVERY_ERA_YEAR - meta['year']) / 120)
+            else:
+                # Bonus scales from 1.0 (1980) up to 1.3 (Modern)
+                age_factor = min(1.3, 1.0 + (meta['year'] - DISCOVERY_ERA_YEAR) / 100)
+                
+            final_score = raw_score * genre_multiplier * age_factor
+            
+            final_list.append({
+                'movie_id': m_id,
+                'movie_title': meta['movie_title'],
+                'genres': meta['genres'],
+                'score': final_score
+            })
+            
+        # Top 6 for Home Screen
+        home_recs[persona] = sorted(final_list, key=lambda x: x['score'], reverse=True)[:6]
+
+        top_movies_str = ", ".join([f"'{r['movie_title']}'" for r in home_recs[persona][:2]])
+        print(f"  - Top recs for {persona}: {top_movies_str}...")
+        
+    with open(f'{PROCESSED_DIR}/home_recommendations.json', 'w') as f:
+        json.dump(home_recs, f, indent=4)
+    return home_recs
+
+def generate_hooks(home_recs):
+    print("Step 6: Generating LLM Hooks for Discovery Feed...")
+    cached_hooks = {}
+    for persona, recs in home_recs.items():
+        cached_hooks[persona] = {}
+        for r in recs:
+            title = r['movie_title']
+            prompt = f"Generate a 5-10 word snappy, atmospheric hook for the movie: {title}."
+            hook = call_llm_for_hook(prompt)
+            cached_hooks[persona][str(r['movie_id'])] = hook
+            time.sleep(0.5) # Increased sleep to avoid HF Backend Error 40001
+            
+    with open(f'{PROCESSED_DIR}/cached_hooks.json', 'w') as f:
+        json.dump(cached_hooks, f, indent=4)
+
+if __name__ == "__main__":
+    total_start = time.time()
+    
+    # --- Phase 1: Data Loading, Cleaning, and Initial Computations ---
+    step_start = time.time()
+    archetypes, meta, p_matrix = prepare_data()
+    print(f">>> Phase 1 (Data Prep) complete in {time.time() - step_start:.2f}s\n")
+    
+    # --- Phase 2: Compute Home Recommendations using Centroid Logic ---
+    step_start = time.time()
+    recs = compute_home_recommendations(archetypes, meta, p_matrix)
+    print(f">>> Phase 2 (Home Recs) complete in {time.time() - step_start:.2f}s\n")
+
+    # --- Phase 3: Generate LLM Hooks for the UI ---
+    step_start = time.time()
+    generate_hooks(recs)
+    print(f">>> Phase 3 (LLM Hooks) complete in {time.time() - step_start:.2f}s\n")
+
+    print(f"✅ SUCCESS: Full data pipeline complete in {time.time() - total_start:.2f} seconds.")

movielens_analysis.py

@@ -0,0 +1,152 @@
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+import numpy as np
+
+# Load the datasets
+try:
+    movies_df = pd.read_csv('data/ml-latest-small/movies.csv')
+    ratings_df = pd.read_csv('data/ml-latest-small/ratings.csv')
+except FileNotFoundError:
+    print("Ensure 'movies.csv' and 'ratings.csv' are in the 'data/ml-latest-small/' directory.")
+    exit()
+
+print("--- Movies DataFrame Info ---")
+movies_df.info()
+print("\n--- Ratings DataFrame Info ---")
+ratings_df.info()
+
+# Merge movies and ratings dataframes
+# This allows us to link movie titles and genres with ratings
+movie_ratings = pd.merge(ratings_df, movies_df, on='movieId')
+
+print("\n--- Merged DataFrame Info ---")
+movie_ratings.info()
+
+print("\n--- First 5 rows of Merged DataFrame ---")
+print(movie_ratings.head())
+
+# --- Analysis 1: Most Rated Movies ---
+# Calculate the number of ratings for each movie
+movie_counts = movie_ratings['title'].value_counts()
+print("\n--- Top 10 Most Rated Movies ---")
+print(movie_counts.head(10))
+
+# Visualize Most Rated Movies
+plt.figure(figsize=(12, 6))
+sns.barplot(y=movie_counts.head(10).index, x=movie_counts.head(10).values, palette='viridis')
+plt.title('Top 10 Most Rated Movies')
+plt.xlabel('Number of Ratings')
+plt.ylabel('Movie Title')
+plt.tight_layout()
+plt.savefig('most_rated_movies.png')
+plt.show()
+
+# --- Analysis 2: Highest Rated Movies (with a minimum number of ratings) ---
+# Calculate average rating for each movie
+average_ratings = movie_ratings.groupby('title')['rating'].mean()
+
+# Combine with rating counts
+movie_popularity = pd.DataFrame({
+    'rating_count': movie_counts,
+    'average_rating': average_ratings
+})
+
+# Drop movies with less than a certain number of ratings (e.g., 50 ratings) to avoid skewed results
+min_ratings = 50
+popular_movies = movie_popularity[movie_popularity['rating_count'] >= min_ratings]
+
+# Sort by average rating
+highest_rated_movies = popular_movies.sort_values(by='average_rating', ascending=False)
+print(f"\n--- Top 10 Highest Rated Movies (with at least {min_ratings} ratings) ---")
+print(highest_rated_movies.head(10))
+
+# Visualize Highest Rated Movies
+plt.figure(figsize=(12, 6))
+sns.barplot(y=highest_rated_movies.head(10).index, x=highest_rated_movies.head(10)['average_rating'], palette='magma')
+plt.title(f'Top 10 Highest Rated Movies (at least {min_ratings} ratings)')
+plt.xlabel('Average Rating')
+plt.ylabel('Movie Title')
+plt.tight_layout()
+plt.savefig('highest_rated_movies.png')
+plt.show()
+
+# --- Analysis 3: Genre Distribution ---
+# Split genres and expand into multiple rows
+genres_split = movies_df['genres'].str.split('|', expand=True)
+genres_long = genres_split.stack().reset_index(level=1, drop=True).to_frame(name='genre')
+
+# Count occurrences of each genre
+genre_counts = genres_long['genre'].value_counts()
+print("\n--- Top 10 Most Common Genres ---")
+print(genre_counts.head(10))
+
+# Visualize Genre Distribution
+plt.figure(figsize=(12, 7))
+sns.barplot(y=genre_counts.index, x=genre_counts.values, palette='cubehelix')
+plt.title('Distribution of Movie Genres')
+plt.xlabel('Number of Movies')
+plt.ylabel('Genre')
+plt.tight_layout()
+plt.savefig('genre_distribution.png')
+plt.show()
+
+# --- Analysis 4: User Rating Behavior (Distribution of all ratings) ---
+plt.figure(figsize=(10, 6))
+sns.histplot(ratings_df['rating'], bins=np.arange(0.5, 5.5, 0.5), kde=True, stat='density')
+plt.title('Distribution of All Ratings')
+plt.xlabel('Rating')
+plt.ylabel('Density')
+plt.xticks(np.arange(0.5, 5.5, 0.5))
+plt.grid(axis='y', alpha=0.75)
+plt.tight_layout()
+plt.savefig('rating_distribution.png')
+plt.show()
+
+# --- Analysis 5: Correlation between number of ratings and average rating ---
+plt.figure(figsize=(10, 8))
+sns.scatterplot(x='rating_count', y='average_rating', data=movie_popularity, alpha=0.6)
+plt.title('Correlation between Number of Ratings and Average Rating')
+plt.xlabel('Number of Ratings')
+plt.ylabel('Average Rating')
+plt.grid(True, linestyle='--', alpha=0.6)
+plt.tight_layout()
+plt.savefig('rating_count_vs_avg_rating.png')
+plt.show()
+
+# --- Analysis 6: Distribution of Movies by Number of Ratings ---
+plt.figure(figsize=(12, 6))
+sns.histplot(movie_counts, bins=50, kde=False) # Use movie_counts directly
+plt.title('Distribution of Movies by Number of Ratings')
+plt.xlabel('Number of Ratings Received by Movie')
+plt.ylabel('Number of Movies')
+plt.grid(axis='y', alpha=0.75)
+plt.yscale('log') # Use a log scale for better visibility of lower counts
+plt.tight_layout()
+plt.savefig('movie_rating_count_distribution.png')
+plt.show()
+
+# --- Analysis 7: Distribution of Users by Number of Ratings ---
+user_rating_counts = ratings_df.groupby('userId').size()
+plt.figure(figsize=(12, 6))
+sns.histplot(user_rating_counts, bins=50, kde=False)
+plt.title('Distribution of Users by Number of Movies Rated')
+plt.xlabel('Number of Movies Rated by User')
+plt.ylabel('Number of Users')
+plt.grid(axis='y', alpha=0.75)
+plt.yscale('log') # Log scale is often useful for such distributions
+plt.tight_layout()
+plt.savefig('user_rating_count_distribution.png')
+plt.show()
+
+# --- Analysis 8: List Users who Rated More Than 1000 Movies ---
+users_high_ratings = user_rating_counts[user_rating_counts > 1000]
+print(f"\n--- Users who rated more than 1000 movies (Total: {len(users_high_ratings)}) ---")
+if not users_high_ratings.empty:
+    for user_id, count in users_high_ratings.items():
+        print(f"User ID: {user_id}, Ratings: {count}")
+else:
+    print("No users found who rated more than 1000 movies.")
+
+
+print("\nAnalysis complete. Visualizations saved as PNG files.")

requirements.txt

@@ -0,0 +1,12 @@
+pandas
+numpy
+scikit-learn
+gradio
+requests
+tqdm
+huggingface_hub
+python-dotenv
+#scikit-surprise
+litellm
+matplotlib
+seaborn