Update utils/movies_explanation.py

utils/movies_explanation.py

@@ -1,158 +1,157 @@
-# utils/movies_explanation.py
-import random
-from typing import Dict, List, Any, Optional, Tuple
-
-
-def generate_explanation(user_tags: Dict[str, Any], item: Dict[str, Any]) -> str:
-    """
-    Generates a personalized, natural-sounding explanation for a recommended movie.
-
-    The explanation dynamically combines matched user preferences (genres, mood, audience)
-    with movie attributes (title, director, lead actor, era, original genres/moods)
-    using varied templates.
-
-    Args:
-        user_tags (Dict[str, Any]): Parsed tags from the user's query (e.g., genres, mood, target_audience).
-        item (Dict[str, Any]): The movie record being recommended, including its annotated attributes.
-
-    Returns:
-        str: A generated explanation string in English.
-    """
-    # --- Extract and prepare attributes ---
-    title = item.get("title", "this captivating movie")
-    director = item.get("director", "a talented director").title() if item.get(
-        "director") else "a talented director"  # Capitalize
-    cast = item.get("cast", [])
-    lead_actor = cast[0].title() if cast and cast[0] else "a stellar cast"  # Capitalize
-
-    # Ensure default values are used correctly if lists are empty
-    genres_item = item.get("genres")
-    if not genres_item:
-        genres_item = ["drama"]  # Default for explanation if missing or empty
-
-    mood_item = item.get("mood")
-    if not mood_item:
-        mood_item = ["captivating"]  # Default for explanation if missing or empty
-
-    era_item = item.get("era", "recent")
-    audience_item = item.get("target_audience", "adult")
-
-    # Try to get release_year from release_date if release_year is not directly available
-    release_year = item.get("release_year")
-    if not release_year:
-        try:
-            release_year = int(item.get("release_date", "").split("-")[0])
-        except (ValueError, IndexError):
-            release_year = None
-
-    year_info = f"({release_year})" if release_year else f"(from the {era_item} era)"  # More descriptive year info
-
-    # --- Identify matched user preferences ---
-    user_genres = user_tags.get("genres", [])
-    user_moods = user_tags.get("mood", [])
-
-    matched_genres = sorted(list(set(user_genres) & set(genres_item)))
-    matched_moods = sorted(list(set(user_moods) & set(mood_item)))
-
-    # Prioritize user's preferred genre and mood if matched, otherwise fall back to item's first
-    primary_genre_for_explanation = matched_genres[0] if matched_genres else (
-        genres_item[0] if genres_item else "general")
-    primary_mood_for_explanation = matched_moods[0] if matched_moods else (mood_item[0] if mood_item else "engaging")
-
-    # --- Construct dynamic phrases ---
-    audience_phrase = ""
-    if audience_item == "children":
-        audience_phrase = "perfect for the whole family"
-    elif audience_item == "young_adult":
-        audience_phrase = "ideal for teens and young adults"
-    else:  # adult
-        audience_phrase = "recommended for mature audiences"
-
-    genre_match_phrase = ""
-    if matched_genres:
-        if len(matched_genres) == 1:
-            genre_match_phrase = f"matching your interest in {matched_genres[0].lower()} films"
-        else:
-            genre_match_phrase = f"matching your interest in {', '.join(matched_genres).lower()} genres"
-
-    mood_match_phrase = ""
-    if matched_moods:
-        if len(matched_moods) == 1:
-            mood_match_phrase = f"with a distinctly {matched_moods[0].lower()} vibe"
-        else:
-            mood_match_phrase = f"offering a mix of {', '.join(matched_moods).lower()} moods"
-    elif user_tags.get("mood"):  # User asked for mood, but no exact match in movie item's direct moods
-        # This covers cases where the user asked for a mood, but the movie's annotated moods didn't perfectly overlap
-        mood_match_phrase = f"that aligns with your desire for something {', '.join(user_tags['mood']).lower()}"
-
-    # --- Diverse and intelligent templates ---
-    templates = []
-
-    # High-specificity templates (when both genre and mood match)
-    if matched_genres and matched_moods:
-        templates.append(
-            f"This is a fantastic pick {audience_phrase}: \"{title}\" {year_info}, directed by {director}, is a {primary_genre_for_explanation.lower()} film, especially {primary_mood_for_explanation.lower()} and {genre_match_phrase}."
-        )
-        templates.append(
-            f"We think you'll love \"{title}\" {year_info}. It's a {primary_genre_for_explanation.lower()} movie, exactly what you asked for {mood_match_phrase} and {genre_match_phrase}."
-        )
-        templates.append(
-            f"Join {lead_actor} in \"{title}\" {year_info}, a {primary_genre_for_explanation.lower()} masterpiece by {director} that's both {primary_mood_for_explanation.lower()} and {genre_match_phrase}."
-        )
-        templates.append(
-            f"For a truly {primary_mood_for_explanation.lower()} {primary_genre_for_explanation.lower()} cinematic experience, dive into \"{title}\" {year_info} by {director}."
-        )
-
-    # Medium-specificity templates (when only genre or only mood match)
-    if matched_genres and not matched_moods:
-        templates.append(
-            f"Searching for a {primary_genre_for_explanation.lower()} film? \"{title}\" {year_info}, by {director}, perfectly matches your genre preference."
-        )
-        templates.append(
-            f"This {primary_genre_for_explanation.lower()} movie, \"{title}\" {year_info}, starring {lead_actor}, comes highly recommended {audience_phrase}."
-        )
-        templates.append(
-            f"If you're looking for {primary_genre_for_explanation.lower()} movies, \"{title}\" is a strong choice by {director} {year_info}."
-        )
-
-    if matched_moods and not matched_genres:
-        templates.append(
-            f"Looking for something {primary_mood_for_explanation.lower()}? \"{title}\" {year_info}, directed by {director}, offers just that experience."
-        )
-        templates.append(
-            f"For a truly {primary_mood_for_explanation.lower()} cinematic journey, don't miss \"{title}\" {year_info}, featuring {lead_actor}."
-        )
-        templates.append(
-            f"This movie, \"{title}\" by {director}, provides a {primary_mood_for_explanation.lower()} escape {audience_phrase}."
-        )
-        templates.append(
-            f"Feeling {primary_mood_for_explanation.lower()}? \"{title}\" {year_info} is a perfect match {audience_phrase}."
-        )
-
-    # General templates (when audience or other general attributes match, or as fallback)
-    templates.append(
-        f"\"{title}\" {year_info}, directed by {director}, is a {primary_genre_for_explanation.lower()} film that viewers find {primary_mood_for_explanation.lower()}. It's {audience_phrase}."
-    )
-    templates.append(
-        f"A compelling watch {audience_phrase}, \"{title}\" {year_info} offers a {primary_mood_for_explanation.lower()} experience in the {primary_genre_for_explanation.lower()} genre."
-    )
-    templates.append(
-        f"You might enjoy \"{title}\" {year_info} from {director}, a {primary_genre_for_explanation.lower()} story starring {lead_actor} that is {primary_mood_for_explanation.lower()}."
-    )
-    templates.append(
-        f"This {primary_genre_for_explanation.lower()} classic {year_info} by {director} is an {primary_mood_for_explanation.lower()} pick {audience_phrase}."
-    )
-    templates.append(
-        f"Experience {primary_mood_for_explanation.lower()} thrills in “{title}” {year_info}, a {primary_genre_for_explanation.lower()} gem by {director}, {audience_phrase}."
-    )
-    templates.append(
-        f"Discover \"{title}\" {year_info} by {director}, a highly-rated {primary_genre_for_explanation.lower()} film {audience_phrase}."
-    )
-
-    # Filter out empty templates and choose one
-    valid_templates = [t for t in templates if t.strip()]
-    if valid_templates:
-        return random.choice(valid_templates)
-    else:
-        # Fallback if no specific templates could be formed (should be rare with general templates)
-        return f"We recommend \"{title}\" {year_info}, a {primary_genre_for_explanation.lower()} movie for {audience_phrase}."
+import random
+from typing import Dict, List, Any, Optional, Tuple
+
+
+def generate_explanation(user_tags: Dict[str, Any], item: Dict[str, Any]) -> str:
+    """
+    Generates a personalized, natural-sounding explanation for a recommended movie.
+
+    The explanation dynamically combines matched user preferences (genres, mood, audience)
+    with movie attributes (title, director, lead actor, era, original genres/moods)
+    using varied templates.
+
+    Args:
+        user_tags (Dict[str, Any]): Parsed tags from the user's query (e.g., genres, mood, target_audience).
+        item (Dict[str, Any]): The movie record being recommended, including its annotated attributes.
+
+    Returns:
+        str: A generated explanation string in English.
+    """
+    # --- Extract and prepare attributes ---
+    title = item.get("title", "this captivating movie")
+    director = item.get("director", "a talented director").title() if item.get(
+        "director") else "a talented director"  # Capitalize
+    cast = item.get("cast", [])
+    lead_actor = cast[0].title() if cast and cast[0] else "a stellar cast"  # Capitalize
+
+    # Ensure default values are used correctly if lists are empty
+    genres_item = item.get("genres")
+    if not genres_item:
+        genres_item = ["drama"]  # Default for explanation if missing or empty
+
+    mood_item = item.get("mood")
+    if not mood_item:
+        mood_item = ["captivating"]  # Default for explanation if missing or empty
+
+    era_item = item.get("era", "recent")
+    audience_item = item.get("target_audience", "adult")
+
+    # Try to get release_year from release_date if release_year is not directly available
+    release_year = item.get("release_year")
+    if not release_year:
+        try:
+            release_year = int(item.get("release_date", "").split("-")[0])
+        except (ValueError, IndexError):
+            release_year = None
+
+    year_info = f"({release_year})" if release_year else f"(from the {era_item} era)"  # More descriptive year info
+
+    # --- Identify matched user preferences ---
+    user_genres = user_tags.get("genres", [])
+    user_moods = user_tags.get("mood", [])
+
+    matched_genres = sorted(list(set(user_genres) & set(genres_item)))
+    matched_moods = sorted(list(set(user_moods) & set(mood_item)))
+
+    # Prioritize user's preferred genre and mood if matched, otherwise fall back to item's first
+    primary_genre_for_explanation = matched_genres[0] if matched_genres else (
+        genres_item[0] if genres_item else "general")
+    primary_mood_for_explanation = matched_moods[0] if matched_moods else (mood_item[0] if mood_item else "engaging")
+
+    # --- Construct dynamic phrases ---
+    audience_phrase = ""
+    if audience_item == "children":
+        audience_phrase = "perfect for the whole family"
+    elif audience_item == "young_adult":
+        audience_phrase = "ideal for teens and young adults"
+    else:  # adult
+        audience_phrase = "recommended for mature audiences"
+
+    genre_match_phrase = ""
+    if matched_genres:
+        if len(matched_genres) == 1:
+            genre_match_phrase = f"matching your interest in {matched_genres[0].lower()} films"
+        else:
+            genre_match_phrase = f"matching your interest in {', '.join(matched_genres).lower()} genres"
+
+    mood_match_phrase = ""
+    if matched_moods:
+        if len(matched_moods) == 1:
+            mood_match_phrase = f"with a distinctly {matched_moods[0].lower()} vibe"
+        else:
+            mood_match_phrase = f"offering a mix of {', '.join(matched_moods).lower()} moods"
+    elif user_tags.get("mood"):  # User asked for mood, but no exact match in movie item's direct moods
+        # This covers cases where the user asked for a mood, but the movie's annotated moods didn't perfectly overlap
+        mood_match_phrase = f"that aligns with your desire for something {', '.join(user_tags['mood']).lower()}"
+
+    # --- Diverse and intelligent templates ---
+    templates = []
+
+    # High-specificity templates (when both genre and mood match)
+    if matched_genres and matched_moods:
+        templates.append(
+            f"This is a fantastic pick {audience_phrase}: \"{title}\" {year_info}, directed by {director}, is a {primary_genre_for_explanation.lower()} film, especially {primary_mood_for_explanation.lower()} and {genre_match_phrase}."
+        )
+        templates.append(
+            f"We think you'll love \"{title}\" {year_info}. It's a {primary_genre_for_explanation.lower()} movie, exactly what you asked for {mood_match_phrase} and {genre_match_phrase}."
+        )
+        templates.append(
+            f"Join {lead_actor} in \"{title}\" {year_info}, a {primary_genre_for_explanation.lower()} masterpiece by {director} that's both {primary_mood_for_explanation.lower()} and {genre_match_phrase}."
+        )
+        templates.append(
+            f"For a truly {primary_mood_for_explanation.lower()} {primary_genre_for_explanation.lower()} cinematic experience, dive into \"{title}\" {year_info} by {director}."
+        )
+
+    # Medium-specificity templates (when only genre or only mood match)
+    if matched_genres and not matched_moods:
+        templates.append(
+            f"Searching for a {primary_genre_for_explanation.lower()} film? \"{title}\" {year_info}, by {director}, perfectly matches your genre preference."
+        )
+        templates.append(
+            f"This {primary_genre_for_explanation.lower()} movie, \"{title}\" {year_info}, starring {lead_actor}, comes highly recommended {audience_phrase}."
+        )
+        templates.append(
+            f"If you're looking for {primary_genre_for_explanation.lower()} movies, \"{title}\" is a strong choice by {director} {year_info}."
+        )
+
+    if matched_moods and not matched_genres:
+        templates.append(
+            f"Looking for something {primary_mood_for_explanation.lower()}? \"{title}\" {year_info}, directed by {director}, offers just that experience."
+        )
+        templates.append(
+            f"For a truly {primary_mood_for_explanation.lower()} cinematic journey, don't miss \"{title}\" {year_info}, featuring {lead_actor}."
+        )
+        templates.append(
+            f"This movie, \"{title}\" by {director}, provides a {primary_mood_for_explanation.lower()} escape {audience_phrase}."
+        )
+        templates.append(
+            f"Feeling {primary_mood_for_explanation.lower()}? \"{title}\" {year_info} is a perfect match {audience_phrase}."
+        )
+
+    # General templates (when audience or other general attributes match, or as fallback)
+    templates.append(
+        f"\"{title}\" {year_info}, directed by {director}, is a {primary_genre_for_explanation.lower()} film that viewers find {primary_mood_for_explanation.lower()}. It's {audience_phrase}."
+    )
+    templates.append(
+        f"A compelling watch {audience_phrase}, \"{title}\" {year_info} offers a {primary_mood_for_explanation.lower()} experience in the {primary_genre_for_explanation.lower()} genre."
+    )
+    templates.append(
+        f"You might enjoy \"{title}\" {year_info} from {director}, a {primary_genre_for_explanation.lower()} story starring {lead_actor} that is {primary_mood_for_explanation.lower()}."
+    )
+    templates.append(
+        f"This {primary_genre_for_explanation.lower()} classic {year_info} by {director} is an {primary_mood_for_explanation.lower()} pick {audience_phrase}."
+    )
+    templates.append(
+        f"Experience {primary_mood_for_explanation.lower()} thrills in “{title}” {year_info}, a {primary_genre_for_explanation.lower()} gem by {director}, {audience_phrase}."
+    )
+    templates.append(
+        f"Discover \"{title}\" {year_info} by {director}, a highly-rated {primary_genre_for_explanation.lower()} film {audience_phrase}."
+    )
+
+    # Filter out empty templates and choose one
+    valid_templates = [t for t in templates if t.strip()]
+    if valid_templates:
+        return random.choice(valid_templates)
+    else:
+        # Fallback if no specific templates could be formed (should be rare with general templates)
+        return f"We recommend \"{title}\" {year_info}, a {primary_genre_for_explanation.lower()} movie for {audience_phrase}."