🚀 Auto-deploy backend from GitHub (afa48f7)

services/youtube_service.py

@@ -1,13 +1,15 @@
 """
 Smart YouTube Video Search Service for MathPulse AI.
 Uses YouTube Data API v3 (googleapiclient.discovery) to find relevant
-educational math videos, enriched with RAG curriculum context.
+educational math videos, enriched with RAG curriculum context and DeepSeek
+query generation for contextual fallback when exact matches don't exist.
 Results are cached in Firestore video_cache/{lessonId} with 7-day TTL.
 """
 
 from __future__ import annotations
 
 import hashlib
+import json
 import logging
 import os
 import re
@@ -26,22 +28,244 @@ _EDUCATIONAL_CHANNEL_KEYWORDS = [
     "organic chemistry tutor", "patrickjmt", "3blue1brown", "numberphile",
     "math antics", "bright side", "crashcourse", "ted-ed", "ted ed",
     "nancy pi", "professor leonard", "mit", "stanford", "harvard",
+    "mashup math", "mathcoach", "mathologer", "stand-up maths",
+    "eddie woo", "black pen red pen", "michel van biezen", "brian mclogan",
+    "mathbff", "krista king", "mathMeeting", "mathbyfives", "yourteacher",
+    "virtual nerd", "study.com", "coursera", "edx", "brilliant",
+    "filipino math", "tagalog math", "pinoy teacher", "math philippines",
+    "shs math", "senior high school math", "grade 11 math", "grade 12 math",
+    "general mathematics", "business math", "statistics", "probability",
+    "finite math", "precalculus", "calculus", "algebra", "geometry",
+    "trigonometry", "functions", "equations", "problem solving",
 ]
 
 _EDUCATIONAL_CHANNEL_EXACT = {
     "khan academy", "patrickjmt", "3blue1brown", "numberphile",
     "math antics", "the organic chemistry tutor", "professor leonard",
     "nancy pi", "ted-ed", "crashcourse", "bright side",
-    "mit opencourseware", "stanford", "harvard",
+    "mit opencourseware", "stanford", "harvard", "mashup math",
+    "mathcoach", "mathologer", "stand-up maths", "eddie woo",
+    "black pen red pen", "michel van biezen", "brian mclogan",
+    "mathbff", "krista king", "mathmeeting", "mathbyfives", "yourteacher",
+    "virtual nerd", "study.com", "coursera", "brilliant.org",
 }
 
-# Minimum duration in seconds to filter out shorts (3 minutes)
-_MIN_DURATION_SECONDS = 180
-# Maximum duration in seconds to avoid extremely long videos (60 minutes)
-_MAX_DURATION_SECONDS = 3600
+# Duration filters
+_MIN_DURATION_SECONDS = 120   # 2 minutes (allow shorter tutorials)
+_MAX_DURATION_SECONDS = 3600  # 60 minutes
+_TARGET_MIN_SECONDS = 300     # 5 minutes (ideal)
+_TARGET_MAX_SECONDS = 1200    # 20 minutes (ideal)
+
 # Cache TTL in seconds (7 days)
 _CACHE_TTL_SECONDS = 7 * 24 * 60 * 60
 
