🚀 Auto-deploy backend from GitHub (3efade4)

main.py

@@ -108,6 +108,7 @@ from routes.class_analytics_routes import router as class_analytics_router
 from routes.intervention_routes import router as intervention_router
 from routes.pipeline_routes import router as pipeline_router
 from routes.deepseek_rag_routes import router as deepseek_rag_router
+from routes.at_risk_resolution import router as at_risk_resolution_router
 
 # Rate limiting (slowapi)
 try:
@@ -1171,6 +1172,7 @@ app.include_router(class_analytics_router)
 app.include_router(intervention_router)
 app.include_router(pipeline_router)
 app.include_router(deepseek_rag_router)
+app.include_router(at_risk_resolution_router)
 
 
 # ─── Global Exception Handler ─────────────────────────────────
@@ -1894,6 +1896,74 @@ def _is_continuation_followup_token(message: str) -> bool:
     return followup_token in _CONTINUATION_FOLLOWUP_TOKENS
 
 
+# ─── Context-Aware Intent Gate (Fix: out-of-scope false positives) ────
+# This function prevents short/vague student replies from being rejected
+# as off-topic when an active tutoring session is in progress.
+
+_FILIPINO_CONTINUATION_PHRASES: Set[str] = {
+    "di ko alam", "hindi ko alam", "di ko gets", "hindi ko gets",
+    "di ko maintindihan", "hindi ko maintindihan", "ano ulit", "ano yun",
+    "bakit", "paano", "paano po", "bakit po", "sige", "sige po",
+    "oo", "oo nga", "okay", "ok", "gets ko na", "gets", "ayaw ko na",
+    "hindi", "hindi po", "wala akong idea", "di ko alam yan",
+    "ano", "ano po", "huh", "what", "wait", "idk", "i don't know",
+    "i dont know", "not sure", "unsure", "help", "help me",
+    "di ko pa gets", "di ko pa alam", "try ko", "ano nga ulit",
+    "thanks", "thank you", "salamat", "nice", "wow", "oh",
+}
+
+
+def is_continuation_reply(user_message: str, active_state: Any, recent_turns: Optional[list]) -> bool:
+    """
+    Returns True if the message should be treated as a continuation of
+    the current tutoring session rather than a new or off-topic request.
+
+    A message is a continuation if ANY of the following are true:
+    - It matches known Filipino/Taglish continuation patterns
+    - It is short (under 8 words) AND active_state has active_topic or current_problem
+    - The last assistant message in recent_turns was a question or problem prompt
+    """
+    msg = user_message.strip().lower()
+    if not msg:
+        return False
+
+    # Check Filipino/Taglish continuation signals
+    words = msg.split()
+    word_count = len(words)
+    word_set = set(words)
+    for phrase in _FILIPINO_CONTINUATION_PHRASES:
+        if ' ' in phrase:
+            # Multi-word: substring match
+            if phrase in msg:
+                return True
+        else:
+            # Single-word: only match if message is short (≤3 words)
+            if word_count <= 3 and phrase in word_set:
+                return True
+
+    # Short messages (under 8 words) with active math context are continuations
+    has_active_context = active_state and (
+        getattr(active_state, "active_topic", "") or
+        getattr(active_state, "current_problem", "")
+    )
+
+    if word_count <= 7 and has_active_context:
+        return True
+
+    # Last assistant turn was a question or problem prompt
+    if recent_turns:
+        for turn in reversed(recent_turns):
+            role = turn.get("role") if isinstance(turn, dict) else getattr(turn, "role", "")
+            content = (turn.get("content") if isinstance(turn, dict) else getattr(turn, "content", "")) or ""
+            if str(role).lower() in ("assistant", "ai"):
+                content_stripped = content.strip()
+                if content_stripped.endswith("?") or "solve" in content_stripped.lower() or "try" in content_stripped.lower():
+                    return True
+                break
+
+    return False
+
+
 def _extract_latest_assistant_message(history: Optional[Sequence[Any]]) -> Optional[str]:
     if not history:
         return None
@@ -2316,7 +2386,40 @@ MEMORY AWARENESS:
 - Build on what was previously taught — don't repeat from scratch unless the student asks.
 - If the student refers to "that problem" or "last time", use memory context to infer what they mean.
 - If memory is not available, continue tutoring normally without it.
