🚀 Auto-deploy backend from GitHub (552770f)

main.py

@@ -100,6 +100,8 @@ from routes.video_routes import router as video_router
 from routes.quiz_battle import router as quiz_battle_router
 from routes.teacher_materials import router as teacher_materials_router
 from routes.class_records_router import router as class_records_router
+from routes.risk_router import router as risk_router
+from routes.tutor_checkin import router as tutor_checkin_router
 
 # Rate limiting (slowapi)
 try:
@@ -1089,6 +1091,8 @@ app.include_router(video_router)
 app.include_router(quiz_battle_router)
 app.include_router(teacher_materials_router)
 app.include_router(class_records_router)
+app.include_router(risk_router)
+app.include_router(tutor_checkin_router)
 
 
 # ─── Global Exception Handler ─────────────────────────────────

routes/risk_router.py

@@ -0,0 +1,121 @@
+"""
+WRI (Weighted Risk Index) Computation Router.
+
+POST /api/risk/compute      -> Compute WRI for a single student
+POST /api/risk/compute/batch -> Batch compute WRI for multiple students
+
+Prevention-first 5-band classification:
+  WRI >= 88 -> safe
+  WRI >= 80 -> watch
+  WRI >= 75 -> intervene
+  WRI >= 68 -> critical
+  WRI < 68  -> at_risk
+
+Aligned with DepEd DO No. 8, s. 2015 — 75 is the failing floor, not the trigger.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+logger = logging.getLogger("mathpulse.risk")
+
+router = APIRouter(prefix="/api/risk", tags=["risk"])
+
+# Lazy import of wri_service (may not exist yet in dev environments)
+_wri_service = None
+
+def _get_wri_service():
+    global _wri_service
+    if _wri_service is None:
+        try:
+            from services.wri_service import compute_wri
+            _wri_service = compute_wri
+        except ImportError:
+            # Fallback for when services haven't been set up yet
+            _wri_service = None
+    return _wri_service
+
+
+class RiskComputePayload(BaseModel):
+    d: Optional[float] = None
+    g: Optional[float] = None
+    p: Optional[float] = None
+    weights: Dict[str, float] = {"w1": 0.30, "w2": 0.40, "w3": 0.30}
+
+
+class StudentRiskInput(BaseModel):
+    id: str
+    d: Optional[float] = None
+    g: Optional[float] = None
+    p: Optional[float] = None
+
+
+class BatchRiskPayload(BaseModel):
+    students: List[StudentRiskInput]
+    weights: Dict[str, float] = {"w1": 0.30, "w2": 0.40, "w3": 0.30}
+
+
+@router.post("/compute")
+def compute_risk_endpoint(payload: RiskComputePayload):
+    """
+    Compute WRI for a single student.
+    """
+    compute_fn = _get_wri_service()
+    if compute_fn is None:
+        raise HTTPException(
+            status_code=503,
+            detail="WRI service not available. Ensure backend services are initialized."
+        )
+    
+    try:
+        result = compute_fn(
+            d=payload.d,
+            g=payload.g,
+            p=payload.p,
+            weights=payload.weights,
+        )
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/compute/batch")
+def compute_risk_batch(payload: BatchRiskPayload):
+    """
+    Compute WRI for multiple students in one call.
+    Used by Cloud Functions for batch recalculation.
+    """
+    compute_fn = _get_wri_service()
+    if compute_fn is None:
+        raise HTTPException(
+            status_code=503,
+            detail="WRI service not available."
+        )
+    
+    results = []
+    for student in payload.students:
+        try:
+            result = compute_fn(
+                d=student.d,
+                g=student.g,
+                p=student.p,
+                weights=payload.weights,
+            )
+            results.append({
+                "id": student.id,
+                **result,
+            })
+        except ValueError as e:
+            results.append({
+                "id": student.id,
+                "wri": None,
+                "risk_status": "error",
+                "error": str(e),
+            })
+    
+    return {"results": results}

routes/tutor_checkin.py

@@ -0,0 +1,143 @@
+"""
+Tutor Check-in Engine — DeepSeek-powered contextual student engagement.
+
+POST /api/tutor-checkin -> Generate a personalized check-in message for a student
+based on their recent activity, weak topics, and current risk status.
+"""
+
+import logging
+import os
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+logger = logging.getLogger("mathpulse.tutor_checkin")
+
+router = APIRouter(prefix="/api/tutor-checkin", tags=["tutor-checkin"])
+
+
+class TutorCheckinRequest(BaseModel):
+    student_id: str
+    student_name: Optional[str] = None
+    risk_status: Optional[str] = None
+    wri: Optional[float] = None
+    weak_topics: Optional[list] = None
+    recent_activity: Optional[str] = None
+
+
+class TutorCheckinResponse(BaseModel):
+    message: str
+    tone: str
+    suggested_action: Optional[str] = None
+
+
+def _build_checkin_prompt(req: TutorCheckinRequest) -> str:
+    """Build a contextual prompt for DeepSeek to generate a tutor check-in."""
+    name = req.student_name or "Student"
+    status = req.risk_status or "unknown"
+    wri = req.wri
+    weak = req.weak_topics or []
+    activity = req.recent_activity or "No recent activity recorded."
+
+    weak_topics_str = ", ".join(weak) if weak else "none identified"
+
+    tone_map = {
+        "safe": "encouraging and celebratory",
+        "watch": "gentle and supportive",
+        "intervene": "caring but firm",
+        "critical": "urgent and deeply supportive",
+        "at_risk": "emergency-level supportive",
+    }
+    tone = tone_map.get(status, "supportive")
+
+    prompt = f"""You are MathPulse AI, a friendly and encouraging math tutor checking in on a student.
+
+Student: {name}
+Current risk status: {status}
+WRI score: {wri if wri is not None else 'N/A'}
+Weak topics: {weak_topics_str}
+Recent activity: {activity}
+
+Generate a short, personalized check-in message (2-3 sentences max) in a {tone} tone.
+The message should:
+- Acknowledge the student's current situation without being judgmental
+- Offer specific, actionable encouragement
+- Suggest ONE concrete next step they can take right now
+- Be warm, human, and written like a caring tutor, not a robot
+
+Return ONLY the message text. No JSON, no markdown, no prefixes."""
+
+    return prompt
+
+
+@router.post("", response_model=TutorCheckinResponse)
+def generate_tutor_checkin(req: TutorCheckinRequest):
+    """
+    Generate a DeepSeek-powered tutor check-in message for a student.
+    """
+    try:
+        # Lazy import to avoid startup dependency issues
+        from services.inference_client import InferenceClient
+
+        client = InferenceClient()
+        prompt = _build_checkin_prompt(req)
+
+        # Call DeepSeek with a short, fast completion
+        response = client.generate(
+            messages=[{"role": "user", "content": prompt}],
+            model="deepseek-chat",
+            temperature=0.7,
+            max_tokens=150,
+        )
+
+        message = response.strip() if response else _fallback_message(req.risk_status)
+
+        tone_map = {
+            "safe": "encouraging",
+            "watch": "supportive",
+            "intervene": "caring-but-firm",
+            "critical": "urgent",
+            "at_risk": "emergency",
+        }
+
+        return TutorCheckinResponse(
+            message=message,
+            tone=tone_map.get(req.risk_status or "", "supportive"),
+            suggested_action=_suggest_action(req.risk_status, req.weak_topics),
+        )
+
+    except Exception as e:
+        logger.error(f"[TUTOR_CHECKIN] Failed to generate check-in: {e}")
+        # Fallback to template-based message
+        return TutorCheckinResponse(
+            message=_fallback_message(req.risk_status),
+            tone="supportive",
+            suggested_action=_suggest_action(req.risk_status, req.weak_topics),
+        )
+
+
+def _fallback_message(risk_status: Optional[str]) -> str:
+    """Template-based fallback when DeepSeek is unavailable."""
+    fallbacks = {
+        "safe": "Great work! You're on track. Keep up the momentum with today's practice.",
+        "watch": "I noticed you've been working hard. Let's take a moment to review any tricky concepts together.",
+        "intervene": "Your teacher and I are here to help. Let's focus on one topic at a time — you've got this.",
+        "critical": "I'm worried about your progress. Please reach out to your teacher or start a remedial module today.",
+        "at_risk": "Your learning path is paused until your teacher reviews your progress. In the meantime, review your completed lessons.",
+    }
+    return fallbacks.get(risk_status or "", "Keep going! Every problem you solve makes you stronger.")
+
+
+def _suggest_action(risk_status: Optional[str], weak_topics: Optional[list]) -> Optional[str]:
+    """Suggest a concrete next action based on status."""
+    if risk_status == "safe":
+        return "Try a bonus challenge to stretch your skills."
+    if risk_status == "watch":
+        return "Review the hint for your last incorrect answer."
+    if risk_status == "intervene":
+        topic = weak_topics[0] if weak_topics else "your weakest topic"
+        return f"Start the remedial module on {topic}."
+    if risk_status in ("critical", "at_risk"):
+        return "Contact your teacher or start a 1-on-1 review session."
+    return None

services/wri_service.py

@@ -0,0 +1,98 @@
+"""
+WRI CLASSIFICATION — Prevention-First 5-Band System
+
+This module implements at-risk classification based on DepEd DO No. 8, s. 2015
+(Policy Guidelines on Classroom Assessment for the K to 12 Basic Education Program).
+
+Official Passing Grade: 75 (Did Not Meet Expectations = below 75)
+
+Prevention-first WRI thresholds (DepEd 75 is the FLOOR, not the trigger):
+- WRI >= 88 → safe      (On Track — no intervention needed)
+- WRI >= 80 → watch     (Slight decline — system adjusts difficulty)
+- WRI >= 75 → intervene (Approaching DepEd threshold — teacher notified)
+- WRI >= 68 → critical  (Urgent — structured intervention required)
+- WRI < 68  → at_risk   (Near or below DepEd failing mark)
+
+IMPORTANT: WRI is a SUPPORT TOOL, not a replacement for teacher judgment.
+Final academic decisions must still be made by the teacher in accordance
+with official DepEd grading policies.
+"""
+
+from typing import Optional
+
+DEFAULT_WEIGHTS = {"w1": 0.30, "w2": 0.40, "w3": 0.30}
+WEIGHT_TOLERANCE = 0.001
+
+
+def compute_wri(
+    d: Optional[float],
+    g: Optional[float],
+    p: Optional[float],
+    weights: dict = None,
+) -> dict:
+    """
+    Computes the Weighted Risk Index (WRI) and returns classification.
+    
+    Args:
+        d: Diagnostic baseline score (0-100), set once after initial assessment
+        g: External grades average (0-100), from teacher-imported class records
+        p: System performance average (0-100), from quiz/activity scores
+        weights: w1 (diagnostic), w2 (external), w3 (system) — must sum to 1.0
+    
+    Returns:
+        dict with keys:
+            wri: float (rounded to 2 decimal places) or None if D is missing
+            risk_status: 'safe' | 'watch' | 'intervene' | 'critical' | 'at_risk' | 'pending_assessment'
+            inputs: {'D': float, 'G': float, 'P': float} (actual values used, after defaults)
+            g_fallback: bool (True if G defaulted to D)
+            p_fallback: bool (True if P defaulted to D)
+    """
+    if weights is None:
+        weights = DEFAULT_WEIGHTS.copy()
+    
+    w1 = weights.get("w1", DEFAULT_WEIGHTS["w1"])
+    w2 = weights.get("w2", DEFAULT_WEIGHTS["w2"])
+    w3 = weights.get("w3", DEFAULT_WEIGHTS["w3"])
+    
+    # Validate weights sum to 1.0
+    if abs((w1 + w2 + w3) - 1.0) > WEIGHT_TOLERANCE:
+        raise ValueError(f"Weights must sum to 1.0, got w1={w1}, w2={w2}, w3={w3}")
+    
+    # Cannot compute without diagnostic baseline
+    if d is None:
+        return {
+            "wri": None,
+            "risk_status": "pending_assessment",
+            "inputs": {"D": None, "G": g, "P": p},
+            "g_fallback": False,
+            "p_fallback": False,
+        }
+    
+    # Apply defaults: missing G and/or P default to D
+    g_fallback = g is None
+    p_fallback = p is None
+    g_val = g if g is not None else d
+    p_val = p if p is not None else d
+    
+    # Compute WRI
+    wri = round((w1 * d) + (w2 * g_val) + (w3 * p_val), 2)
+    
+    # 5-band prevention-first classification
+    if wri >= 88:
+        status = "safe"
+    elif wri >= 80:
+        status = "watch"
+    elif wri >= 75:
+        status = "intervene"
+    elif wri >= 68:
+        status = "critical"
+    else:
+        status = "at_risk"
+    
+    return {
+        "wri": wri,
+        "risk_status": status,
+        "inputs": {"D": d, "G": g_val, "P": p_val},
+        "g_fallback": g_fallback,
+        "p_fallback": p_fallback,
+    }

tests/test_risk_router.py

@@ -0,0 +1,91 @@
+import pytest
+from fastapi.testclient import TestClient
+from unittest.mock import MagicMock
+
+from backend import main as main_module
+app = main_module.app
+
+# Mock auth verification so protected endpoints can run in tests without Firebase credentials.
+main_module._firebase_ready = True
+main_module._init_firebase_admin = lambda: None
+main_module.firebase_firestore = None
+main_module.firebase_auth = MagicMock()
+main_module.firebase_auth.verify_id_token = MagicMock(
+    return_value={
+        "uid": "test-teacher-uid",
+        "email": "teacher@example.com",
+        "role": "teacher",
+    }
+)
+
+client = TestClient(app, headers={"Authorization": "Bearer test-auth-token"})
+
+def test_compute_risk_safe():
+    response = client.post("/api/risk/compute", json={
+        "d": 90, "g": 90, "p": 90,
+        "weights": {"w1": 0.30, "w2": 0.40, "w3": 0.30}
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert data["wri"] == 90.0
+    assert data["risk_status"] == "safe"
+
+def test_compute_risk_at_risk():
+    response = client.post("/api/risk/compute", json={
+        "d": 60, "g": 70, "p": 65
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert data["wri"] == 65.5
+    assert data["risk_status"] == "at_risk"
+
+def test_compute_risk_intervene():
+    response = client.post("/api/risk/compute", json={
+        "d": 78, "g": 76, "p": 74
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert data["wri"] == 76.0
+    assert data["risk_status"] == "intervene"
+
+def test_compute_risk_missing_g_uses_d():
+    response = client.post("/api/risk/compute", json={
+        "d": 70, "g": None, "p": 80
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert data["g_fallback"] is True
+    # WRI = 0.3*70 + 0.4*70 + 0.3*80 = 21 + 28 + 24 = 73.0
+    assert data["wri"] == 73.0
+    assert data["risk_status"] == "critical"
+
+def test_compute_risk_no_diagnostic_returns_pending():
+    response = client.post("/api/risk/compute", json={
+        "d": None, "g": 80, "p": 90
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert data["wri"] is None
+    assert data["risk_status"] == "pending_assessment"
+
+def test_compute_risk_invalid_weights():
+    response = client.post("/api/risk/compute", json={
+        "d": 80, "g": 80, "p": 80,
+        "weights": {"w1": 0.5, "w2": 0.5, "w3": 0.5}
+    })
+    assert response.status_code == 400
+
+def test_compute_risk_batch():
+    response = client.post("/api/risk/compute/batch", json={
+        "students": [
+            {"id": "s1", "d": 90, "g": 90, "p": 90},
+            {"id": "s2", "d": 60, "g": 70, "p": 65},
+        ]
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data["results"]) == 2
+    assert data["results"][0]["id"] == "s1"
+    assert data["results"][0]["risk_status"] == "safe"
+    assert data["results"][1]["id"] == "s2"
+    assert data["results"][1]["risk_status"] == "at_risk"

tests/test_wri_service.py

@@ -0,0 +1,119 @@
+import pytest
+from services.wri_service import compute_wri
+
+class TestComputeWRI:
+    """TDD: Write failing tests first, then implement."""
+    
+    def test_standard_weights_safe(self):
+        """WRI = 0.3(90) + 0.4(90) + 0.3(90) = 90.0 → safe (>= 88)"""
+        result = compute_wri(d=90, g=90, p=90)
+        assert result["wri"] == 90.0
+        assert result["risk_status"] == "safe"
+    
+    def test_standard_weights_at_risk(self):
+        """WRI = 0.3(60) + 0.4(70) + 0.3(65) = 18 + 28 + 19.5 = 65.5 → at_risk"""
+        result = compute_wri(d=60, g=70, p=65)
+        assert result["wri"] == 65.5
+        assert result["risk_status"] == "at_risk"
+    
+    def test_standard_weights_intervene(self):
+        """WRI = 0.3(78) + 0.4(76) + 0.3(74) = 76.0 → intervene (75-79)"""
+        result = compute_wri(d=78, g=76, p=74)
+        assert result["wri"] == 76.0
+        assert result["risk_status"] == "intervene"
+    
+    def test_missing_g_defaults_to_d(self):
+        """When G is None/missing, it defaults to D value."""
+        result = compute_wri(d=70, g=None, p=80)
+        assert result["wri"] == 0.3*70 + 0.4*70 + 0.3*80  # G=70 (defaulted from D)
+        assert result["g_fallback"] is True
+    
+    def test_missing_p_defaults_to_d(self):
+        """When P is None/missing, it defaults to D value."""
+        result = compute_wri(d=75, g=85, p=None)
+        assert result["wri"] == 0.3*75 + 0.4*85 + 0.3*75  # P=75 (defaulted from D)
+        assert result["p_fallback"] is True
+    
+    def test_missing_g_and_p_both_default_to_d(self):
+        """Both G and P missing → both default to D."""
+        result = compute_wri(d=68, g=None, p=None)
+        assert result["wri"] == 0.3*68 + 0.4*68 + 0.3*68  # = 68.0
+        assert result["g_fallback"] is True
+        assert result["p_fallback"] is True
+    
+    def test_no_diagnostic_returns_none(self):
+        """When D is None → cannot compute WRI, return pending status."""
+        result = compute_wri(d=None, g=80, p=90)
+        assert result["wri"] is None
+        assert result["risk_status"] == "pending_assessment"
+    
+    def test_invalid_weights_raise_error(self):
+        """Weights that don't sum to 1.0 → ValueError."""
+        with pytest.raises(ValueError, match="Weights must sum to 1.0"):
+            compute_wri(d=80, g=80, p=80, weights={"w1": 0.5, "w2": 0.5, "w3": 0.5})
+    
+    def test_weights_close_to_one_are_valid(self):
+        """Allow small floating-point tolerance (abs diff <= 0.001)."""
+        result = compute_wri(d=90, g=90, p=90, weights={"w1": 0.333, "w2": 0.333, "w3": 0.334})
+        assert result["wri"] == 90.0
+        assert result["risk_status"] == "safe"
+    
+    def test_wri_rounds_to_2_decimal_places(self):
+        """WRI result must be rounded to 2 decimal places."""
+        result = compute_wri(d=77.777, g=88.888, p=66.666)
+        assert result["wri"] == round(0.3*77.777 + 0.4*88.888 + 0.3*66.666, 2)
+    
+    def test_boundary_88_is_safe(self):
+        """Exactly WRI=88 should be classified as safe."""
+        result = compute_wri(d=88, g=88, p=88)
+        assert result["wri"] == 88.0
+        assert result["risk_status"] == "safe"
+
+    def test_boundary_80_is_watch(self):
+        """Exactly WRI=80 should be classified as watch."""
+        result = compute_wri(d=80, g=80, p=80)
+        assert result["wri"] == 80.0
+        assert result["risk_status"] == "watch"
+
+    def test_boundary_75_is_intervene(self):
+        """Exactly WRI=75 should be classified as intervene."""
+        result = compute_wri(d=75, g=75, p=75)
+        assert result["wri"] == 75.0
+        assert result["risk_status"] == "intervene"
+
+    def test_boundary_68_is_critical(self):
+        """Exactly WRI=68 should be classified as critical."""
+        result = compute_wri(d=68, g=68, p=68)
+        assert result["wri"] == 68.0
+        assert result["risk_status"] == "critical"
+
+    def test_boundary_67_is_at_risk(self):
+        """WRI just below 68 (e.g. 67.99) should be at_risk."""
+        result = compute_wri(d=67.99, g=67.99, p=67.99)
+        assert result["wri"] == 67.99
+        assert result["risk_status"] == "at_risk"
+    
+    def test_custom_weights(self):
+        """Custom weights w1=0.2, w2=0.5, w3=0.3"""
+        result = compute_wri(d=70, g=90, p=80, weights={"w1": 0.2, "w2": 0.5, "w3": 0.3})
+        expected = 0.2*70 + 0.5*90 + 0.3*80
+        assert result["wri"] == round(expected, 2)
+    
+    def test_zero_scores(self):
+        """All zero scores → WRI = 0 → at_risk"""
+        result = compute_wri(d=0, g=0, p=0)
+        assert result["wri"] == 0.0
+        assert result["risk_status"] == "at_risk"
+    
+    def test_perfect_scores(self):
+        """All perfect scores → WRI = 100 → safe"""
+        result = compute_wri(d=100, g=100, p=100)
+        assert result["wri"] == 100.0
+        assert result["risk_status"] == "safe"
+
+    def test_result_includes_inputs(self):
+        """Result dict should include the input values used."""
+        result = compute_wri(d=80, g=85, p=90)
+        assert result["inputs"]["D"] == 80
+        assert result["inputs"]["G"] == 85
+        assert result["inputs"]["P"] == 90