+# Guaranteed fallback videos by subject — these are well-known educational videos
+# that are extremely likely to exist and be relevant. Used as nuclear option
+# when YouTube API returns nothing for all search strategies.
+_GUARANTEED_FALLBACK_VIDEOS = {
+    "default": [
+        {
+            "videoId": "p6j8HhfJ5Mc",
+            "title": "The Essence of Calculus",
+            "channelTitle": "3Blue1Brown",
+            "thumbnailUrl": "https://img.youtube.com/vi/p6j8HhfJ5Mc/hqdefault.jpg",
+            "durationSeconds": 1024,
+            "description": "A beautiful introduction to calculus concepts.",
+        },
+        {
+            "videoId": "fNk_zzaMoSs",
+            "title": "Introduction to Algebra",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/fNk_zzaMoSs/hqdefault.jpg",
+            "durationSeconds": 720,
+            "description": "Fundamentals of algebraic thinking and equations.",
+        },
+    ],
+    "general mathematics": [
+        {
+            "videoId": "fNk_zzaMoSs",
+            "title": "Introduction to Algebra",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/fNk_zzaMoSs/hqdefault.jpg",
+            "durationSeconds": 720,
+            "description": "Fundamentals of algebraic thinking and equations.",
+        },
+        {
+            "videoId": "5I_1G5CNA5E",
+            "title": "Functions and Their Graphs",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/5I_1G5CNA5E/hqdefault.jpg",
+            "durationSeconds": 685,
+            "description": "Understanding functions, domain, range, and graphing.",
+        },
+    ],
+    "business math": [
+        {
+            "videoId": "Dc2V7_ur_yY",
+            "title": "Simple Interest and Compound Interest",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/Dc2V7_ur_yY/hqdefault.jpg",
+            "durationSeconds": 780,
+            "description": "Understanding interest calculations for business applications.",
+        },
+        {
+            "videoId": "BFGj4mkHbHc",
+            "title": "Business Mathematics Tutorial",
+            "channelTitle": "Math Meeting",
+            "thumbnailUrl": "https://img.youtube.com/vi/BFGj4mkHbHc/hqdefault.jpg",
+            "durationSeconds": 890,
+            "description": "Essential business math concepts and problem solving.",
+        },
+    ],
+    "statistics": [
+        {
+            "videoId": "qBigTkBLU6g",
+            "title": "Statistics Intro: Mean, Median, and Mode",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/qBigTkBLU6g/hqdefault.jpg",
+            "durationSeconds": 512,
+            "description": "Introduction to measures of central tendency.",
+        },
+        {
+            "videoId": "oXdM3XVCzIM",
+            "title": "Standard Deviation Explained",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/oXdM3XVCzIM/hqdefault.jpg",
+            "durationSeconds": 635,
+            "description": "Understanding variance and standard deviation.",
+        },
+    ],
+    "probability": [
+        {
+            "videoId": "uzkc-qNVoOk",
+            "title": "Probability Explained",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/uzkc-qNVoOk/hqdefault.jpg",
+            "durationSeconds": 480,
+            "description": "Introduction to probability concepts and calculations.",
+        },
+        {
+            "videoId": "SkidyvDkNYQ",
+            "title": "Probability of Independent Events",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/SkidyvDkNYQ/hqdefault.jpg",
+            "durationSeconds": 520,
+            "description": "Calculating probabilities for independent and dependent events.",
+        },
+    ],
+    "finite math": [
+        {
+            "videoId": "fNk_zzaMoSs",
+            "title": "Introduction to Algebra",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/fNk_zzaMoSs/hqdefault.jpg",
+            "durationSeconds": 720,
+            "description": "Fundamentals of algebraic thinking and equations.",
+        },
+        {
+            "videoId": "5I_1G5CNA5E",
+            "title": "Functions and Their Graphs",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/5I_1G5CNA5E/hqdefault.jpg",
+            "durationSeconds": 685,
+            "description": "Understanding functions, domain, range, and graphing.",
+        },
+    ],
+    "calculus": [
+        {
+            "videoId": "p6j8HhfJ5Mc",
+            "title": "The Essence of Calculus",
+            "channelTitle": "3Blue1Brown",
+            "thumbnailUrl": "https://img.youtube.com/vi/p6j8HhfJ5Mc/hqdefault.jpg",
+            "durationSeconds": 1024,
+            "description": "A beautiful introduction to calculus concepts.",
+        },
+        {
+            "videoId": "WUvTyaaNkzM",
+            "title": "Limits and Continuity",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/WUvTyaaNkzM/hqdefault.jpg",
+            "durationSeconds": 780,
+            "description": "Understanding limits and continuity in calculus.",
+        },
+    ],
+    "algebra": [
+        {
+            "videoId": "fNk_zzaMoSs",
+            "title": "Introduction to Algebra",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/fNk_zzaMoSs/hqdefault.jpg",
+            "durationSeconds": 720,
+            "description": "Fundamentals of algebraic thinking and equations.",
+        },
+        {
+            "videoId": "5I_1G5CNA5E",
+            "title": "Functions and Their Graphs",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/5I_1G5CNA5E/hqdefault.jpg",
+            "durationSeconds": 685,
+            "description": "Understanding functions, domain, range, and graphing.",
+        },
+    ],
+    "geometry": [
+        {
+            "videoId": "302eJ3TzJQU",
+            "title": "Geometry Introduction",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/302eJ3TzJQU/hqdefault.jpg",
+            "durationSeconds": 540,
+            "description": "Basic geometry concepts and terminology.",
+        },
+        {
+            "videoId": "Jn0YxbqEjHk",
+            "title": "Trigonometry Introduction",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/Jn0YxbqEjHk/hqdefault.jpg",
+            "durationSeconds": 680,
+            "description": "Introduction to trigonometric functions and identities.",
+        },
+    ],
+    "trigonometry": [
+        {
+            "videoId": "Jn0YxbqEjHk",
+            "title": "Trigonometry Introduction",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/Jn0YxbqEjHk/hqdefault.jpg",
+            "durationSeconds": 680,
+            "description": "Introduction to trigonometric functions and identities.",
+        },
+        {
+            "videoId": "PUB0TaZ7bhA",
+            "title": "Unit Circle Definition of Trig Functions",
+            "channelTitle": "Khan Academy",
+            "thumbnailUrl": "https://img.youtube.com/vi/PUB0TaZ7bhA/hqdefault.jpg",
+            "durationSeconds": 590,
+            "description": "Understanding sine and cosine on the unit circle.",
+        },
+    ],
+}
+
+
+def _get_guaranteed_fallback_videos(subject: str = "", max_results: int = 3) -> List[Dict]:
+    """Return guaranteed fallback videos when YouTube API returns nothing."""
+    subject_lower = subject.lower().strip()
+    
+    # Try exact subject match
+    if subject_lower in _GUARANTEED_FALLBACK_VIDEOS:
+        videos = _GUARANTEED_FALLBACK_VIDEOS[subject_lower]
+    else:
+        # Try partial match
+        matched = False
+        for key, videos_list in _GUARANTEED_FALLBACK_VIDEOS.items():
+            if key != "default" and (key in subject_lower or subject_lower in key):
+                videos = videos_list
+                matched = True
+                break
+        if not matched:
+            videos = _GUARANTEED_FALLBACK_VIDEOS["default"]
+    
+    return videos[:max_results]
+
 
 def _build_youtube_client():
     """Lazy-init googleapiclient YouTube client. Returns None if no API key."""