-- Never mention the memory system to the student — just use it naturally."""
+- Never mention the memory system to the student — just use it naturally.
+
+CONTEXT-AWARE FALLBACK RULE:
+You have access to a MEMORY CONTEXT block above that contains:
+- CURRENT SESSION STATE: active_topic and current_problem fields
+- RECENT CONVERSATION: the last 10 turns of this session
+
+RULE: If the MEMORY CONTEXT shows an active_topic OR current_problem OR the previous
+assistant turn asked the student a question, you MUST treat any short, vague, or
+conversational student reply as a continuation of that tutoring thread.
+
+NEVER trigger the out-of-scope response for:
+- "di ko alam" / "hindi ko alam" / "di ko gets" (Filipino: I don't know)
+- "idk", "I don't know", "not sure"
+- "huh?", "what?", "ano?", "bakit?", "paano?"
+- "okay", "ok", "sige", "oo", "gets ko na"
+- "help", "help me", "ayaw ko na"
+- any reply under 8 words when a math problem is active
+
+For ALL of the above, continue the tutoring session. If the student doesn't know
+the answer, guide them with a hint or a simpler step. Do not abandon them.
+
+Only use the out-of-scope response when:
+1. The student explicitly asks about something completely unrelated to mathematics
+   (e.g., "who is the president?", "write my English essay", "what is noli me tangere about")
+2. AND there is no active_topic, current_problem, or recent math context in memory
+
+When in doubt, ask a clarifying math question rather than triggering out-of-scope.
+
+LANGUAGE:
+You understand and respond naturally in Filipino, Tagalog, Taglish, and English.
+Always match the student's language. Filipino and Taglish expressions are valid input.
+Treat all Filipino conversational replies as normal student communication, never as
+off-topic or unrecognized input."""
 
 
 _STREAM_COMPLETION_MODES: Set[str] = {"auto", "marker", "none"}
@@ -2528,9 +2631,24 @@ async def chat_tutor(request: ChatRequest):
     """AI Math Tutor powered by Hugging Face Inference routing."""
     _start_ms = int(time.monotonic() * 1000)
     try:
-        boundary_response = get_scope_boundary_response(request.message, request.history)
-        if boundary_response is not None:
-            return ChatResponse(response=boundary_response)
+        # ─── Context-Aware Intent Gate (before scope check) ──────
+        # Load active state to determine if student is mid-session.
+        # If so, skip scope check for short/vague replies.
+        _skip_scope_check = False
+        if request.userId and request.sessionId and HAS_MEMORY_SERVICE and get_active_state is not None:
+            try:
+                _active = get_active_state(request.userId, request.sessionId)
+            except Exception:
+                _active = None
+            _history_dicts = [{"role": m.role, "content": m.content} for m in (request.history or [])[-10:]]
+            if is_continuation_reply(request.message, _active, _history_dicts):
+                _skip_scope_check = True
+        # ─── End Intent Gate ─────────────────────────────────────
+
+        if not _skip_scope_check:
+            boundary_response = get_scope_boundary_response(request.message, request.history)
+            if boundary_response is not None:
+                return ChatResponse(response=boundary_response)
 
         system_prompt = MATH_TUTOR_SYSTEM_PROMPT
 