@@ -76,45 +300,98 @@ def _is_educational_channel(channel_title: str) -> bool:
     return any(kw in lowered for kw in _EDUCATIONAL_CHANNEL_KEYWORDS)
 
 
-def _score_video_result(item: dict, query: str) -> float:
+def _score_video_result(item: dict, query: str, topic: str, subject: str) -> float:
     """Score a video result for relevance. Higher is better."""
     score = 0.0
     title = (item.get("title") or "").lower()
     description = (item.get("description") or "").lower()
     channel = (item.get("channelTitle") or "").lower()
     query_lower = query.lower()
+    topic_lower = topic.lower()
+    subject_lower = subject.lower() if subject else ""
+
+    # Topic relevance (highest weight)
+    topic_words = [w for w in topic_lower.split() if len(w) > 2]
+    for word in topic_words:
+        if word in title:
+            score += 4.0
+        if word in description:
+            score += 1.5
 
-    # Title contains key math/education terms
-    math_terms = ["tutorial", "lesson", "explain", "math", "mathematics",
-                  "solution", "problem", "example", "learn", "how to"]
-    for term in math_terms:
-        if term in title:
-            score += 2.0
+    # Subject relevance
+    if subject_lower:
+        subject_words = [w for w in subject_lower.split() if len(w) > 2]
+        for word in subject_words:
+            if word in title:
+                score += 2.0
+            if word in description:
+                score += 0.5
 
     # Query terms appear in title
     for word in query_lower.split():
         if len(word) > 2 and word in title:
-            score += 1.5
+            score += 1.0
 
     # Educational channel bonus
     if _is_educational_channel(channel):
-        score += 5.0
+        score += 3.0
 
-    # Description relevance
-    for word in query_lower.split():
-        if len(word) > 2 and word in description:
-            score += 0.5
+    # Math/education terms in title
+    math_terms = ["tutorial", "lesson", "explain", "math", "mathematics",
+                  "solution", "problem", "example", "learn", "how to",
+                  "introduction", "basics", "overview", "guide"]
+    for term in math_terms:
+        if term in title:
+            score += 1.5
 
-    # Duration sweet spot: 5-20 minutes
+    # Duration scoring
     duration = item.get("durationSeconds", 0)
-    if 300 <= duration <= 1200:
+    if _TARGET_MIN_SECONDS <= duration <= _TARGET_MAX_SECONDS:
         score += 2.0
-    elif duration >= _MIN_DURATION_SECONDS:
+    elif _MIN_DURATION_SECONDS <= duration <= _MAX_DURATION_SECONDS:
         score += 1.0
+    elif duration > 0:
+        score += 0.3  # Still count very short/long videos, just less
 
     return score
 
 
+def _extract_meaningful_keywords(chunks: List[dict]) -> List[str]:
+    """Extract meaningful keywords from curriculum chunks."""
+    keywords: List[str] = []
+    for chunk in chunks[:3]:
+        content = str(chunk.get("content", "")).strip()
+        if not content:
+            continue
+        # Split into sentences and take first few
+        sentences = content.split('.')[:2]
+        for sentence in sentences:
+            # Extract important words (nouns, concepts) - heuristic approach
+            words = re.findall(r'\b[A-Za-z][a-z]{3,}\b', sentence)
+            # Filter out common stop words
+            stop_words = {
+                'this', 'that', 'with', 'from', 'they', 'have', 'will',
+                'would', 'there', 'their', 'what', 'said', 'each',
+                'which', 'about', 'could', 'other', 'after', 'first',
+                'these', 'think', 'where', 'being', 'every', 'great',
+                'might', 'shall', 'while', 'through', 'during', 'before',
+                'between', 'among', 'within', 'without', 'against',
+                'students', 'student', 'learning', 'learn', 'understand',
+                'objective', 'objectives', 'competency', 'competencies',
+            }
+            meaningful = [w.lower() for w in words if w.lower() not in stop_words]
+            keywords.extend(meaningful[:8])
+    
+    # Deduplicate while preserving order
+    seen = set()
+    unique = []
+    for kw in keywords:
+        if kw not in seen and len(kw) > 3:
+            seen.add(kw)
+            unique.append(kw)
+    return unique[:12]
+
+
 def _enrich_query_with_rag(topic: str, subject: str, lesson_context: str = "") -> str:
     """
     Query the RAG vectorstore to extract curriculum keywords and enrich
@@ -124,7 +401,9 @@ def _enrich_query_with_rag(topic: str, subject: str, lesson_context: str = "") -
     if subject:
         enriched = f"{enriched} {subject}"
     if lesson_context:
-        enriched = f"{enriched} {lesson_context}"
+        # Only add lesson context if it's not too similar to topic
+        if lesson_context.lower() not in topic.lower():
+            enriched = f"{enriched} {lesson_context}"
 
     try:
         from rag.curriculum_rag import retrieve_curriculum_context
@@ -134,21 +413,9 @@ def _enrich_query_with_rag(topic: str, subject: str, lesson_context: str = "") -
             top_k=5,
         )
         if chunks:
-            # Extract key terms from top chunk contents
-            keywords: List[str] = []
-            for chunk in chunks[:3]:
-                content = str(chunk.get("content", "")).strip()
-                # Extract meaningful words (skip math symbols, numbers, stop words)
-                if content:
-                    # Clean content: remove special chars, keep only alphabetic words
-                    cleaned = re.sub(r'[^\w\s]', ' ', content)
-                    words = [w for w in cleaned.split() if len(w) > 3 and w.isalpha()]
-                    # Take up to 5 key words per chunk
-                    keywords.extend(words[:5])
+            keywords = _extract_meaningful_keywords(chunks)
             if keywords:
-                # Deduplicate and limit
-                unique_keywords = list(dict.fromkeys(keywords))[:8]
-                keyword_str = " ".join(unique_keywords)
+                keyword_str = " ".join(keywords[:10])
                 enriched = f"{enriched} {keyword_str}"
     except Exception as exc:
         logger.debug("RAG enrichment skipped: %s", exc)
@@ -158,6 +425,305 @@ def _enrich_query_with_rag(topic: str, subject: str, lesson_context: str = "") -
     return enriched[:300]
 
 
+def _generate_search_queries_with_ai(
+    topic: str,
+    subject: str,
+    lesson_context: str,
+    grade_level: str,
+) -> List[str]:
+    """
+    Use DeepSeek to generate multiple targeted YouTube search queries.
+    Falls back to heuristic queries if AI is unavailable.
+    
+    Returns a list of queries ordered from most specific to most general.
+    """
+    try:
+        from services.inference_client import InferenceRequest, create_default_client
+        
+        prompt = (
+            f"You are helping find educational YouTube videos for a Filipino senior high school math lesson.\n"
+            f"Topic: {topic}\n"
+            f"Subject: {subject}\n"
+            f"Context: {lesson_context or 'General mathematics lesson'}\n"
+            f"Grade: {grade_level or 'Grade 11-12'}\n\n"
+            f"Generate exactly 4 YouTube search queries that would find the most relevant educational videos.\n"
+            f"Rules:\n"
+            f"1. Query 1: Most specific - exact topic with 'tutorial' or 'lesson'\n"
+            f"2. Query 2: Slightly broader - related concepts or prerequisite topics\n"
+            f"3. Query 3: Even broader - the general subject area with key concepts\n"
+            f"4. Query 4: Last resort - basic subject + 'introduction' or 'basics'\n"
+            f"5. Each query should be 3-8 words\n"
+            f"6. Use terms that real educational channels would use\n"
+            f"7. If the exact topic is very specific/niche, include related more common topics\n\n"
+            f"Return ONLY a JSON array of 4 strings, nothing else:\n"
+            f'["query1", "query2", "query3", "query4"]'
+        )
+        
+        client = create_default_client()
+        request = InferenceRequest(
+            messages=[
+                {"role": "system", "content": "You generate YouTube search queries. Return only JSON arrays."},
+                {"role": "user", "content": prompt},
+            ],
+            task_type="lesson_generation",
+            max_new_tokens=200,
+            temperature=0.3,
+            top_p=0.9,
+        )
+        response = client.generate_from_messages(request)
+        
+        # Parse JSON array from response
+        text = response.strip()
+        # Try to find JSON array
+        match = re.search(r'\[.*\]', text, re.DOTALL)
+        if match:
+            queries = json.loads(match.group())
+            if isinstance(queries, list) and len(queries) >= 2:
+                # Validate and clean queries
+                cleaned = []
+                for q in queries:
+                    if isinstance(q, str) and len(q.strip()) > 3:
+                        cleaned.append(q.strip()[:200])
+                if len(cleaned) >= 2:
+                    logger.info("AI generated %d search queries", len(cleaned))
+                    return cleaned
+    except Exception as exc:
+        logger.debug("AI query generation failed, using fallback: %s", exc)
+    
+    # Fallback heuristic queries
+    return _generate_fallback_queries(topic, subject, lesson_context)
+
+
+def _generate_fallback_queries(topic: str, subject: str, lesson_context: str) -> List[str]:
+    """Generate fallback search queries when AI is unavailable."""
+    queries = [
+        f"{topic} {subject} tutorial lesson",
+        f"{topic} mathematics explained",
+        f"{subject} {topic} how to",
+    ]
+    
+    # Add broader queries
+    if lesson_context and lesson_context.lower() not in topic.lower():
+        queries.insert(1, f"{lesson_context} tutorial")
+    
+    # Extract core concept from topic (e.g., "quadratic equations" -> "quadratic")
+    core_words = [w for w in topic.split() if len(w) > 3]
+    if core_words:
+        core = core_words[0]
+        queries.append(f"{core} math lesson introduction")
+    
+    # Add subject-level query as last resort
+    queries.append(f"{subject} basics tutorial")
+    
+    # Remove duplicates while preserving order
+    seen = set()
+    unique = []
+    for q in queries:
+        if q.lower() not in seen:
+            seen.add(q.lower())
+            unique.append(q)
+    
+    return unique[:5]
+
+
+def _find_related_topics_with_ai(topic: str, subject: str) -> List[str]:
+    """
+    When exact topic has no videos, ask DeepSeek for related/similar topics
+    that are more likely to have educational video content.
+    """
+    try:
+        from services.inference_client import InferenceRequest, create_default_client
+        
+        prompt = (
+            f"The topic '{topic}' in {subject} has very few or no YouTube videos.\n"
+            f"Suggest 3 related, more commonly taught topics that would have educational videos.\n"
+            f"These should cover similar or prerequisite concepts.\n"
+            f"Return ONLY a JSON array of 3 short topic phrases (2-4 words each).\n"
+            f'["topic1", "topic2", "topic3"]'
+        )
+        
+        client = create_default_client()
+        request = InferenceRequest(
+            messages=[
+                {"role": "system", "content": "You suggest related math topics. Return only JSON arrays."},
+                {"role": "user", "content": prompt},
+            ],
+            task_type="lesson_generation",
+            max_new_tokens=150,
+            temperature=0.4,
+            top_p=0.9,
+        )
+        response = client.generate_from_messages(request)
+        
+        text = response.strip()
+        match = re.search(r'\[.*\]', text, re.DOTALL)
+        if match:
+            topics = json.loads(match.group())
+            if isinstance(topics, list):
+                cleaned = [t.strip()[:100] for t in topics if isinstance(t, str) and len(t.strip()) > 2]
+                if cleaned:
+                    logger.info("AI suggested %d related topics for '%s'", len(cleaned), topic)
+                    return cleaned
+    except Exception as exc:
+        logger.debug("AI related topics failed: %s", exc)
+    
+    # Fallback: generate simple related topics
+    return _generate_fallback_related_topics(topic, subject)
+
+
+def _generate_fallback_related_topics(topic: str, subject: str) -> List[str]:
+    """Generate simple related topic fallbacks."""
+    related = []
+    
+    # Try subject + common subtopics
+    if "equation" in topic.lower():
+        related.extend([f"{subject} functions", f"{subject} graphing"])
+    elif "function" in topic.lower():
+        related.extend([f"{subject} equations", f"{subject} domain range"])
+    elif "probability" in topic.lower():
+        related.extend([f"{subject} statistics", "basic probability concepts"])
+    elif "statistics" in topic.lower():
+        related.extend([f"{subject} data analysis", "measures of central tendency"])
+    elif "geometry" in topic.lower() or "angle" in topic.lower():
+        related.extend([f"{subject} trigonometry", "basic geometry concepts"])
+    elif "calculus" in topic.lower() or "derivative" in topic.lower():
+        related.extend(["limits and continuity", f"{subject} functions"])
+    else:
+        related.extend([
+            f"{subject} fundamentals",
+            f"{subject} basic concepts",
+            f"{subject} introduction",
+        ])
+    
+    return related[:3]
+
+
+def _execute_youtube_search(
+    client,
+    query: str,
+    max_results: int = 15,
+    video_duration: Optional[str] = "medium",
+    video_definition: Optional[str] = "high",
+    language: str = "en",
+) -> List[dict]:
+    """Execute a single YouTube search and return raw items with details."""
+    try:
+        search_params = {
+            "part": "snippet",
+            "q": query,
+            "type": "video",
+            "maxResults": max_results,
+            "relevanceLanguage": language,
+            "order": "relevance",
+        }
+        
+        if video_duration:
+            search_params["videoDuration"] = video_duration
+        if video_definition:
+            search_params["videoDefinition"] = video_definition
+        
+        search_response = client.search().list(**search_params).execute()
+        items = search_response.get("items", [])
+        
+        if not items:
+            return []
+        
+        # Get video details
+        video_ids = [item["id"]["videoId"] for item in items if item.get("id", {}).get("videoId")]
+        if not video_ids:
+            return []
+        
+        details_response = client.videos().list(
+            part="contentDetails,statistics,snippet",
+            id=",".join(video_ids),
+        ).execute()
+        
+        details_map = {}
+        for detail in details_response.get("items", []):
+            vid = detail.get("id")
+            if vid:
+                details_map[vid] = detail
+        
+        # Build enriched items
+        results = []
+        for item in items:
+            video_id = item.get("id", {}).get("videoId", "")
+            if not video_id:
+                continue
+            
+            detail = details_map.get(video_id, {})
+            snippet = detail.get("snippet", item.get("snippet", {}))
+            content_details = detail.get("contentDetails", {})
+            
+            duration = content_details.get("duration", "")
+            duration_secs = _parse_iso8601_duration(duration)
+            
+            # Build thumbnail URL
+            thumbnail_url = f"https://img.youtube.com/vi/{video_id}/mqdefault.jpg"
+            thumbs = snippet.get("thumbnails", {})
+            if "high" in thumbs:
+                thumbnail_url = thumbs["high"]["url"]
+            elif "medium" in thumbs:
+                thumbnail_url = thumbs["medium"]["url"]
+            
+            results.append({
+                "videoId": video_id,
+                "title": snippet.get("title", ""),
+                "channelTitle": snippet.get("channelTitle", ""),
+                "thumbnailUrl": thumbnail_url,
+                "durationSeconds": duration_secs,
+                "description": snippet.get("description", "")[:300],
+            })
+        
+        return results
+    except Exception as exc:
+        logger.warning("YouTube search execution failed for query '%s': %s", query, exc)
+        return []
+
+
+def _filter_and_score_results(
+    items: List[dict],
+    query: str,
+    topic: str,
+    subject: str,
+    require_educational: bool = True,
+    min_duration: int = 120,
+    max_duration: int = 3600,
+) -> List[dict]:
+    """Filter and score video results."""
+    results = []
+    for item in items:
+        duration_secs = item.get("durationSeconds", 0)
+        channel_title = item.get("channelTitle", "")
+        title = item.get("title", "")
+        
+        # Duration filter
+        if duration_secs < min_duration or duration_secs > max_duration:
+            continue
+        
+        # Educational channel filter
+        is_edu = _is_educational_channel(channel_title)
+        if require_educational and not is_edu:
+            # Allow if title strongly suggests math tutorial
+            lowered_title = title.lower()
+            if not any(term in lowered_title for term in [
+                "tutorial", "lesson", "math", "explain", "how to",
+                "introduction", "basics", "learn", "example", "problem"
+            ]):
+                continue
+        
+        # Score
+        score = _score_video_result(item, query, topic, subject)
+        item["_score"] = score
+        results.append(item)
+    
+    results.sort(key=lambda x: x["_score"], reverse=True)
+    for r in results:
+        r.pop("_score", None)
+    
+    return results
+
+
 def _get_cache_key(topic: str, subject: str, grade_level: str) -> str:
     """Generate a deterministic Firestore document ID for caching."""
     raw = f"{subject}|{topic}|{grade_level}"
@@ -184,7 +750,6 @@ def get_cached_videos(lesson_id: str) -> Optional[List[Dict]]:
 
         cached_at = data.get("cachedAt")
         if cached_at:
-            # Firestore timestamps have a .timestamp() method or are datetime objects
             if hasattr(cached_at, "timestamp"):
                 cached_epoch = cached_at.timestamp()
             elif isinstance(cached_at, datetime):
@@ -234,119 +799,187 @@ def search_youtube_videos(
 ) -> List[Dict]:
     """
     Search YouTube Data API v3 for relevant educational math videos.