@@ -2678,7 +2796,19 @@ async def _update_memory_after_response(
 async def chat_tutor_stream(request: ChatRequest):
     """SSE stream endpoint for AI Math Tutor chat responses."""
     try:
-        boundary_response = get_scope_boundary_response(request.message, request.history)
+        # ─── Context-Aware Intent Gate (before scope check) ──────
+        _skip_scope_check = False
+        if request.userId and request.sessionId and HAS_MEMORY_SERVICE and get_active_state is not None:
+            try:
+                _active = get_active_state(request.userId, request.sessionId)
+            except Exception:
+                _active = None
+            _history_dicts = [{"role": m.role, "content": m.content} for m in (request.history or [])[-10:]]
+            if is_continuation_reply(request.message, _active, _history_dicts):
+                _skip_scope_check = True
+        # ─── End Intent Gate ─────────────────────────────────────
+
+        boundary_response = None if _skip_scope_check else get_scope_boundary_response(request.message, request.history)
         
         # ─── Memory Context Injection ────────────────────────────
         memory_context = ""

routes/at_risk_resolution.py

@@ -0,0 +1,316 @@
+"""
+At-Risk + Locked Module Resolution Logic.
+
+POST /api/at-risk/resolve       — Classify flagged topics into resolution states + generate fallback content
+GET  /api/at-risk/fallback/{uid}/{topic_id} — Fetch cached fallback study brief
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from services.ai_client import CHAT_MODEL
+from services.deepseek_client import is_enabled, rag_grounded_completion, parse_json_response
+from rag.curriculum_rag import (
+    retrieve_curriculum_context,
+    format_retrieved_chunks,
+    summarize_retrieval_confidence,
+)
+
+import firebase_admin
+from firebase_admin import firestore as fs
+
+logger = logging.getLogger("mathpulse.at_risk_resolution")
+router = APIRouter(prefix="/api/at-risk", tags=["at-risk-resolution"])
+
+
+# ─── Models ────────────────────────────────────────────────────────
+
+class FlaggedTopicInput(BaseModel):
+    topic_id: str
+    topic_name: str
+    subject: str = "General Mathematics"
+    quarter: int = 1
+    confidence_score: float = 0.0
+
+
+class ResolveRequest(BaseModel):
+    uid: str
+    flagged_topics: list[FlaggedTopicInput]
+
+
+class ResolvedTopic(BaseModel):
+    topic_id: str
+    subject: str
+    quarter: int
+    confidence_score: float
+    resolution_state: str  # accessible | coming_soon | progression_locked | no_module
+    module_id: Optional[str] = None
+
+
+class FallbackContent(BaseModel):
+    summary: str = ""
+    key_concepts: list[str] = Field(default_factory=list)
+    one_worked_example: dict = Field(default_factory=dict)
+    what_to_focus_on: str = ""
+    rag_confidence: str = "low"
+
+
+class ResolveResponse(BaseModel):
+    resolved: list[ResolvedTopic]
+    fallback_generated: int = 0
+
+
+# ─── Resolution Logic ──────────────────────────────────────────────
+
+def _resolve_topic(
+    topic: FlaggedTopicInput,
+    firestore_client: Any,
+    uid: str,
+) -> ResolvedTopic:
+    """Classify a flagged topic into a resolution state by checking Firestore modules collection."""
+    # Query modules collection for matching topic
+    modules_ref = firestore_client.collection("modules")
+    # Try exact match on moduleId == topic_id first
+    doc = modules_ref.document(topic.topic_id).get()
+
+    module_id: Optional[str] = None
+    module_status: Optional[str] = None
+
+    if doc.exists:
+        data = doc.to_dict() or {}
+        module_id = topic.topic_id
+        module_status = data.get("moduleStatus") or data.get("status") or "unavailable"
+    else:
+        # Fallback: query by topicId field
+        query = modules_ref.where("topicId", "==", topic.topic_id).limit(1).stream()
+        for match in query:
+            data = match.to_dict() or {}
+            module_id = match.id
+            module_status = data.get("moduleStatus") or data.get("status") or "unavailable"
+            break
+
+    if not module_id or not module_status:
+        return ResolvedTopic(
+            topic_id=topic.topic_id,
+            subject=topic.subject,
+            quarter=topic.quarter,
+            confidence_score=topic.confidence_score,
+            resolution_state="no_module",
+            module_id=None,
+        )
+
+    # Check if module is accessible
+    if module_status in ("available", "teacher_uploaded"):
+        # Check progression unlock
+        progress_doc = (
+            firestore_client.collection("studentProgress")
+            .document(uid)
+            .collection("modules")
+            .document(module_id)
+            .get()
+        )
+        if progress_doc.exists:
+            prog_data = progress_doc.to_dict() or {}
+            if prog_data.get("unlocked") is False:
+                return ResolvedTopic(
+                    topic_id=topic.topic_id,
+                    subject=topic.subject,
+                    quarter=topic.quarter,
+                    confidence_score=topic.confidence_score,
+                    resolution_state="progression_locked",
+                    module_id=module_id,
+                )
+        return ResolvedTopic(
+            topic_id=topic.topic_id,
+            subject=topic.subject,
+            quarter=topic.quarter,
+            confidence_score=topic.confidence_score,
+            resolution_state="accessible",
+            module_id=module_id,
+        )
+
+    if module_status == "coming_soon":
+        return ResolvedTopic(
+            topic_id=topic.topic_id,
+            subject=topic.subject,
+            quarter=topic.quarter,
+            confidence_score=topic.confidence_score,
+            resolution_state="coming_soon",
+            module_id=module_id,
+        )
+
+    # unavailable or unknown
+    return ResolvedTopic(
+        topic_id=topic.topic_id,
+        subject=topic.subject,
+        quarter=topic.quarter,
+        confidence_score=topic.confidence_score,
+        resolution_state="no_module",
+        module_id=module_id,
+    )
+
+
+# ─── Fallback Content Generation ──────────────────────────────────
+
+def _generate_fallback_content(
+    topic: FlaggedTopicInput,
+    resolution_state: str,
+) -> Optional[dict]:
+    """Generate RAG-grounded fallback study brief for a non-accessible topic."""
+    if not is_enabled():
+        return None
+
+    # STEP 1 — RAG retrieval: key concepts
+    concept_chunks = retrieve_curriculum_context(
+        query=f"core concepts and learning competency for {topic.topic_name}",
+        subject=topic.subject,
+        quarter=topic.quarter,
+        chunk_type="key_concepts",
+        top_k=5,
+    )
+    if not concept_chunks:
+        concept_chunks = retrieve_curriculum_context(
+            query=f"core concepts and learning competency for {topic.topic_name}",
+            subject=topic.subject,
+            quarter=topic.quarter,
+            chunk_type="learning_competency",
+            top_k=5,
+        )
+    if not concept_chunks:
+        concept_chunks = retrieve_curriculum_context(
+            query=f"core concepts and learning competency for {topic.topic_name}",
+            subject=topic.subject,
+            quarter=topic.quarter,
+            top_k=5,
+        )
+
+    # Worked examples
+    example_chunks = retrieve_curriculum_context(
+        query=f"worked examples for {topic.topic_name}",
+        subject=topic.subject,
+        quarter=topic.quarter,
+        chunk_type="worked_examples",
+        top_k=3,
+    )
+
+    # Merge and deduplicate
+    seen: set[str] = set()
+    merged: list[dict] = []
+    for chunk in concept_chunks + example_chunks:
+        key = f"{chunk.get('source_file')}::{chunk.get('page')}::{chunk.get('content', '')[:60]}"
+        if key not in seen:
+            seen.add(key)
+            merged.append(chunk)
+
+    rag_context = format_retrieved_chunks(merged)
+    confidence_info = summarize_retrieval_confidence(merged)
+    rag_band = confidence_info.get("band", "low")
+
+    # STEP 2 — DeepSeek call
+    system_prompt = (
+        "You are a DepEd SHS math tutor. A student has been flagged as at-risk on a topic "
+        "but the full module is not yet available. Generate a compact, self-contained "
+        "study brief using ONLY the retrieved DepEd curriculum content below. "
+        "Do NOT invent content outside the curriculum context."
+    )
+    user_prompt = (
+        f"[CURRICULUM CONTEXT]\n{rag_context}\n\n"
+        f"The student is at risk in: '{topic.topic_name}' ({topic.subject}, Q{topic.quarter}).\n"
+        f"The full module is currently [{resolution_state}].\n\n"
+        "Generate a compact study brief with this exact JSON structure:\n"
+        "{\n"
+        '  "summary": "2-3 sentence overview of the topic",\n'
+        '  "key_concepts": ["concept 1", "concept 2", "concept 3"],\n'
+        '  "one_worked_example": { "problem": "...", "solution": "..." },\n'
+        '  "what_to_focus_on": "1-2 sentences on what the student should prioritize",\n'
+        f'  "rag_confidence": "{rag_band}"\n'
+        "}\n\n"
+        "Return ONLY valid JSON."
+    )
+
+    raw = rag_grounded_completion(CHAT_MODEL, system_prompt, user_prompt, temperature=0.2)
+    parsed = parse_json_response(raw)
+
+    if parsed:
+        parsed.setdefault("rag_confidence", rag_band)
+        return parsed
+
+    return None
+
+
+# ─── Endpoints ─────────────────────────────────────────────────────
+
+@router.post("/resolve", response_model=ResolveResponse)
+async def resolve_at_risk_topics(request: ResolveRequest):
+    """Resolve flagged topics into resolution states and generate fallback content."""
+    try:
+        firestore_client = fs.client()
+    except Exception:
+        raise HTTPException(status_code=503, detail="Database unavailable")
+
+    resolved: list[ResolvedTopic] = []
+    fallback_count = 0
+
+    for topic in request.flagged_topics:
+        result = _resolve_topic(topic, firestore_client, request.uid)
+        resolved.append(result)
+
+        # Write resolution state to Firestore
+        try:
+            firestore_client.collection("students").document(request.uid).collection(
+                "flaggedTopics"
+            ).document(topic.topic_id).set({
+                "topicId": topic.topic_id,
+                "subject": topic.subject,
+                "quarter": topic.quarter,
+                "confidenceScore": topic.confidence_score,
+                "resolutionState": result.resolution_state,
+                "moduleId": result.module_id,
+                "resolvedAt": fs.SERVER_TIMESTAMP,
+            })
+        except Exception as e:
+            logger.warning(f"Failed to write flaggedTopics for {topic.topic_id}: {e}")
+
+        # Generate fallback content for non-accessible topics
+        if result.resolution_state != "accessible":
+            fallback = _generate_fallback_content(topic, result.resolution_state)
+            if fallback:
+                try:
+                    firestore_client.collection("students").document(request.uid).collection(
+                        "atRiskFallbackContent"
+                    ).document(topic.topic_id).set({
+                        **fallback,
+                        "generated_at": fs.SERVER_TIMESTAMP,
+                        "resolutionState": result.resolution_state,
+                    })
+                    fallback_count += 1
+                except Exception as e:
+                    logger.warning(f"Failed to cache fallback for {topic.topic_id}: {e}")
+
+    return ResolveResponse(resolved=resolved, fallback_generated=fallback_count)
+
+
+@router.get("/fallback/{uid}/{topic_id}")
+async def get_fallback_content(uid: str, topic_id: str):
+    """Fetch cached fallback study brief for a flagged topic."""
+    try:
+        firestore_client = fs.client()
+    except Exception:
+        raise HTTPException(status_code=503, detail="Database unavailable")
+
+    doc = (
+        firestore_client.collection("students")
+        .document(uid)
+        .collection("atRiskFallbackContent")
+        .document(topic_id)
+        .get()
+    )
+
+    if not doc.exists:
+        raise HTTPException(status_code=404, detail="No fallback content found")
+
+    return doc.to_dict()

routes/pipeline_routes.py

@@ -48,6 +48,24 @@ async def receive_event(payload: PipelineEventPayload, background_tasks: Backgro
     return {"status": "accepted", "student_id": payload.student_id}
 
 
+@router.post("/nudge/{student_id}", status_code=200)
+async def request_nudge(student_id: str, background_tasks: BackgroundTasks, request: Request):
+    """Check if a nudge should be generated for an existing at-risk student."""
+    user = _require_auth(request)
+    if user.role == "student" and student_id != user.uid:
+        raise HTTPException(status_code=403, detail="Students can only request nudges for themselves")
+
+    async def _generate():
+        try:
+            from services.tutor_nudge_service import check_and_generate_nudge
+            await check_and_generate_nudge(student_id)
+        except Exception as e:
+            logger.warning(f"Nudge check failed for {student_id}: {e}")
+
+    background_tasks.add_task(_generate)
+    return {"status": "accepted"}
+
+
 @router.get("/profile/{student_id}")
 async def get_profile(student_id: str, request: Request):
     """Get full student profile."""

services/intervention_engine.py

@@ -48,6 +48,7 @@ class LearningStep(BaseModel):
     difficulty: Literal["easy", "medium", "hard"] = "easy"
     is_completed: bool = False
     completion_score: Optional[float] = None
+    youtube_query: Optional[str] = None
 
 
 class LearningPath(BaseModel):
@@ -404,6 +405,7 @@ Create a 4-6 step learning path that:
 2. Uses varied methodology: video → practice → assessment → review cycle
 3. Scales difficulty: start easy, progress to grade-level
 4. Total estimated time: {estimated_days} days
+5. For video_lesson steps, include a youtube_query field with a specific YouTube search query targeting Filipino DepEd math content. Format: "{{topic}} Grade {{level}} {{subtopic}} tutorial Philippines"
 
 Return ONLY valid JSON:
 {{
@@ -420,7 +422,8 @@ Return ONLY valid JSON:
       "num_items": null,
       "topic": "Topic Name",
       "competency_tag": "M11GM-Ia-1",
-      "difficulty": "easy"
+      "difficulty": "easy",
+      "youtube_query": "Topic Name Grade Level basics tutorial Philippines DepEd"
     }}
   ]
 }}"""
@@ -453,6 +456,7 @@ Return ONLY valid JSON:
                     topic=s.get("topic", weakest_topic),
                     competency_tag=s.get("competency_tag", ""),
                     difficulty=s.get("difficulty", "easy"),
+                    youtube_query=s.get("youtube_query"),
                 ))
 
             return LearningPath(
@@ -474,7 +478,8 @@ Return ONLY valid JSON:
         """Generate a basic learning path without AI."""
         steps = [
             LearningStep(step_number=1, type="video_lesson", title=f"{weakest_topic} - Fundamentals",
-                         description="Review core concepts", duration_minutes=8, topic=weakest_topic, difficulty="easy"),
+                         description="Review core concepts", duration_minutes=8, topic=weakest_topic, difficulty="easy",
+                         youtube_query=f"{weakest_topic} Grade 11 basics tutorial Philippines DepEd"),
             LearningStep(step_number=2, type="practice", title=f"{weakest_topic} - Guided Practice",
                          description="Work through examples", duration_minutes=12, num_items=10, topic=weakest_topic, difficulty="easy"),
             LearningStep(step_number=3, type="practice", title=f"{weakest_topic} - Independent Practice",

services/student_intelligence_pipeline.py

@@ -155,6 +155,25 @@ class StudentIntelligencePipeline:
                 # 6. Write to managedStudents (update P, WRI, riskStatus)
                 self._update_managed_student(db, event.student_id, wri_result, new_p)
 
+            # 6b. Proactive tutor nudge (fire-and-forget, non-blocking)
+            new_status = profile.get("risk_status", "safe")
+            if new_status in ("watch", "intervene", "critical", "at_risk"):
+                weak_topics = (
+                    profile.get("quiz_performance", {}).get("lowest_accuracy_topics", [])
+                    or profile.get("diagnostic", {}).get("weak_topics", [])
+                )
+                if weak_topics:
+                    try:
+                        from services.tutor_nudge_service import generate_tutor_nudge_for_student
+                        await generate_tutor_nudge_for_student(
+                            student_id=event.student_id,
+                            weak_topics=weak_topics[:3],
+                            grade_level=profile.get("grade_level", "Grade 11"),
+                            recent_score=profile.get("system_performance_avg"),
+                        )
+                    except Exception as e:
+                        logger.warning(f"Nudge generation failed (non-critical): {e}")
+
             # 7. AI context generation (cost-controlled)
             if self._should_regenerate_ai(event, profile, result):
                 ai_ctx = await self._generate_ai_context(profile, event)

services/tutor_nudge_service.py

@@ -0,0 +1,165 @@
+"""
+MathPulse AI — Tutor Nudge Service
+
+Generates proactive AI tutor nudges for at-risk students using DeepSeek,
+then writes them to Firestore for the floating tutor to surface.
+"""
+
+import logging
+from datetime import datetime, timezone
+
+logger = logging.getLogger("mathpulse.tutor_nudge")
+
+NUDGE_COOLDOWN_HOURS = 24
+
+SYSTEM_PROMPT = (
+    "You are MathPulse's AI tutor. Write a single short, friendly message "
+    "to nudge the student to work on their weakest topic. "
+    "No long explanation, just a nudge plus a concrete action. "
+    "1-2 sentences max. No code, no LaTeX. Be warm and encouraging."
+)
+
+
+def _get_db():
+    try:
+        from firebase_admin import firestore as ff
+        return ff.client()
+    except Exception:
+        return None
+
+
+def _has_recent_nudge(db, student_id: str, topic: str) -> bool:
+    """Check if an unconsumed nudge for this topic exists within cooldown."""
+    from datetime import timedelta
+    cutoff = datetime.now(timezone.utc) - timedelta(hours=NUDGE_COOLDOWN_HOURS)
+    nudges_ref = db.collection("tutorNudges").document(student_id).collection("nudges")
+    existing = (
+        nudges_ref
+        .where("topic", "==", topic)
+        .where("createdAt", ">=", cutoff)
+        .limit(1)
+        .get()
+    )
+    return len(existing) > 0
+
+
+async def generate_tutor_nudge_for_student(
+    student_id: str,
+    weak_topics: list[str],
+    grade_level: str = "Grade 11",
+    recent_score: float | None = None,
+) -> dict | None:
+    """Generate a nudge message via DeepSeek and write to Firestore."""
+    if not weak_topics:
+        return None
+
+    db = _get_db()
+    if not db:
+        logger.warning("Firestore unavailable, skipping nudge generation")
+        return None
+
+    # Pick the first weak topic that doesn't have a recent nudge
+    topic = None
+    for t in weak_topics[:3]:
+        if not _has_recent_nudge(db, student_id, t):
+            topic = t
+            break
+
+    if not topic:
+        return None  # All topics have recent nudges
+
+    # Generate nudge via DeepSeek
+    try:
+        from services.ai_client import get_deepseek_client, CHAT_MODEL
+
+        client = get_deepseek_client()
+        user_content = (
+            f"Student grade: {grade_level}. "
+            f"Weak topic: {topic}. "
+            f"{'Recent score: ' + str(round(recent_score)) + '%.' if recent_score else ''} "
+            f"Write a short nudge to encourage them to practice this topic."
+        )
+
+        response = client.chat.completions.create(
+            model=CHAT_MODEL,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=0.7,
+            max_tokens=100,
+        )
+        message = (response.choices[0].message.content or "").strip()
+        if not message:
+            return None
+
+    except Exception as e:
+        logger.error(f"DeepSeek nudge generation failed for {student_id}: {e}")
+        return None
+
+    # Write to Firestore
+    nudge_data = {
+        "message": message,
+        "topic": topic,
+        "createdAt": datetime.now(timezone.utc),
+        "consumed": False,
+    }
+
+    try:
+        db.collection("tutorNudges").document(student_id).collection("nudges").add(nudge_data)
+        logger.info(f"Nudge written for {student_id}: topic={topic}")
+    except Exception as e:
+        logger.error(f"Failed to write nudge for {student_id}: {e}")
+        return None
+
+    return {"message": message, "topic": topic, "created_at": nudge_data["createdAt"].isoformat()}
+
+
+async def check_and_generate_nudge(student_id: str) -> dict | None:
+    """
+    Check if a student already has risk data warranting a nudge,
+    and generate one if no recent unconsumed nudge exists.
+    Used for students who completed diagnostics but have no new pipeline events.
+    """
+    db = _get_db()
+    if not db:
+        return None
+
+    # Read existing risk profile from managedStudents
+    managed_ref = db.collection("managedStudents").document(student_id)
+    managed_snap = managed_ref.get()
+    if not managed_snap.exists:
+        return None
+
+    data = managed_snap.to_dict() or {}
+    risk_status = data.get("riskStatus")
+    if risk_status not in ("watch", "intervene", "critical", "at_risk"):
+        return None
+
+    # Get weak topics from student_profiles
+    profile_ref = db.collection("student_profiles").document(student_id)
+    profile_snap = profile_ref.get()
+    weak_topics: list[str] = []
+    if profile_snap.exists:
+        profile = profile_snap.to_dict() or {}
+        weak_topics = (
+            profile.get("quiz_performance", {}).get("lowest_accuracy_topics", [])
+            or profile.get("diagnostic", {}).get("weak_topics", [])
+        )
+
+    if not weak_topics:
+        # Fallback: use atRiskSubjects from user doc
+        user_ref = db.collection("users").document(student_id)
+        user_snap = user_ref.get()
+        if user_snap.exists:
+            weak_topics = (user_snap.to_dict() or {}).get("atRiskSubjects", [])
+
+    if not weak_topics:
+        return None
+
+    return await generate_tutor_nudge_for_student(
+        student_id=student_id,
+        weak_topics=weak_topics[:3],
+        grade_level=data.get("grade", "Grade 11"),
+        recent_score=data.get("systemPerformanceAvg") or data.get("diagnosticScore"),
+    )

tests/test_fallback_intent_gate.py

@@ -0,0 +1,120 @@
+"""
+Tests for the context-aware intent gate (is_continuation_reply).
+
+Verifies that short/vague student replies during active tutoring sessions
+are NOT rejected as off-topic, while genuinely off-topic messages still are.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import pytest
+from unittest.mock import MagicMock
+from main import is_continuation_reply
+
+
+def _make_active_state(active_topic: str = "", current_problem: str = ""):
+    """Create a mock WorkingMemoryState."""
+    state = MagicMock()
+    state.active_topic = active_topic
+    state.current_problem = current_problem
+    return state
+
+
+def _make_history(messages: list[tuple[str, str]]) -> list[dict]:
+    """Create history list from (role, content) tuples."""
+    return [{"role": role, "content": content} for role, content in messages]
+
+
+# ─── Tests: Should return True (continuation) ─────────────────────
+
+class TestContinuationPositive:
+    def test_di_ko_alam_with_active_topic(self):
+        state = _make_active_state(active_topic="Functions and Their Graphs")
+        assert is_continuation_reply("di ko alam", state, []) is True
+
+    def test_idk_with_current_problem(self):
+        state = _make_active_state(current_problem="Solve x^2 + 3x - 4 = 0")
+        assert is_continuation_reply("idk", state, []) is True
+
+    def test_huh_after_tutor_question(self):
+        history = _make_history([
+            ("user", "what is a function?"),
+            ("assistant", "A function maps each input to exactly one output. Can you give me an example?"),
+        ])
+        assert is_continuation_reply("huh?", None, history) is True
+
+    def test_thanks_with_active_topic(self):
+        state = _make_active_state(active_topic="Quadratic Equations")
+        assert is_continuation_reply("thanks", state, []) is True
+
+    def test_hindi_ko_gets_no_state_but_phrase_match(self):
+        # Filipino phrase match should trigger even without active state
+        assert is_continuation_reply("hindi ko gets", None, []) is True
+
+    def test_short_reply_with_active_context(self):
+        state = _make_active_state(active_topic="Linear Equations")
+        assert is_continuation_reply("I'm confused", state, []) is True
+
+    def test_ano_with_active_problem(self):
+        state = _make_active_state(current_problem="Find the derivative of f(x)=3x^2")
+        assert is_continuation_reply("ano?", state, []) is True
+
+    def test_paano_po(self):
+        assert is_continuation_reply("paano po", None, []) is True
+
+    def test_sige_with_context(self):
+        state = _make_active_state(active_topic="Statistics")
+        assert is_continuation_reply("sige", state, []) is True
+
+    def test_help_me(self):
+        assert is_continuation_reply("help me", None, []) is True
+
+    def test_short_msg_after_solve_prompt(self):
+        history = _make_history([
+            ("assistant", "Try to solve this: What is 2x + 5 = 11?"),
+        ])
+        assert is_continuation_reply("what", None, history) is True
+
+    def test_ok_with_active_topic(self):
+        state = _make_active_state(active_topic="Trigonometry")
+        assert is_continuation_reply("ok", state, []) is True
+
+
+# ─── Tests: Should return False (not a continuation) ──────────────
+
+class TestContinuationNegative:
+    def test_explicit_offtopic_no_context(self):
+        assert is_continuation_reply(
+            "who is the president of the philippines?", None, []
+        ) is False
+
+    def test_write_essay_no_context(self):
+        assert is_continuation_reply("write my essay", None, []) is False
+
+    def test_long_offtopic_no_context(self):
+        assert is_continuation_reply(
+            "can you tell me about the history of the roman empire", None, []
+        ) is False
+
+    def test_empty_message(self):
+        assert is_continuation_reply("", None, []) is False
+
+    def test_long_non_math_no_state(self):
+        assert is_continuation_reply(
+            "what is the meaning of life and why are we here on earth",
+            None,
+            [],
+        ) is False
+
+    def test_explicit_offtopic_even_with_history_no_question(self):
+        history = _make_history([
+            ("assistant", "Great job solving that equation!"),
+        ])
+        # Long off-topic message, no active state, last assistant msg not a question
+        assert is_continuation_reply(
+            "tell me about basketball players in the NBA this season",
+            None,
+            history,
+        ) is False