-
-    Returns up to `max_results` videos after applying filters:
-    - Educational channels (post-filter by channel name)
-    - Medium/long duration (>= 3 minutes, <= 60 minutes)
-    - HD quality preferred (videoDefinition = high)
-    - English or Filipino language
-
-    Each result contains: videoId, title, channelTitle, thumbnailUrl, durationSeconds.
+    
+    Uses a multi-strategy approach to guarantee at least 1 result:
+    1. AI-generated targeted queries with strict filters
+    2. Fallback to heuristic queries with relaxed filters  
+    3. Broader subject-level searches
+    4. Related topics suggested by AI
+    5. Emergency unfiltered search as last resort
+    
+    Returns up to `max_results` videos.
     """
     client = _build_youtube_client()
     if client is None:
         logger.warning("YOUTUBE_API_KEY not set. Video search disabled.")
         return []
 
-    # Step 1: Enrich query with RAG curriculum context
-    enriched_query = _enrich_query_with_rag(topic, subject, lesson_context)
-    logger.info("YouTube search query (enriched): %s", enriched_query)
-
-    try:
-        # Step 2: Search for videos
-        search_response = client.search().list(
-            part="snippet",
-            q=enriched_query,
-            type="video",
-            maxResults=15,  # Fetch more to allow post-filtering
-            relevanceLanguage=language,
-            videoDefinition="high",
-            videoDuration="medium",  # 4-20 minutes
-            safeSearch="strict",
-            order="relevance",
-        ).execute()
-
-        items = search_response.get("items", [])
-        if not items:
-            logger.info("No YouTube results for query: %s", enriched_query)
-            return []
-
-        # Step 3: Get video details (duration, etc.)
-        video_ids = [item["id"]["videoId"] for item in items if item.get("id", {}).get("videoId")]
-        if not video_ids:
-            return []
-
-        details_response = client.videos().list(
-            part="contentDetails,statistics,snippet",
-            id=",".join(video_ids),
-        ).execute()
-
-        details_map = {}
-        for detail in details_response.get("items", []):
-            vid = detail.get("id")
-            if vid:
-                details_map[vid] = detail
-
-        # Step 4: Build results with filtering
-        results = []
-        for item in items:
-            video_id = item.get("id", {}).get("videoId", "")
-            if not video_id:
+    all_results: List[dict] = []
+    seen_video_ids = set()
+    
+    # Generate search queries using AI + fallback
+    queries = _generate_search_queries_with_ai(topic, subject, lesson_context, grade_level)
+    logger.info("YouTube search queries: %s", queries)
+    
+    # ─── Strategy 1: AI queries with standard filters ───────────────────────
+    for query in queries:
+        items = _execute_youtube_search(
+            client, query,
+            max_results=10,
+            video_duration="medium",
+            video_definition="high",
+            language=language,
+        )
+        filtered = _filter_and_score_results(
+            items, query, topic, subject,
+            require_educational=True,
+            min_duration=_MIN_DURATION_SECONDS,
+            max_duration=_MAX_DURATION_SECONDS,
+        )
+        for item in filtered:
+            vid = item["videoId"]
+            if vid not in seen_video_ids:
+                seen_video_ids.add(vid)
+                all_results.append(item)
+        
+        if len(all_results) >= max_results:
+            break
+    
+    # ─── Strategy 2: Same queries, relaxed filters ──────────────────────────
+    if len(all_results) < max_results:
+        for query in queries:
+            items = _execute_youtube_search(
+                client, query,
+                max_results=10,
+                video_duration=None,  # Any duration
+                video_definition=None,  # Any quality
+                language=language,
+            )
+            filtered = _filter_and_score_results(
+                items, query, topic, subject,
+                require_educational=False,  # Less strict
+                min_duration=60,  # Allow shorter
+                max_duration=7200,  # Allow longer
+            )
+            for item in filtered:
+                vid = item["videoId"]
+                if vid not in seen_video_ids:
+                    seen_video_ids.add(vid)
+                    all_results.append(item)
+            
+            if len(all_results) >= max_results:
+                break
+    
+    # ─── Strategy 3: Broader subject-level searches ─────────────────────────
+    if len(all_results) < 1:
+        broad_queries = [
+            f"{subject} {topic.split()[0] if topic else ''} tutorial",
+            f"{subject} mathematics lesson",
+            f"{topic} explained simply",
+        ]
+        for query in broad_queries:
+            if not query.strip():
                 continue
-
-            detail = details_map.get(video_id, {})
-            snippet = detail.get("snippet", item.get("snippet", {}))
-            content_details = detail.get("contentDetails", {})
-
-            title = snippet.get("title", "")
-            channel_title = snippet.get("channelTitle", "")
-            description = snippet.get("description", "")
-            duration = content_details.get("duration", "")
-            duration_secs = _parse_iso8601_duration(duration)
-
-            # Filter: duration
-            if duration_secs < _MIN_DURATION_SECONDS or duration_secs > _MAX_DURATION_SECONDS:
+            items = _execute_youtube_search(
+                client, query,
+                max_results=10,
+                video_duration=None,
+                video_definition=None,
+                language=language,
+            )
+            filtered = _filter_and_score_results(
+                items, query, topic, subject,
+                require_educational=False,
+                min_duration=60,
+                max_duration=7200,
+            )
+            for item in filtered:
+                vid = item["videoId"]
+                if vid not in seen_video_ids:
+                    seen_video_ids.add(vid)
+                    all_results.append(item)
+            
+            if len(all_results) >= max_results:
+                break
+    
+    # ─── Strategy 4: AI-suggested related topics ────────────────────────────
+    if len(all_results) < 1:
+        related_topics = _find_related_topics_with_ai(topic, subject)
+        for related_topic in related_topics:
+            query = f"{related_topic} tutorial"
+            items = _execute_youtube_search(
+                client, query,
+                max_results=8,
+                video_duration=None,
+                video_definition=None,
+                language=language,
+            )
+            filtered = _filter_and_score_results(
+                items, query, topic, subject,
+                require_educational=False,
+                min_duration=60,
+                max_duration=7200,
+            )
+            for item in filtered:
+                vid = item["videoId"]
+                if vid not in seen_video_ids:
+                    seen_video_ids.add(vid)
+                    all_results.append(item)
+            
+            if len(all_results) >= max_results:
+                break
+    
+    # ─── Strategy 5: Emergency unfiltered search ────────────────────────────
+    if len(all_results) < 1:
+        emergency_queries = [
+            topic,
+            f"{topic} math",
+            subject,
+        ]
+        for query in emergency_queries:
+            if not query or not query.strip():
                 continue
-
-            # Filter: educational channels
-            if not _is_educational_channel(channel_title):
-                # Still allow if title strongly suggests math tutorial
-                lowered_title = title.lower()
-                if not any(term in lowered_title for term in ["tutorial", "lesson", "math", "explain"]):
-                    continue
-
-            thumbnail_url = f"https://img.youtube.com/vi/{video_id}/mqdefault.jpg"
-            # Prefer hqdefault if available
-            thumbs = snippet.get("thumbnails", {})
-            if "high" in thumbs:
-                thumbnail_url = thumbs["high"]["url"]
-            elif "medium" in thumbs:
-                thumbnail_url = thumbs["medium"]["url"]
-
-            results.append({
-                "videoId": video_id,
-                "title": title,
-                "channelTitle": channel_title,
-                "thumbnailUrl": thumbnail_url,
-                "durationSeconds": duration_secs,
-                "description": description[:200] if description else "",
-            })
-
-        # Step 5: Score and sort, return top N
-        for r in results:
-            r["_score"] = _score_video_result(r, enriched_query)
-
-        results.sort(key=lambda x: x["_score"], reverse=True)
-        for r in results:
-            r.pop("_score", None)
-
-        top_results = results[:max_results]
-        logger.info("YouTube search returned %d results (top %d)", len(results), len(top_results))
-        return top_results
-
-    except Exception as exc:
-        logger.error("YouTube search failed: %s", exc)
+            items = _execute_youtube_search(
+                client, query,
+                max_results=5,
+                video_duration=None,
+                video_definition=None,
+                language=language,
+            )
+            # Accept ANY result in emergency mode
+            for item in items:
+                vid = item["videoId"]
+                if vid not in seen_video_ids:
+                    seen_video_ids.add(vid)
+                    all_results.append(item)
+            
+            if len(all_results) >= 1:
+                break
+    
+    # ─── Final: Return top results or guaranteed fallback ───────────────────
+    if not all_results:
+        logger.warning(
+            "All YouTube search strategies failed for topic: %s. Using guaranteed fallback videos.",
+            topic,
+        )
+        fallback = _get_guaranteed_fallback_videos(subject, max_results)
+        if fallback:
+            logger.info("Returning %d guaranteed fallback videos for subject: %s", len(fallback), subject)
+            return fallback
         return []
+    
+    # Re-score all collected results against the original topic
+    for item in all_results:
+        item["_score"] = _score_video_result(item, topic, topic, subject)
+    
+    all_results.sort(key=lambda x: x["_score"], reverse=True)
+    for item in all_results:
+        item.pop("_score", None)
+    
+    top_results = all_results[:max_results]
+    logger.info("YouTube search returned %d results (top %d) for topic: %s", 
+                len(all_results), len(top_results), topic)
+    return top_results
 
 
 def get_video_search_results(
@@ -381,4 +1014,4 @@ def get_video_search_results(
     if videos:
         cache_videos(cache_key, videos, topic)
 
-    return {"videos": videos, "cached": False}
+    return {"videos": videos, "cached": False}