🚀 Auto-deploy backend from GitHub (f081589)

Dockerfile

@@ -1,35 +1,34 @@
-FROM python:3.11-slim
-
-ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1 \
-    PIP_DISABLE_PIP_VERSION_CHECK=1 \
-    PIP_NO_CACHE_DIR=1 \
-    HF_HOME=/data/.huggingface \
-    HUGGINGFACE_HUB_CACHE=/data/.huggingface/hub \
-    TRANSFORMERS_CACHE=/data/.huggingface/transformers \
-    MPLCONFIGDIR=/tmp/matplotlib
-
-WORKDIR /app
-
-# Keep OS layer minimal and wheel-friendly.
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
-
-# Dependency layer first for better cache reuse.
-COPY requirements.txt /app/requirements.txt
-RUN python -m pip install --upgrade pip setuptools wheel && \
-    python -m pip install --prefer-binary --retries 5 -r /app/requirements.txt
-
-# Copy only runtime sources to reduce invalidation surface.
-COPY main.py /app/main.py
-COPY startup_validation.py /app/startup_validation.py
-COPY analytics.py /app/analytics.py
-COPY automation_engine.py /app/automation_engine.py
-COPY services /app/services
-COPY models /app/models
-COPY config /app/config
-
-EXPOSE 7860
-
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HF_HOME=/data/.huggingface \
+    HUGGINGFACE_HUB_CACHE=/data/.huggingface/hub \
+    TRANSFORMERS_CACHE=/data/.huggingface/transformers \
+    MPLCONFIGDIR=/tmp/matplotlib
+
+WORKDIR /app
+
+# Keep OS layer minimal and wheel-friendly.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Dependency layer first for better cache reuse.
+COPY requirements.txt /app/requirements.txt
+RUN python -m pip install --upgrade pip setuptools wheel && \
+    python -m pip install --prefer-binary --retries 5 -r /app/requirements.txt
+
+# Copy only runtime sources to reduce invalidation surface.
+COPY main.py /app/main.py
+COPY analytics.py /app/analytics.py
+COPY automation_engine.py /app/automation_engine.py
+COPY services /app/services
+COPY models /app/models
+COPY config /app/config
+
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

automation_engine.py

@@ -1,693 +1,693 @@
-"""
-MathPulse AI - Event-Driven Automation Engine
-
-Processes educational workflows based on a diagnostic-first, risk-driven
-intervention model.  Trigger points:
-
-1. Diagnostic Assessment Completion  (highest priority)
-2. Quiz / Assessment Submission       (continuous)
-3. New Student Enrollment
-4. External Data Import               (teacher action)
-5. Admin Content Updates
-
-Each event is routed to a dedicated handler that orchestrates
-classification, quiz generation, notifications and dashboard updates.
-"""
-
-import os
-import json
-import math
-import logging
-import traceback
-from typing import List, Optional, Dict, Any, Tuple
-from datetime import datetime, timedelta
-
-from pydantic import BaseModel, Field
-
-logger = logging.getLogger("mathpulse.automation")
-
-# ─── Constants ──────────────────────────────────────────────────
-
-AT_RISK_THRESHOLD = 60          # < 60 % → At Risk
-WEAK_TOPIC_THRESHOLD = 0.50     # < 50 % accuracy → weak topic
-HIGH_RISK_RATIO = 0.75          # 75 %+ subjects at risk
-MEDIUM_RISK_RATIO = 0.50        # 50-75 %
-
-REMEDIAL_CONFIG = {
-    "High":   {"questions": 15, "dist": {"easy": 60, "medium": 30, "hard": 10}},
-    "Medium": {"questions": 12, "dist": {"easy": 50, "medium": 35, "hard": 15}},
-    "Low":    {"questions": 10, "dist": {"easy": 40, "medium": 40, "hard": 20}},
-}
-
-# ─── Request / Response Models ──────────────────────────────────
-
-
-class DiagnosticResult(BaseModel):
-    """Per-subject score from diagnostic assessment."""
-    subject: str
-    score: float = Field(..., ge=0, le=100)
-
-
-class DiagnosticCompletionPayload(BaseModel):
-    """Payload sent when a student completes the diagnostic."""
-    studentId: str
-    results: List[DiagnosticResult]
-    gradeLevel: str = "Grade 10"
-    questionBreakdown: Optional[Dict[str, list]] = None   # topic → [{correct: bool, …}]
-
-
-class QuizSubmissionPayload(BaseModel):
-    """Payload sent on quiz / assessment submission."""
-    studentId: str
-    quizId: str
-    subject: str
-    score: float = Field(..., ge=0, le=100)
-    totalQuestions: int
-    correctAnswers: int
-    timeSpentSeconds: int
-    answers: Optional[List[Dict[str, Any]]] = None
-
-
-class StudentEnrollmentPayload(BaseModel):
-    """Payload sent when a new student account is created."""
-    studentId: str
-    name: str
-    email: str
-    gradeLevel: str = "Grade 10"
-    teacherId: Optional[str] = None
-
-
-class DataImportPayload(BaseModel):
-    """Payload sent after a teacher uploads a spreadsheet."""
-    teacherId: str
-    students: List[Dict[str, Any]]       # parsed student rows
-    columnMapping: Dict[str, str]
-
-
-class ContentUpdatePayload(BaseModel):
-    """Payload sent when admin performs CRUD on curriculum."""
-    adminId: str
-    action: str                           # create | update | delete
-    contentType: str                      # lesson | quiz | module | subject
-    contentId: str
-    subjectId: Optional[str] = None
-    details: Optional[str] = None
-
-
-# ─── Risk classification helpers ─────────────────────────────────
-
-
-class SubjectRiskClassification(BaseModel):
-    status: str              # "At Risk" | "On Track"
-    score: float
-    confidence: float
-    needsIntervention: bool
-
-
-class AutomationResult(BaseModel):
-    """Standardised result returned by every handler."""
-    success: bool
-    event: str
-    studentId: Optional[str] = None
-    message: str
-    riskClassifications: Optional[Dict[str, Dict[str, Any]]] = None
-    overallRisk: Optional[str] = None
-    atRiskSubjects: Optional[List[str]] = None
-    weakTopics: Optional[List[Dict[str, Any]]] = None
-    learningPath: Optional[str] = None
-    remedialQuizzesCreated: int = 0
-    interventions: Optional[str] = None
-    notifications: List[str] = Field(default_factory=list)
-
-
-# ─── Automation Engine ──────────────────────────────────────────
-
-
-class MathPulseAutomationEngine:
-    """
-    Stateless event-driven automation system.
-
-    Each ``handle_*`` method is an independent, self-contained handler that
-    receives a validated Pydantic payload and returns an ``AutomationResult``.
-    Firebase / Hugging Face calls are only attempted when available.
-    """
-
-    # ────────────────────────────────────────────────────────────
-    # 1. DIAGNOSTIC COMPLETION  (highest-priority)
-    # ───────────────────────────────────���────────────────────────
-
-    async def handle_diagnostic_completion(
-        self, payload: DiagnosticCompletionPayload
-    ) -> AutomationResult:
-        """
-        Runs when a student completes the mandatory diagnostic.
-
-        Steps:
-        1. Classify per-subject risk
-        2. Identify weak topics
-        3. Compute overall risk
-        4. Generate personalised learning path (AI)
-        5. Create remedial quiz assignments
-        6. Generate teacher intervention recommendations (AI)
-        7. Persist everything & notify
-        """
-        student_id = payload.studentId
-        logger.info(f"📊 DIAGNOSTIC COMPLETED for {student_id}")
-        notifications: list[str] = []
-
-        # 1 — subject-level risk
-        risk_classifications = self._classify_subject_risks(payload.results)
-
-        # 2 — weak topics
-        weak_topics = self._identify_weak_topics(payload.questionBreakdown)
-
-        # 3 — overall risk
-        overall_risk = self._calculate_overall_risk(risk_classifications)
-
-        at_risk_subjects = [
-            subj for subj, data in risk_classifications.items()
-            if data["status"] == "At Risk"
-        ]
-
-        # 4 — learning path (AI call)
-        learning_path: Optional[str] = None
-        if at_risk_subjects:
-            learning_path = await self._generate_learning_path(
-                at_risk_subjects, weak_topics, payload.gradeLevel
-            )
-
-        # 5 — remedial quizzes
-        remedial_count = 0
-        remedial_quizzes: list[dict] = []
-        if at_risk_subjects:
-            remedial_quizzes = self._build_remedial_quiz_configs(
-                student_id, at_risk_subjects, overall_risk, payload.gradeLevel
-            )
-            remedial_count = len(remedial_quizzes)
-
-        # 6 — teacher interventions (AI call)
-        interventions: Optional[str] = None
-        if at_risk_subjects:
-            interventions = await self._generate_teacher_interventions(
-                risk_classifications, weak_topics
-            )
-
-        # 7 — notification messages
-        if at_risk_subjects:
-            notifications.append(
-                f"Diagnostic complete — {len(at_risk_subjects)} subject(s) flagged At Risk: "
-                + ", ".join(at_risk_subjects)
-            )
-        else:
-            notifications.append("Diagnostic complete — all subjects On Track!")
-
-        logger.info(
-            f"✅ DIAGNOSTIC PROCESSING COMPLETE for {student_id} | "
-            f"Overall={overall_risk} | AtRisk={at_risk_subjects}"
-        )
-
-        return AutomationResult(
-            success=True,
-            event="diagnostic_completed",
-            studentId=student_id,
-            message=f"Diagnostic processed for {student_id}",
-            riskClassifications=risk_classifications,
-            overallRisk=overall_risk,
-            atRiskSubjects=at_risk_subjects,
-            weakTopics=weak_topics,
-            learningPath=learning_path,
-            remedialQuizzesCreated=remedial_count,
-            interventions=interventions,
-            notifications=notifications,
-        )
-
-    # ────────────────────────────────────────────────────────────
-    # 2. QUIZ SUBMISSION  (continuous)
-    # ────────────────────────────────────────────────────────────
-
-    async def handle_quiz_submission(
-        self, payload: QuizSubmissionPayload
-    ) -> AutomationResult:
-        """Recalculate risk for a subject after a quiz is submitted."""
-        student_id = payload.studentId
-        logger.info(f"📝 QUIZ SUBMITTED by {student_id} — {payload.subject} ({payload.score}%)")
-        notifications: list[str] = []
-
-        # Determine new status for this subject
-        new_status = "At Risk" if payload.score < AT_RISK_THRESHOLD else "On Track"
-        confidence = (
-            (AT_RISK_THRESHOLD - payload.score) / AT_RISK_THRESHOLD
-            if new_status == "At Risk"
-            else (payload.score - AT_RISK_THRESHOLD) / (100 - AT_RISK_THRESHOLD)
-        )
-
-        risk_classifications = {
-            payload.subject: {
-                "status": new_status,
-                "score": payload.score,
-                "confidence": round(abs(confidence), 2),
-                "needsIntervention": new_status == "At Risk",
-            }
-        }
-
-        at_risk = [payload.subject] if new_status == "At Risk" else []
-
-        if new_status == "At Risk":
-            notifications.append(
-                f"Quiz result: {payload.subject} scored {payload.score}% — status changed to At Risk"
-            )
-        else:
-            notifications.append(
-                f"Quiz result: {payload.subject} scored {payload.score}% — On Track"
-            )
-
-        return AutomationResult(
-            success=True,
-            event="quiz_submitted",
-            studentId=student_id,
-            message=f"Quiz processed for {student_id}",
-            riskClassifications=risk_classifications,
-            overallRisk=None,   # single-subject update — overall recalculated on frontend
-            atRiskSubjects=at_risk,
-            notifications=notifications,
-        )
-
-    # ────────────────────────────────────────────────────────────
-    # 3. STUDENT ENROLLMENT
-    # ────────────────────────────────────────────────────────────
-
-    async def handle_student_enrollment(
-        self, payload: StudentEnrollmentPayload
-    ) -> AutomationResult:
-        """
-        Prepare a new student:
-        - Create empty progress record skeleton
-        - Initialise gamification (XP 0, Level 1, no streaks)
-        - Flag as needing diagnostic
-        """
-        student_id = payload.studentId
-        logger.info(f"🆕 NEW STUDENT ENROLLED: {student_id}")
-
-        progress_skeleton = {
-            "userId": student_id,
-            "subjects": {},
-            "lessons": {},
-            "quizAttempts": [],
-            "totalLessonsCompleted": 0,
-            "totalQuizzesCompleted": 0,
-            "averageScore": 0,
-        }
-
-        gamification_init = {
-            "level": 1,
-            "currentXP": 0,
-            "totalXP": 0,
-            "streak": 0,
-            "hasTakenDiagnostic": False,
-            "atRiskSubjects": [],
-        }
-
-        notifications: list[str] = [
-            f"Welcome {payload.name}! Please complete the diagnostic assessment to personalise your learning path.",
-        ]
-
-        if payload.teacherId:
-            notifications.append(
-                f"New student {payload.name} enrolled — diagnostic pending."
-            )
-
-        return AutomationResult(
-            success=True,
-            event="student_enrolled",
-            studentId=student_id,
-            message=f"Student {payload.name} enrolled and initialised",
-            notifications=notifications,
-        )
-
-    # ────────────────────────────────────────────────────────────
-    # 4. DATA IMPORT  (teacher action)
-    # ────────────────────────────────────────────────────────────
-
-    async def handle_data_import(
-        self, payload: DataImportPayload
-    ) -> AutomationResult:
-        """
-        After a teacher uploads a spreadsheet, recalculate risk for every
-        imported student and flag any status changes.
-        """
-        logger.info(f"📂 DATA IMPORT by teacher {payload.teacherId} — {len(payload.students)} students")
-        notifications: list[str] = []
-        high_risk_students: list[str] = []
-        medium_risk_count = 0
-        low_risk_count = 0
-        weak_topic_counts: Dict[str, int] = {}
-
-        for student_row in payload.students:
-            name = str(student_row.get("name") or "Unknown").strip() or "Unknown"
-            avg_score = self._safe_float(student_row.get("avgQuizScore"), 0.0)
-            attendance = self._safe_float(student_row.get("attendance"), 0.0)
-            engagement = self._safe_float(student_row.get("engagementScore"), 0.0)
-            completion_raw = student_row.get("assignmentCompletion")
-            completion = (
-                self._safe_float(completion_raw, 0.0)
-                if completion_raw not in (None, "")
-                else None
-            )
-
-            risk_level = self._classify_import_risk(
-                avg_score=avg_score,
-                attendance=attendance,
-                engagement=engagement,
-                completion=completion,
-            )
-            if risk_level == "High":
-                high_risk_students.append(name)
-            elif risk_level == "Medium":
-                medium_risk_count += 1
-            else:
-                low_risk_count += 1
-
-            topic_label = self._extract_import_topic(student_row)
-            if topic_label:
-                weak_topic_counts[topic_label] = weak_topic_counts.get(topic_label, 0) + 1
-
-        if high_risk_students:
-            notifications.append(
-                f"Data import flagged {len(high_risk_students)} high-risk student(s): "
-                + ", ".join(high_risk_students[:5])
-                + ("..." if len(high_risk_students) > 5 else "")
-            )
-
-        notifications.append(
-            "Risk interpretation summary — "
-            f"High: {len(high_risk_students)}, Medium: {medium_risk_count}, Low: {low_risk_count}."
-        )
-
-        if weak_topic_counts:
-            top_topics = sorted(
-                weak_topic_counts.items(),
-                key=lambda item: (-item[1], item[0]),
-            )[:3]
-            notifications.append(
-                "Most frequent weak-topic signals: "
-                + ", ".join(f"{topic} ({count})" for topic, count in top_topics)
-            )
-
-        notifications.append(
-            f"Data import complete — {len(payload.students)} student records processed."
-        )
-
-        return AutomationResult(
-            success=True,
-            event="data_imported",
-            studentId=None,
-            message=f"Data import processed for {len(payload.students)} students",
-            atRiskSubjects=None,
-            notifications=notifications,
-        )
-
-    # ────────────────────────────────────────────────────────────
-    # 5. CONTENT UPDATE  (admin action)
-    # ────────────────────────────────────────────────────────────
-
-    async def handle_content_update(
-        self, payload: ContentUpdatePayload
-    ) -> AutomationResult:
-        """
-        After admin CRUD on curriculum, log & notify.
-        """
-        logger.info(
-            f"📚 CONTENT UPDATE by admin {payload.adminId}: "
-            f"{payload.action} {payload.contentType} {payload.contentId}"
-        )
-        notifications: list[str] = [
-            f"Curriculum update: {payload.action}d {payload.contentType} "
-            f"({payload.contentId}). Teachers may want to review affected quizzes.",
-        ]
-
-        return AutomationResult(
-            success=True,
-            event="content_updated",
-            studentId=None,
-            message=f"Content {payload.action} processed for {payload.contentType}",
-            notifications=notifications,
-        )
-
-    # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    #  INTERNAL HELPERS
-    # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    # --- risk classification ---
-
-    @staticmethod
-    def _safe_float(value: Any, default: float = 0.0) -> float:
-        try:
-            parsed = float(value)
-            if math.isnan(parsed) or math.isinf(parsed):
-                return default
-            return parsed
-        except (TypeError, ValueError):
-            return default
-
-    @staticmethod
-    def _classify_import_risk(
-        *,
-        avg_score: float,
-        attendance: float,
-        engagement: float,
-        completion: Optional[float],
-    ) -> str:
-        high_flags = int(avg_score < 60) + int(attendance < 75) + int(engagement < 55)
-        medium_flags = int(avg_score < 75) + int(attendance < 85) + int(engagement < 70)
-
-        if completion is not None:
-            high_flags += int(completion < 60)
-            medium_flags += int(completion < 75)
-
-        if high_flags >= 2 or (avg_score < 55 and (attendance < 80 or engagement < 65)):
-            return "High"
-        if medium_flags >= 2:
-            return "Medium"
-        return "Low"
-
-    @staticmethod
-    def _extract_import_topic(student_row: Dict[str, Any]) -> Optional[str]:
-        explicit_topic = str(student_row.get("weakestTopic") or "").strip()
-        if explicit_topic:
-            return explicit_topic
-
-        assessment_name = str(student_row.get("assessmentName") or "").strip()
-        if assessment_name and assessment_name.lower() != "general-assessment":
-            return assessment_name
-
-        return None
-
-    @staticmethod
-    def _classify_subject_risks(
-        results: List[DiagnosticResult],
-    ) -> Dict[str, Dict[str, Any]]:
-        """Classify each subject as 'At Risk' or 'On Track'."""
-        classifications: Dict[str, Dict[str, Any]] = {}
-        for r in results:
-            if r.score < AT_RISK_THRESHOLD:
-                status = "At Risk"
-                confidence = round((AT_RISK_THRESHOLD - r.score) / AT_RISK_THRESHOLD, 2)
-            else:
-                status = "On Track"
-                confidence = round(
-                    (r.score - AT_RISK_THRESHOLD) / (100 - AT_RISK_THRESHOLD), 2
-                )
-            classifications[r.subject] = {
-                "status": status,
-                "score": r.score,
-                "confidence": confidence,
-                "needsIntervention": status == "At Risk",
-            }
-        return classifications
-
-    @staticmethod
-    def _identify_weak_topics(
-        question_breakdown: Optional[Dict[str, list]],
-    ) -> List[Dict[str, Any]]:
-        """
-        Drill into per-topic accuracy from diagnostic question-level data.
-        Returns topics sorted weakest-first.
-        """
-        if not question_breakdown:
-            return []
-
-        weak: list[dict] = []
-        for topic, questions in question_breakdown.items():
-            if not questions:
-                continue
-            correct_count = sum(1 for q in questions if q.get("correct"))
-            accuracy = correct_count / len(questions)
-            if accuracy < WEAK_TOPIC_THRESHOLD:
-                weak.append({
-                    "topic": topic,
-                    "accuracy": round(accuracy, 2),
-                    "questionsAttempted": len(questions),
-                    "priority": "high" if accuracy < 0.3 else "medium",
-                })
-        weak.sort(key=lambda x: x["accuracy"])
-        return weak
-
-    @staticmethod
-    def _calculate_overall_risk(
-        classifications: Dict[str, Dict[str, Any]],
-    ) -> str:
-        total = len(classifications)
-        if total == 0:
-            return "Low"
-        at_risk_count = sum(
-            1 for d in classifications.values() if d["status"] == "At Risk"
-        )
-        ratio = at_risk_count / total
-        if ratio >= HIGH_RISK_RATIO:
-            return "High"
-        elif ratio >= MEDIUM_RISK_RATIO:
-            return "Medium"
-        return "Low"
-
-    # --- remedial quiz configs ---
-
-    @staticmethod
-    def _build_remedial_quiz_configs(
-        student_id: str,
-        at_risk_subjects: List[str],
-        overall_risk: str,
-        grade_level: str,
-    ) -> List[Dict[str, Any]]:
-        """Return list of quiz configuration dicts ready for persistence."""
-        cfg = REMEDIAL_CONFIG.get(overall_risk, REMEDIAL_CONFIG["Low"])
-        quizzes: list[dict] = []
-        for subject in at_risk_subjects:
-            quizzes.append({
-                "studentId": student_id,
-                "subject": subject,
-                "quizConfig": {
-                    "topics": [subject],
-                    "gradeLevel": grade_level,
-                    "numQuestions": cfg["questions"],
-                    "questionTypes": [
-                        "identification",
-                        "enumeration",
-                        "multiple_choice",
-                        "word_problem",
-                    ],
-                    "difficultyDistribution": cfg["dist"],
-                    "bloomLevels": ["remember", "understand", "apply"],
-                    "includeGraphs": False,
-                    "excludeTopics": [],
-                    "purpose": "remedial",
-                    "targetStudent": student_id,
-                },
-                "status": "pending",
-                "autoGenerated": True,
-                "reason": f'Diagnostic identified "{subject}" as At Risk',
-                "priority": "high" if overall_risk == "High" else "medium",
-                "dueInDays": 7,
-            })
-        return quizzes
-
-    # --- AI helpers (Hugging Face) ---
-
-    async def _generate_learning_path(
-        self,
-        at_risk_subjects: List[str],
-        weak_topics: List[Dict[str, Any]],
-        grade_level: str,
-    ) -> Optional[str]:
-        """Generate a personalised learning path via HF Serverless Inference."""
-        try:
-            from main import call_hf_chat
-
-            weakness_lines = ", ".join(at_risk_subjects)
-            topic_lines = "\n".join(
-                f"  - {t['topic']} ({t['accuracy']*100:.0f}% accuracy)"
-                for t in weak_topics[:5]
-            )
-
-            prompt = (
-                f"Generate a personalised math learning path for a {grade_level} student.\n\n"
-                f"Weak subjects: {weakness_lines}\n"
-                f"Weak topics:\n{topic_lines}\n\n"
-                "Create 5-7 specific activities. For each give:\n"
-                "1. Activity title\n"
-                "2. Brief description (1-2 sentences)\n"
-                "3. Estimated duration\n"
-                "4. Type (video, practice, quiz, reading, interactive)\n\n"
-                "Format as a numbered list. Be specific."
-            )
-
-            return call_hf_chat(
-                messages=[
-                    {
-                        "role": "system",
-                        "content": (
-                            "You are an educational curriculum expert specialising in "
-                            "mathematics. Create clear, actionable learning paths."
-                        ),
-                    },
-                    {"role": "user", "content": prompt},
-                ],
-                max_tokens=1500,
-                temperature=0.7,
-            )
-        except Exception as e:
-            logger.warning(f"Learning-path AI call failed: {e}")
-            return None
-
-    async def _generate_teacher_interventions(
-        self,
-        risk_classifications: Dict[str, Dict[str, Any]],
-        weak_topics: List[Dict[str, Any]],
-    ) -> Optional[str]:
-        """Generate teacher intervention recommendations via HF Serverless Inference."""
-        try:
-            from main import call_hf_chat
-
-            at_risk = [
-                subj for subj, data in risk_classifications.items()
-                if data["status"] == "At Risk"
-            ]
-            topic_lines = "\n".join(
-                f"- {t['topic']} ({t['accuracy']*100:.0f}% accuracy)"
-                for t in weak_topics[:5]
-            )
-
-            prompt = (
-                "You are an educational intervention specialist. A student has completed "
-                "their diagnostic assessment with the following results:\n\n"
-                f"At-Risk Subjects: {', '.join(at_risk)}\n\n"
-                f"Weak Topics Identified:\n{topic_lines}\n\n"
-                "Generate a 'Remedial Path Timeline' with:\n"
-                "1. Prioritised list of topics to address (most critical first)\n"
-                "2. Suggested teaching strategies for each topic\n"
-                "3. Recommended one-on-one intervention activities\n"
-                "4. Timeline for reassessment\n"
-                "5. Warning signs that student needs additional support\n\n"
-                "Keep response under 300 words, structured with clear sections."
-            )
-
-            return call_hf_chat(
-                messages=[
-                    {
-                        "role": "system",
-                        "content": (
-                            "You are an expert educational intervention specialist. "
-                            "Provide actionable, structured recommendations for teachers."
-                        ),
-                    },
-                    {"role": "user", "content": prompt},
-                ],
-                max_tokens=1000,
-                temperature=0.5,
-            )
-        except Exception as e:
-            logger.warning(f"Teacher-intervention AI call failed: {e}")
-            return None
-
-
-# Module-level singleton
-automation_engine = MathPulseAutomationEngine()
+"""
+MathPulse AI - Event-Driven Automation Engine
+
+Processes educational workflows based on a diagnostic-first, risk-driven
+intervention model.  Trigger points:
+
+1. Diagnostic Assessment Completion  (highest priority)
+2. Quiz / Assessment Submission       (continuous)
+3. New Student Enrollment
+4. External Data Import               (teacher action)
+5. Admin Content Updates
+
+Each event is routed to a dedicated handler that orchestrates
+classification, quiz generation, notifications and dashboard updates.
+"""
+
+import os
+import json
+import math
+import logging
+import traceback
+from typing import List, Optional, Dict, Any, Tuple
+from datetime import datetime, timedelta
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger("mathpulse.automation")
+
+# ─── Constants ──────────────────────────────────────────────────
+
+AT_RISK_THRESHOLD = 60          # < 60 % → At Risk
+WEAK_TOPIC_THRESHOLD = 0.50     # < 50 % accuracy → weak topic
+HIGH_RISK_RATIO = 0.75          # 75 %+ subjects at risk
+MEDIUM_RISK_RATIO = 0.50        # 50-75 %
+
+REMEDIAL_CONFIG = {
+    "High":   {"questions": 15, "dist": {"easy": 60, "medium": 30, "hard": 10}},
+    "Medium": {"questions": 12, "dist": {"easy": 50, "medium": 35, "hard": 15}},
+    "Low":    {"questions": 10, "dist": {"easy": 40, "medium": 40, "hard": 20}},
+}
+
+# ─── Request / Response Models ──────────────────────────────────
+
+
+class DiagnosticResult(BaseModel):
+    """Per-subject score from diagnostic assessment."""
+    subject: str
+    score: float = Field(..., ge=0, le=100)
+
+
+class DiagnosticCompletionPayload(BaseModel):
+    """Payload sent when a student completes the diagnostic."""
+    studentId: str
+    results: List[DiagnosticResult]
+    gradeLevel: str = "Grade 10"
+    questionBreakdown: Optional[Dict[str, list]] = None   # topic → [{correct: bool, …}]
+
+
+class QuizSubmissionPayload(BaseModel):
+    """Payload sent on quiz / assessment submission."""
+    studentId: str
+    quizId: str
+    subject: str
+    score: float = Field(..., ge=0, le=100)
+    totalQuestions: int
+    correctAnswers: int
+    timeSpentSeconds: int
+    answers: Optional[List[Dict[str, Any]]] = None
+
+
+class StudentEnrollmentPayload(BaseModel):
+    """Payload sent when a new student account is created."""
+    studentId: str
+    name: str
+    email: str
+    gradeLevel: str = "Grade 10"
+    teacherId: Optional[str] = None
+
+
+class DataImportPayload(BaseModel):
+    """Payload sent after a teacher uploads a spreadsheet."""
+    teacherId: str
+    students: List[Dict[str, Any]]       # parsed student rows
+    columnMapping: Dict[str, str]
+
+
+class ContentUpdatePayload(BaseModel):
+    """Payload sent when admin performs CRUD on curriculum."""
+    adminId: str
+    action: str                           # create | update | delete
+    contentType: str                      # lesson | quiz | module | subject
+    contentId: str
+    subjectId: Optional[str] = None
+    details: Optional[str] = None
+
+
+# ─── Risk classification helpers ─────────────────────────────────
+
+
+class SubjectRiskClassification(BaseModel):
+    status: str              # "At Risk" | "On Track"
+    score: float
+    confidence: float
+    needsIntervention: bool
+
+
+class AutomationResult(BaseModel):
+    """Standardised result returned by every handler."""
+    success: bool
+    event: str
+    studentId: Optional[str] = None
+    message: str
+    riskClassifications: Optional[Dict[str, Dict[str, Any]]] = None
+    overallRisk: Optional[str] = None
+    atRiskSubjects: Optional[List[str]] = None
+    weakTopics: Optional[List[Dict[str, Any]]] = None
+    learningPath: Optional[str] = None
+    remedialQuizzesCreated: int = 0
+    interventions: Optional[str] = None
+    notifications: List[str] = Field(default_factory=list)
+
+
+# ─── Automation Engine ──────────────────────────────────────────
+
+
+class MathPulseAutomationEngine:
+    """
+    Stateless event-driven automation system.
+
+    Each ``handle_*`` method is an independent, self-contained handler that
+    receives a validated Pydantic payload and returns an ``AutomationResult``.
+    Firebase / Hugging Face calls are only attempted when available.
+    """
+
+    # ────────────────────────────────────────────────────────────
+    # 1. DIAGNOSTIC COMPLETION  (highest-priority)
+    # ────────────────────────────────────────────────────────────
+
+    async def handle_diagnostic_completion(
+        self, payload: DiagnosticCompletionPayload
+    ) -> AutomationResult:
+        """
+        Runs when a student completes the mandatory diagnostic.
+
+        Steps:
+        1. Classify per-subject risk
+        2. Identify weak topics
+        3. Compute overall risk
+        4. Generate personalised learning path (AI)
+        5. Create remedial quiz assignments
+        6. Generate teacher intervention recommendations (AI)
+        7. Persist everything & notify
+        """
+        student_id = payload.studentId
+        logger.info(f"📊 DIAGNOSTIC COMPLETED for {student_id}")
+        notifications: list[str] = []
+
+        # 1 — subject-level risk
+        risk_classifications = self._classify_subject_risks(payload.results)
+
+        # 2 — weak topics
+        weak_topics = self._identify_weak_topics(payload.questionBreakdown)
+
+        # 3 — overall risk
+        overall_risk = self._calculate_overall_risk(risk_classifications)
+
+        at_risk_subjects = [
+            subj for subj, data in risk_classifications.items()
+            if data["status"] == "At Risk"
+        ]
+
+        # 4 — learning path (AI call)
+        learning_path: Optional[str] = None
+        if at_risk_subjects:
+            learning_path = await self._generate_learning_path(
+                at_risk_subjects, weak_topics, payload.gradeLevel
+            )
+
+        # 5 — remedial quizzes
+        remedial_count = 0
+        remedial_quizzes: list[dict] = []
+        if at_risk_subjects:
+            remedial_quizzes = self._build_remedial_quiz_configs(
+                student_id, at_risk_subjects, overall_risk, payload.gradeLevel
+            )
+            remedial_count = len(remedial_quizzes)
+
+        # 6 — teacher interventions (AI call)
+        interventions: Optional[str] = None
+        if at_risk_subjects:
+            interventions = await self._generate_teacher_interventions(
+                risk_classifications, weak_topics
+            )
+
+        # 7 — notification messages
+        if at_risk_subjects:
+            notifications.append(
+                f"Diagnostic complete — {len(at_risk_subjects)} subject(s) flagged At Risk: "
+                + ", ".join(at_risk_subjects)
+            )
+        else:
+            notifications.append("Diagnostic complete — all subjects On Track!")
+
+        logger.info(
+            f"✅ DIAGNOSTIC PROCESSING COMPLETE for {student_id} | "
+            f"Overall={overall_risk} | AtRisk={at_risk_subjects}"
+        )
+
+        return AutomationResult(
+            success=True,
+            event="diagnostic_completed",
+            studentId=student_id,
+            message=f"Diagnostic processed for {student_id}",
+            riskClassifications=risk_classifications,
+            overallRisk=overall_risk,
+            atRiskSubjects=at_risk_subjects,
+            weakTopics=weak_topics,
+            learningPath=learning_path,
+            remedialQuizzesCreated=remedial_count,
+            interventions=interventions,
+            notifications=notifications,
+        )
+
+    # ────────────────────────────────────────────────────────────
+    # 2. QUIZ SUBMISSION  (continuous)
+    # ────────────────────────────────────────────────────────────
+
+    async def handle_quiz_submission(
+        self, payload: QuizSubmissionPayload
+    ) -> AutomationResult:
+        """Recalculate risk for a subject after a quiz is submitted."""
+        student_id = payload.studentId
+        logger.info(f"📝 QUIZ SUBMITTED by {student_id} — {payload.subject} ({payload.score}%)")
+        notifications: list[str] = []
+
+        # Determine new status for this subject
+        new_status = "At Risk" if payload.score < AT_RISK_THRESHOLD else "On Track"
+        confidence = (
+            (AT_RISK_THRESHOLD - payload.score) / AT_RISK_THRESHOLD
+            if new_status == "At Risk"
+            else (payload.score - AT_RISK_THRESHOLD) / (100 - AT_RISK_THRESHOLD)
+        )
+
+        risk_classifications = {
+            payload.subject: {
+                "status": new_status,
+                "score": payload.score,
+                "confidence": round(abs(confidence), 2),
+                "needsIntervention": new_status == "At Risk",
+            }
+        }
+
+        at_risk = [payload.subject] if new_status == "At Risk" else []
+
+        if new_status == "At Risk":
+            notifications.append(
+                f"Quiz result: {payload.subject} scored {payload.score}% — status changed to At Risk"
+            )
+        else:
+            notifications.append(
+                f"Quiz result: {payload.subject} scored {payload.score}% — On Track"
+            )
+
+        return AutomationResult(
+            success=True,
+            event="quiz_submitted",
+            studentId=student_id,
+            message=f"Quiz processed for {student_id}",
+            riskClassifications=risk_classifications,
+            overallRisk=None,   # single-subject update — overall recalculated on frontend
+            atRiskSubjects=at_risk,
+            notifications=notifications,
+        )
+
+    # ────────────────────────────────────────────────────────────
+    # 3. STUDENT ENROLLMENT
+    # ────────────────────────────────────────────────────────────
+
+    async def handle_student_enrollment(
+        self, payload: StudentEnrollmentPayload
+    ) -> AutomationResult:
+        """
+        Prepare a new student:
+        - Create empty progress record skeleton
+        - Initialise gamification (XP 0, Level 1, no streaks)
+        - Flag as needing diagnostic
+        """
+        student_id = payload.studentId
+        logger.info(f"🆕 NEW STUDENT ENROLLED: {student_id}")
+
+        progress_skeleton = {
+            "userId": student_id,
+            "subjects": {},
+            "lessons": {},
+            "quizAttempts": [],
+            "totalLessonsCompleted": 0,
+            "totalQuizzesCompleted": 0,
+            "averageScore": 0,
+        }
+
+        gamification_init = {
+            "level": 1,
+            "currentXP": 0,
+            "totalXP": 0,
+            "streak": 0,
+            "hasTakenDiagnostic": False,
+            "atRiskSubjects": [],
+        }
+
+        notifications: list[str] = [
+            f"Welcome {payload.name}! Please complete the diagnostic assessment to personalise your learning path.",
+        ]
+
+        if payload.teacherId:
+            notifications.append(
+                f"New student {payload.name} enrolled — diagnostic pending."
+            )
+
+        return AutomationResult(
+            success=True,
+            event="student_enrolled",
+            studentId=student_id,
+            message=f"Student {payload.name} enrolled and initialised",
+            notifications=notifications,
+        )
+
+    # ────────────────────────────────────────────────────────────
+    # 4. DATA IMPORT  (teacher action)
+    # ──────────────────────────────────────────────────────────���─
+
+    async def handle_data_import(
+        self, payload: DataImportPayload
+    ) -> AutomationResult:
+        """
+        After a teacher uploads a spreadsheet, recalculate risk for every
+        imported student and flag any status changes.
+        """
+        logger.info(f"📂 DATA IMPORT by teacher {payload.teacherId} — {len(payload.students)} students")
+        notifications: list[str] = []
+        high_risk_students: list[str] = []
+        medium_risk_count = 0
+        low_risk_count = 0
+        weak_topic_counts: Dict[str, int] = {}
+
+        for student_row in payload.students:
+            name = str(student_row.get("name") or "Unknown").strip() or "Unknown"
+            avg_score = self._safe_float(student_row.get("avgQuizScore"), 0.0)
+            attendance = self._safe_float(student_row.get("attendance"), 0.0)
+            engagement = self._safe_float(student_row.get("engagementScore"), 0.0)
+            completion_raw = student_row.get("assignmentCompletion")
+            completion = (
+                self._safe_float(completion_raw, 0.0)
+                if completion_raw not in (None, "")
+                else None
+            )
+
+            risk_level = self._classify_import_risk(
+                avg_score=avg_score,
+                attendance=attendance,
+                engagement=engagement,
+                completion=completion,
+            )
+            if risk_level == "High":
+                high_risk_students.append(name)
+            elif risk_level == "Medium":
+                medium_risk_count += 1
+            else:
+                low_risk_count += 1
+
+            topic_label = self._extract_import_topic(student_row)
+            if topic_label:
+                weak_topic_counts[topic_label] = weak_topic_counts.get(topic_label, 0) + 1
+
+        if high_risk_students:
+            notifications.append(
+                f"Data import flagged {len(high_risk_students)} high-risk student(s): "
+                + ", ".join(high_risk_students[:5])
+                + ("..." if len(high_risk_students) > 5 else "")
+            )
+
+        notifications.append(
+            "Risk interpretation summary — "
+            f"High: {len(high_risk_students)}, Medium: {medium_risk_count}, Low: {low_risk_count}."
+        )
+
+        if weak_topic_counts:
+            top_topics = sorted(
+                weak_topic_counts.items(),
+                key=lambda item: (-item[1], item[0]),
+            )[:3]
+            notifications.append(
+                "Most frequent weak-topic signals: "
+                + ", ".join(f"{topic} ({count})" for topic, count in top_topics)
+            )
+
+        notifications.append(
+            f"Data import complete — {len(payload.students)} student records processed."
+        )
+
+        return AutomationResult(
+            success=True,
+            event="data_imported",
+            studentId=None,
+            message=f"Data import processed for {len(payload.students)} students",
+            atRiskSubjects=None,
+            notifications=notifications,
+        )
+
+    # ────────────────────────────────────────────────────────────
+    # 5. CONTENT UPDATE  (admin action)
+    # ────────────────────────────────────────────────────────────
+
+    async def handle_content_update(
+        self, payload: ContentUpdatePayload
+    ) -> AutomationResult:
+        """
+        After admin CRUD on curriculum, log & notify.
+        """
+        logger.info(
+            f"📚 CONTENT UPDATE by admin {payload.adminId}: "
+            f"{payload.action} {payload.contentType} {payload.contentId}"
+        )
+        notifications: list[str] = [
+            f"Curriculum update: {payload.action}d {payload.contentType} "
+            f"({payload.contentId}). Teachers may want to review affected quizzes.",
+        ]
+
+        return AutomationResult(
+            success=True,
+            event="content_updated",
+            studentId=None,
+            message=f"Content {payload.action} processed for {payload.contentType}",
+            notifications=notifications,
+        )
+
+    # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    #  INTERNAL HELPERS
+    # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    # --- risk classification ---
+
+    @staticmethod
+    def _safe_float(value: Any, default: float = 0.0) -> float:
+        try:
+            parsed = float(value)
+            if math.isnan(parsed) or math.isinf(parsed):
+                return default
+            return parsed
+        except (TypeError, ValueError):
+            return default
+
+    @staticmethod
+    def _classify_import_risk(
+        *,
+        avg_score: float,
+        attendance: float,
+        engagement: float,
+        completion: Optional[float],
+    ) -> str:
+        high_flags = int(avg_score < 60) + int(attendance < 75) + int(engagement < 55)
+        medium_flags = int(avg_score < 75) + int(attendance < 85) + int(engagement < 70)
+
+        if completion is not None:
+            high_flags += int(completion < 60)
+            medium_flags += int(completion < 75)
+
+        if high_flags >= 2 or (avg_score < 55 and (attendance < 80 or engagement < 65)):
+            return "High"
+        if medium_flags >= 2:
+            return "Medium"
+        return "Low"
+
+    @staticmethod
+    def _extract_import_topic(student_row: Dict[str, Any]) -> Optional[str]:
+        explicit_topic = str(student_row.get("weakestTopic") or "").strip()
+        if explicit_topic:
+            return explicit_topic
+
+        assessment_name = str(student_row.get("assessmentName") or "").strip()
+        if assessment_name and assessment_name.lower() != "general-assessment":
+            return assessment_name
+
+        return None
+
+    @staticmethod
+    def _classify_subject_risks(
+        results: List[DiagnosticResult],
+    ) -> Dict[str, Dict[str, Any]]:
+        """Classify each subject as 'At Risk' or 'On Track'."""
+        classifications: Dict[str, Dict[str, Any]] = {}
+        for r in results:
+            if r.score < AT_RISK_THRESHOLD:
+                status = "At Risk"
+                confidence = round((AT_RISK_THRESHOLD - r.score) / AT_RISK_THRESHOLD, 2)
+            else:
+                status = "On Track"
+                confidence = round(
+                    (r.score - AT_RISK_THRESHOLD) / (100 - AT_RISK_THRESHOLD), 2
+                )
+            classifications[r.subject] = {
+                "status": status,
+                "score": r.score,
+                "confidence": confidence,
+                "needsIntervention": status == "At Risk",
+            }
+        return classifications
+
+    @staticmethod
+    def _identify_weak_topics(
+        question_breakdown: Optional[Dict[str, list]],
+    ) -> List[Dict[str, Any]]:
+        """
+        Drill into per-topic accuracy from diagnostic question-level data.
+        Returns topics sorted weakest-first.
+        """
+        if not question_breakdown:
+            return []
+
+        weak: list[dict] = []
+        for topic, questions in question_breakdown.items():
+            if not questions:
+                continue
+            correct_count = sum(1 for q in questions if q.get("correct"))
+            accuracy = correct_count / len(questions)
+            if accuracy < WEAK_TOPIC_THRESHOLD:
+                weak.append({
+                    "topic": topic,
+                    "accuracy": round(accuracy, 2),
+                    "questionsAttempted": len(questions),
+                    "priority": "high" if accuracy < 0.3 else "medium",
+                })
+        weak.sort(key=lambda x: x["accuracy"])
+        return weak
+
+    @staticmethod
+    def _calculate_overall_risk(
+        classifications: Dict[str, Dict[str, Any]],
+    ) -> str:
+        total = len(classifications)
+        if total == 0:
+            return "Low"
+        at_risk_count = sum(
+            1 for d in classifications.values() if d["status"] == "At Risk"
+        )
+        ratio = at_risk_count / total
+        if ratio >= HIGH_RISK_RATIO:
+            return "High"
+        elif ratio >= MEDIUM_RISK_RATIO:
+            return "Medium"
+        return "Low"
+
+    # --- remedial quiz configs ---
+
+    @staticmethod
+    def _build_remedial_quiz_configs(
+        student_id: str,
+        at_risk_subjects: List[str],
+        overall_risk: str,
+        grade_level: str,
+    ) -> List[Dict[str, Any]]:
+        """Return list of quiz configuration dicts ready for persistence."""
+        cfg = REMEDIAL_CONFIG.get(overall_risk, REMEDIAL_CONFIG["Low"])
+        quizzes: list[dict] = []
+        for subject in at_risk_subjects:
+            quizzes.append({
+                "studentId": student_id,
+                "subject": subject,
+                "quizConfig": {
+                    "topics": [subject],
+                    "gradeLevel": grade_level,
+                    "numQuestions": cfg["questions"],
+                    "questionTypes": [
+                        "identification",
+                        "enumeration",
+                        "multiple_choice",
+                        "word_problem",
+                    ],
+                    "difficultyDistribution": cfg["dist"],
+                    "bloomLevels": ["remember", "understand", "apply"],
+                    "includeGraphs": False,
+                    "excludeTopics": [],
+                    "purpose": "remedial",
+                    "targetStudent": student_id,
+                },
+                "status": "pending",
+                "autoGenerated": True,
+                "reason": f'Diagnostic identified "{subject}" as At Risk',
+                "priority": "high" if overall_risk == "High" else "medium",
+                "dueInDays": 7,
+            })
+        return quizzes
+
+    # --- AI helpers (Hugging Face) ---
+
+    async def _generate_learning_path(
+        self,
+        at_risk_subjects: List[str],
+        weak_topics: List[Dict[str, Any]],
+        grade_level: str,
+    ) -> Optional[str]:
+        """Generate a personalised learning path via HF Serverless Inference."""
+        try:
+            from main import call_hf_chat
+
+            weakness_lines = ", ".join(at_risk_subjects)
+            topic_lines = "\n".join(
+                f"  - {t['topic']} ({t['accuracy']*100:.0f}% accuracy)"
+                for t in weak_topics[:5]
+            )
+
+            prompt = (
+                f"Generate a personalised math learning path for a {grade_level} student.\n\n"
+                f"Weak subjects: {weakness_lines}\n"
+                f"Weak topics:\n{topic_lines}\n\n"
+                "Create 5-7 specific activities. For each give:\n"
+                "1. Activity title\n"
+                "2. Brief description (1-2 sentences)\n"
+                "3. Estimated duration\n"
+                "4. Type (video, practice, quiz, reading, interactive)\n\n"
+                "Format as a numbered list. Be specific."
+            )
+
+            return call_hf_chat(
+                messages=[
+                    {
+                        "role": "system",
+                        "content": (
+                            "You are an educational curriculum expert specialising in "
+                            "mathematics. Create clear, actionable learning paths."
+                        ),
+                    },
+                    {"role": "user", "content": prompt},
+                ],
+                max_tokens=1500,
+                temperature=0.7,
+            )
+        except Exception as e:
+            logger.warning(f"Learning-path AI call failed: {e}")
+            return None
+
+    async def _generate_teacher_interventions(
+        self,
+        risk_classifications: Dict[str, Dict[str, Any]],
+        weak_topics: List[Dict[str, Any]],
+    ) -> Optional[str]:
+        """Generate teacher intervention recommendations via HF Serverless Inference."""
+        try:
+            from main import call_hf_chat
+
+            at_risk = [
+                subj for subj, data in risk_classifications.items()
+                if data["status"] == "At Risk"
+            ]
+            topic_lines = "\n".join(
+                f"- {t['topic']} ({t['accuracy']*100:.0f}% accuracy)"
+                for t in weak_topics[:5]
+            )
+
+            prompt = (
+                "You are an educational intervention specialist. A student has completed "
+                "their diagnostic assessment with the following results:\n\n"
+                f"At-Risk Subjects: {', '.join(at_risk)}\n\n"
+                f"Weak Topics Identified:\n{topic_lines}\n\n"
+                "Generate a 'Remedial Path Timeline' with:\n"
+                "1. Prioritised list of topics to address (most critical first)\n"
+                "2. Suggested teaching strategies for each topic\n"
+                "3. Recommended one-on-one intervention activities\n"
+                "4. Timeline for reassessment\n"
+                "5. Warning signs that student needs additional support\n\n"
+                "Keep response under 300 words, structured with clear sections."
+            )
+
+            return call_hf_chat(
+                messages=[
+                    {
+                        "role": "system",
+                        "content": (
+                            "You are an expert educational intervention specialist. "
+                            "Provide actionable, structured recommendations for teachers."
+                        ),
+                    },
+                    {"role": "user", "content": prompt},
+                ],
+                max_tokens=1000,
+                temperature=0.5,
+            )
+        except Exception as e:
+            logger.warning(f"Teacher-intervention AI call failed: {e}")
+            return None
+
+
+# Module-level singleton
+automation_engine = MathPulseAutomationEngine()

config/env.sample

@@ -1,97 +1,78 @@
-# Inference provider selection
-# CI trigger marker: keep this file touchable to force backend deploy workflow runs when needed.
-INFERENCE_PROVIDER=local_peft
-INFERENCE_PRO_ENABLED=true
-INFERENCE_PRO_PROVIDER=hf_inference
-INFERENCE_GPU_PROVIDER=hf_inference
-INFERENCE_CPU_PROVIDER=hf_inference
-INFERENCE_ENABLE_PROVIDER_FALLBACK=true
-INFERENCE_PRO_PRIORITY_TASKS=chat,verify_solution
-INFERENCE_PRO_ROUTE_HEADER_NAME=
-INFERENCE_PRO_ROUTE_HEADER_VALUE=true
-
-# task policy sets, comma-separated
-INFERENCE_GPU_REQUIRED_TASKS=chat
-INFERENCE_CPU_ONLY_TASKS=risk_classification,analytics_aggregation,file_parsing,auth,default_cpu
-INFERENCE_INTERACTIVE_TASKS=chat,verify_solution,daily_insight
-ENABLE_LLM_RISK_RECOMMENDATIONS=true
-
-# local_space provider settings
-# Accepts either runtime host (https://<owner>-<space>.hf.space) or
-# Space page URL (https://huggingface.co/spaces/<owner>/<space>).
-# Example: https://huggingface.co/spaces/Deign86/mathpulse-ai
-INFERENCE_LOCAL_SPACE_URL=http://127.0.0.1:7860
-INFERENCE_LOCAL_SPACE_GENERATE_PATH=/gradio_api/call/generate
-INFERENCE_LOCAL_SPACE_TIMEOUT_SEC=180
-
-# local_peft provider settings (base model + LoRA adapter, no merge required)
-LORA_BASE_MODEL_ID=Qwen/Qwen2.5-7B-Instruct
-LORA_ADAPTER_MODEL_ID=Deign86/deped-math-qwen2.5-7b-checkpoint-700-lora
-LORA_LOAD_IN_4BIT=true
-LORA_DEVICE_MAP=auto
-LORA_DTYPE=float16
-LORA_MAX_NEW_TOKENS=576
-LORA_CACHE_DIR=
-LOCAL_PEFT_STREAM_TOKEN_TIMEOUT_SEC=30
-LOCAL_PEFT_WORKER_JOIN_TIMEOUT_SEC=45
-LOCAL_PEFT_GENERATE_MAX_TIME_SEC=0
-LOCAL_PEFT_LOG_MEMORY=false
-
-# hf_inference provider settings
-# Alternative env names accepted by runtime/startup checks: HUGGING_FACE_API_TOKEN, HUGGINGFACE_API_TOKEN
-HF_TOKEN=your_hf_token
-FIREBASE_AUTH_PROJECT_ID=mathpulse-ai-2026
-# Prefer one of the options below for backend Firestore/Admin access in deployment:
-# FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account",...}
-# FIREBASE_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
-INFERENCE_HF_BASE_URL=https://router.huggingface.co/hf-inference/models
-INFERENCE_HF_CHAT_URL=https://router.huggingface.co/v1/chat/completions
-INFERENCE_HF_TIMEOUT_SEC=90
-INFERENCE_INTERACTIVE_TIMEOUT_SEC=55
-INFERENCE_BACKGROUND_TIMEOUT_SEC=120
-
-# model defaults (active)
-INFERENCE_MODEL_ID=Qwen/Qwen2.5-7B-Instruct
-INFERENCE_MAX_NEW_TOKENS=640
-INFERENCE_TEMPERATURE=0.2
-INFERENCE_TOP_P=0.9
-INFERENCE_CHAT_MODEL_ID=Qwen/Qwen2.5-7B-Instruct
-# rollback backups (pre-Qwen switch)
-# Note: backup vars are for manual rollback and are not consumed automatically.
-INFERENCE_MODEL_ID_BACKUP=meta-llama/Llama-3.1-8B-Instruct
-INFERENCE_CHAT_MODEL_ID_BACKUP=meta-llama/Llama-3.1-8B-Instruct
-INFERENCE_CHAT_HARD_MODEL_ID=meta-llama/Meta-Llama-3-70B-Instruct
-INFERENCE_CHAT_HARD_TRIGGER_ENABLED=true
-INFERENCE_CHAT_HARD_PROMPT_CHARS=650
-INFERENCE_CHAT_HARD_HISTORY_CHARS=1500
-INFERENCE_CHAT_HARD_KEYWORDS=step-by-step,show all steps,explain each step,justify each step,derive,derivation,proof,prove,rigorous,multi-step,word problem
-CHAT_MAX_NEW_TOKENS=768
-CHAT_STREAM_NO_TOKEN_TIMEOUT_SEC=30
-CHAT_STREAM_TOTAL_TIMEOUT_SEC=180
-# Optional: force quiz-generation model. Leave empty to use routing.task_model_map.quiz_generation.
-HF_QUIZ_MODEL_ID=
-HF_QUIZ_JSON_REPAIR_MODEL_ID=meta-llama/Llama-3.1-8B-Instruct
-
-# retry behavior
-INFERENCE_MAX_RETRIES=3
-INFERENCE_BACKOFF_SEC=1.5
-INFERENCE_INTERACTIVE_MAX_RETRIES=1
-INFERENCE_BACKGROUND_MAX_RETRIES=3
-INFERENCE_INTERACTIVE_BACKOFF_SEC=1.0
-INFERENCE_BACKGROUND_BACKOFF_SEC=1.75
-INFERENCE_INTERACTIVE_MAX_FALLBACK_DEPTH=1
-# Max simultaneous blocking HF calls allowed from async endpoints.
-HF_BLOCKING_CALL_CONCURRENCY=16
-HF_ASYNC_MAX_CONNECTIONS=64
-HF_ASYNC_MAX_KEEPALIVE_CONNECTIONS=32
-HF_ASYNC_CONNECT_TIMEOUT_SEC=10.0
-HF_ASYNC_WRITE_TIMEOUT_SEC=30.0
-HF_ASYNC_POOL_TIMEOUT_SEC=10.0
-
-# fallback model ids, comma-separated
-INFERENCE_FALLBACK_MODELS=meta-llama/Meta-Llama-3-70B-Instruct,google/gemma-2-2b-it
-
-# async generation controls
-ENABLE_ASYNC_GENERATION=true
-ASYNC_TASK_TTL_SECONDS=3600
-ASYNC_TASK_MAX_ITEMS=400
+# Inference provider selection
+# CI trigger marker: keep this file touchable to force backend deploy workflow runs when needed.
+INFERENCE_PROVIDER=hf_inference
+INFERENCE_PRO_ENABLED=true
+INFERENCE_PRO_PROVIDER=hf_inference
+INFERENCE_GPU_PROVIDER=hf_inference
+INFERENCE_CPU_PROVIDER=hf_inference
+INFERENCE_ENABLE_PROVIDER_FALLBACK=true
+INFERENCE_PRO_PRIORITY_TASKS=chat,verify_solution
+INFERENCE_PRO_ROUTE_HEADER_NAME=
+INFERENCE_PRO_ROUTE_HEADER_VALUE=true
+
+# task policy sets, comma-separated
+INFERENCE_GPU_REQUIRED_TASKS=chat
+INFERENCE_CPU_ONLY_TASKS=risk_classification,analytics_aggregation,file_parsing,auth,default_cpu
+INFERENCE_INTERACTIVE_TASKS=chat,verify_solution,daily_insight
+ENABLE_LLM_RISK_RECOMMENDATIONS=true
+
+# local_space provider settings
+# Accepts either runtime host (https://<owner>-<space>.hf.space) or
+# Space page URL (https://huggingface.co/spaces/<owner>/<space>).
+# Example: https://huggingface.co/spaces/Deign86/mathpulse-ai
+INFERENCE_LOCAL_SPACE_URL=http://127.0.0.1:7860
+INFERENCE_LOCAL_SPACE_GENERATE_PATH=/gradio_api/call/generate
+INFERENCE_LOCAL_SPACE_TIMEOUT_SEC=180
+
+# hf_inference provider settings
+# Alternative env names accepted by runtime/startup checks: HUGGING_FACE_API_TOKEN, HUGGINGFACE_API_TOKEN
+HF_TOKEN=your_hf_token
+FIREBASE_AUTH_PROJECT_ID=mathpulse-ai-2026
+# Prefer one of the options below for backend Firestore/Admin access in deployment:
+# FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account",...}
+# FIREBASE_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
+INFERENCE_HF_BASE_URL=https://router.huggingface.co/hf-inference/models
+INFERENCE_HF_CHAT_URL=https://router.huggingface.co/v1/chat/completions
+INFERENCE_HF_TIMEOUT_SEC=90
+INFERENCE_INTERACTIVE_TIMEOUT_SEC=55
+INFERENCE_BACKGROUND_TIMEOUT_SEC=120
+
+# model defaults
+INFERENCE_MODEL_ID=meta-llama/Llama-3.1-8B-Instruct
+INFERENCE_MAX_NEW_TOKENS=640
+INFERENCE_TEMPERATURE=0.2
+INFERENCE_TOP_P=0.9
+INFERENCE_CHAT_MODEL_ID=meta-llama/Llama-3.1-8B-Instruct
+INFERENCE_CHAT_HARD_MODEL_ID=meta-llama/Meta-Llama-3-70B-Instruct
+INFERENCE_CHAT_HARD_TRIGGER_ENABLED=true
+INFERENCE_CHAT_HARD_PROMPT_CHARS=650
+INFERENCE_CHAT_HARD_HISTORY_CHARS=1500
+INFERENCE_CHAT_HARD_KEYWORDS=step-by-step,show all steps,explain each step,justify each step,derive,derivation,proof,prove,rigorous,multi-step,word problem
+CHAT_MAX_NEW_TOKENS=768
+# Optional: force quiz-generation model. Leave empty to use routing.task_model_map.quiz_generation.
+HF_QUIZ_MODEL_ID=
+HF_QUIZ_JSON_REPAIR_MODEL_ID=meta-llama/Llama-3.1-8B-Instruct
+
+# retry behavior
+INFERENCE_MAX_RETRIES=3
+INFERENCE_BACKOFF_SEC=1.5
+INFERENCE_INTERACTIVE_MAX_RETRIES=1
+INFERENCE_BACKGROUND_MAX_RETRIES=3
+INFERENCE_INTERACTIVE_BACKOFF_SEC=1.0
+INFERENCE_BACKGROUND_BACKOFF_SEC=1.75
+INFERENCE_INTERACTIVE_MAX_FALLBACK_DEPTH=1
+# Max simultaneous blocking HF calls allowed from async endpoints.
+HF_BLOCKING_CALL_CONCURRENCY=16
+HF_ASYNC_MAX_CONNECTIONS=64
+HF_ASYNC_MAX_KEEPALIVE_CONNECTIONS=32
+HF_ASYNC_CONNECT_TIMEOUT_SEC=10.0
+HF_ASYNC_WRITE_TIMEOUT_SEC=30.0
+HF_ASYNC_POOL_TIMEOUT_SEC=10.0
+
+# fallback model ids, comma-separated
+INFERENCE_FALLBACK_MODELS=meta-llama/Meta-Llama-3-70B-Instruct,google/gemma-2-2b-it
+
+# async generation controls
+ENABLE_ASYNC_GENERATION=true
+ASYNC_TASK_TTL_SECONDS=3600
+ASYNC_TASK_MAX_ITEMS=400

config/models.yaml

@@ -1,60 +1,58 @@
-models:
-  primary:
-    id: meta-llama/Llama-3.1-8B-Instruct
-    description: Fast default instruction model for interactive Grade 11-12 math tutoring
-    max_new_tokens: 640
-    temperature: 0.25
-    top_p: 0.9
-
-  backup:
-    - id: meta-llama/Meta-Llama-3-70B-Instruct
-      description: High-quality model used for harder multi-step prompts
-      max_new_tokens: 768
-      temperature: 0.3
-      top_p: 0.9
-    - id: google/gemma-2-2b-it
-      description: Secondary backup with broad instruction coverage
-      max_new_tokens: 384
-      temperature: 0.2
-      top_p: 0.9
-
-  experimental:
-    - id: mistralai/Mistral-7B-Instruct-v0.3
-      notes: Prompt/procedure experimentation
-    - id: meta-llama/Meta-Llama-3-8B-Instruct
-      notes: Baseline comparison against legacy deployment
-
-routing:
-  task_model_map:
-    # Chat default: Qwen2.5-7B for improved math quality and latency.
-    # Hard prompts can escalate to 70B via runtime policy in inference_client.
-    chat: Qwen/Qwen2.5-7B-Instruct
-    verify_solution: NousResearch/Nous-Hermes-2-Mixtral-8x7B-DPO
-    lesson_generation: meta-llama/Llama-3.1-8B-Instruct
-    quiz_generation: meta-llama/Llama-3.1-8B-Instruct
-    learning_path: meta-llama/Llama-3.1-8B-Instruct
-    daily_insight: meta-llama/Llama-3.1-8B-Instruct
-    risk_classification: meta-llama/Llama-3.1-8B-Instruct
-    risk_narrative: meta-llama/Llama-3.1-8B-Instruct
-
-  task_fallback_model_map:
-    chat:
-      - meta-llama/Meta-Llama-3-70B-Instruct      # Hard/fallback quality tier
-      - google/gemma-2-2b-it                      # Fast safety fallback
-    verify_solution:
-      - NousResearch/Nous-Hermes-2-Mixtral-8x7B-DPO  # Primary (reasoning-focused)
-      - meta-llama/Meta-Llama-3-70B-Instruct      # First fallback
-      - meta-llama/Llama-3.1-8B-Instruct          # Second fallback
-
-  task_provider_map:
-    # All tasks default to hf_inference router.
-    # Runtime note: when INFERENCE_PROVIDER=local_peft, chat is routed to local_peft first,
-    # then falls back to hf_inference while non-chat tasks remain on these mappings.
-    chat: hf_inference
-    verify_solution: hf_inference
-    lesson_generation: hf_inference
-    quiz_generation: hf_inference
-    learning_path: hf_inference
-    daily_insight: hf_inference
-    risk_narrative: hf_inference
-    risk_classification: hf_inference
+models:
+  primary:
+    id: meta-llama/Llama-3.1-8B-Instruct
+    description: Fast default instruction model for interactive Grade 11-12 math tutoring
+    max_new_tokens: 640
+    temperature: 0.25
+    top_p: 0.9
+
+  backup:
+    - id: meta-llama/Meta-Llama-3-70B-Instruct
+      description: High-quality model used for harder multi-step prompts
+      max_new_tokens: 768
+      temperature: 0.3
+      top_p: 0.9
+    - id: google/gemma-2-2b-it
+      description: Secondary backup with broad instruction coverage
+      max_new_tokens: 384
+      temperature: 0.2
+      top_p: 0.9
+
+  experimental:
+    - id: mistralai/Mistral-7B-Instruct-v0.3
+      notes: Prompt/procedure experimentation
+    - id: meta-llama/Meta-Llama-3-8B-Instruct
+      notes: Baseline comparison against legacy deployment
+
+routing:
+  task_model_map:
+    # Chat default: Llama-3.1-8B for low latency.
+    # Hard prompts can escalate to 70B via runtime policy in inference_client.
+    chat: meta-llama/Llama-3.1-8B-Instruct
+    verify_solution: NousResearch/Nous-Hermes-2-Mixtral-8x7B-DPO
+    lesson_generation: meta-llama/Llama-3.1-8B-Instruct
+    quiz_generation: meta-llama/Llama-3.1-8B-Instruct
+    learning_path: meta-llama/Llama-3.1-8B-Instruct
+    daily_insight: meta-llama/Llama-3.1-8B-Instruct
+    risk_classification: meta-llama/Llama-3.1-8B-Instruct
+    risk_narrative: meta-llama/Llama-3.1-8B-Instruct
+
+  task_fallback_model_map:
+    chat:
+      - meta-llama/Meta-Llama-3-70B-Instruct      # Hard/fallback quality tier
+      - google/gemma-2-2b-it                      # Fast safety fallback
+    verify_solution:
+      - NousResearch/Nous-Hermes-2-Mixtral-8x7B-DPO  # Primary (reasoning-focused)
+      - meta-llama/Meta-Llama-3-70B-Instruct      # First fallback
+      - meta-llama/Llama-3.1-8B-Instruct          # Second fallback
+
+  task_provider_map:
+    # All tasks use hf_inference router (Qwen2.5-7B-Instruct natively supported)
+    chat: hf_inference
+    verify_solution: hf_inference
+    lesson_generation: hf_inference
+    quiz_generation: hf_inference
+    learning_path: hf_inference
+    daily_insight: hf_inference
+    risk_narrative: hf_inference
+    risk_classification: hf_inference

requirements.txt

@@ -1,22 +1,17 @@
-fastapi>=0.104.0
-uvicorn[standard]>=0.24.0
-huggingface-hub>=0.31.0
-transformers>=4.45.0
-peft>=0.13.0
-accelerate>=0.34.0
-torch>=2.3.0
-bitsandbytes>=0.43.0; platform_system != "Darwin"
-requests>=2.31.0
-pandas==2.2.3
-openpyxl==3.1.5
-pdfplumber==0.11.5
-python-docx==1.1.2
-python-multipart>=0.0.6
-sympy==1.13.3
-matplotlib==3.10.0
-scikit-learn==1.6.1
-joblib==1.4.2
-scipy==1.15.1
-numpy==2.2.1
-firebase-admin>=6.2.0
-PyYAML>=6.0.0
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+huggingface-hub>=0.31.0
+requests>=2.31.0
+pandas==2.2.3
+openpyxl==3.1.5
+pdfplumber==0.11.5
+python-docx==1.1.2
+python-multipart>=0.0.6
+sympy==1.13.3
+matplotlib==3.10.0
+scikit-learn==1.6.1
+joblib==1.4.2
+scipy==1.15.1
+numpy==2.2.1
+firebase-admin>=6.2.0
+PyYAML>=6.0.0

services/__init__.py

@@ -1 +1 @@
-"""Backend service helpers for inference, logging, and integrations."""
+"""Backend service helpers for inference, logging, and integrations."""

services/logging_utils.py

@@ -1,86 +1,86 @@
-import json
-import logging
-from datetime import datetime, timezone
-from typing import Any, Dict, Optional
-
-
-def configure_structured_logging(name: str) -> logging.Logger:
-    logger = logging.getLogger(name)
-    if logger.handlers:
-        return logger
-
-    logger.setLevel(logging.INFO)
-    handler = logging.StreamHandler()
-    formatter = logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s")
-    handler.setFormatter(formatter)
-    logger.addHandler(handler)
-    logger.propagate = False
-    return logger
-
-
-def _safe_json(payload: Dict[str, Any]) -> str:
-    return json.dumps(payload, ensure_ascii=True, default=str)
-
-
-def log_model_call(
-    logger: logging.Logger,
-    *,
-    provider: str,
-    model: str,
-    endpoint: str,
-    latency_ms: float,
-    input_tokens: Optional[int],
-    output_tokens: Optional[int],
-    status: str,
-    error_class: Optional[str] = None,
-    error_message: Optional[str] = None,
-    task_type: Optional[str] = None,
-    request_tag: Optional[str] = None,
-    retry_attempt: Optional[int] = None,
-    fallback_depth: Optional[int] = None,
-    route: Optional[str] = None,
-) -> None:
-    payload = {
-        "ts": datetime.now(timezone.utc).isoformat(),
-        "event": "model_call",
-        "provider": provider,
-        "model": model,
-        "endpoint": endpoint,
-        "latency_ms": round(latency_ms, 2),
-        "input_tokens": input_tokens,
-        "output_tokens": output_tokens,
-        "status": status,
-        "error_class": error_class,
-        "error_message": error_message,
-        "task_type": task_type,
-        "request_tag": request_tag,
-        "retry_attempt": retry_attempt,
-        "fallback_depth": fallback_depth,
-        "route": route,
-    }
-    if status == "ok":
-        logger.info(_safe_json(payload))
-    else:
-        logger.error(_safe_json(payload))
-
-
-def log_job_metric(
-    logger: logging.Logger,
-    *,
-    job_name: str,
-    run_id: str,
-    metric_name: str,
-    metric_value: Any,
-    extras: Optional[Dict[str, Any]] = None,
-) -> None:
-    payload: Dict[str, Any] = {
-        "ts": datetime.now(timezone.utc).isoformat(),
-        "event": "job_metric",
-        "job_name": job_name,
-        "run_id": run_id,
-        "metric_name": metric_name,
-        "metric_value": metric_value,
-    }
-    if extras:
-        payload.update(extras)
-    logger.info(_safe_json(payload))
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+
+def configure_structured_logging(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(logging.INFO)
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.propagate = False
+    return logger
+
+
+def _safe_json(payload: Dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=True, default=str)
+
+
+def log_model_call(
+    logger: logging.Logger,
+    *,
+    provider: str,
+    model: str,
+    endpoint: str,
+    latency_ms: float,
+    input_tokens: Optional[int],
+    output_tokens: Optional[int],
+    status: str,
+    error_class: Optional[str] = None,
+    error_message: Optional[str] = None,
+    task_type: Optional[str] = None,
+    request_tag: Optional[str] = None,
+    retry_attempt: Optional[int] = None,
+    fallback_depth: Optional[int] = None,
+    route: Optional[str] = None,
+) -> None:
+    payload = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "event": "model_call",
+        "provider": provider,
+        "model": model,
+        "endpoint": endpoint,
+        "latency_ms": round(latency_ms, 2),
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "status": status,
+        "error_class": error_class,
+        "error_message": error_message,
+        "task_type": task_type,
+        "request_tag": request_tag,
+        "retry_attempt": retry_attempt,
+        "fallback_depth": fallback_depth,
+        "route": route,
+    }
+    if status == "ok":
+        logger.info(_safe_json(payload))
+    else:
+        logger.error(_safe_json(payload))
+
+
+def log_job_metric(
+    logger: logging.Logger,
+    *,
+    job_name: str,
+    run_id: str,
+    metric_name: str,
+    metric_value: Any,
+    extras: Optional[Dict[str, Any]] = None,
+) -> None:
+    payload: Dict[str, Any] = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "event": "job_metric",
+        "job_name": job_name,
+        "run_id": run_id,
+        "metric_name": metric_name,
+        "metric_value": metric_value,
+    }
+    if extras:
+        payload.update(extras)
+    logger.info(_safe_json(payload))

startup_validation.py

@@ -1,292 +1,243 @@
-"""
-Startup validation for MathPulse AI backend.
-
-This module validates all critical dependencies and configurations BEFORE
-the FastAPI app starts, preventing indefinite restart loops.
-
-If any critical check fails, the process exits with a clear error message
-that's visible in HF Space logs.
-"""
-
-import os
-import sys
-import logging
-import importlib
-from pathlib import Path
-
-logger = logging.getLogger("mathpulse.startup")
-
-
-class StartupError(Exception):
-    """Critical error during startup validation."""
-    pass
-
-
-def validate_imports() -> None:
-    """Verify all critical imports work. Use absolute imports."""
-    logger.info("🔍 Validating Python imports...")
-    try:
-        # Core FastAPI stack
-        import fastapi  # noqa
-        import uvicorn  # noqa
-        import pydantic  # noqa
-        logger.info("   ✓ FastAPI, Uvicorn, Pydantic OK")
-        
-        # Backend services (use ABSOLUTE imports like deployed code)
-        from services.inference_client import InferenceClient, create_default_client  # noqa
-        logger.info("   ✓ InferenceClient imports OK")
-        
-        from automation_engine import automation_engine  # noqa
-        logger.info("   ✓ automation_engine imports OK")
-        
-        from analytics import compute_competency_analysis  # noqa
-        logger.info("   ✓ analytics imports OK")
-        
-        # Firebase
-        try:
-            import firebase_admin  # noqa
-            logger.info("   ✓ firebase_admin imports OK")
-        except ImportError:
-            logger.warning("   ⚠ firebase_admin not available (OK if Firebase not needed)")
-        
-        # ML & inference
-        from huggingface_hub import InferenceClient as HFInferenceClient  # noqa
-        logger.info("   ✓ HuggingFace Hub imports OK")
-
-        inference_provider = os.getenv("INFERENCE_PROVIDER", "hf_inference").strip().lower()
-        if inference_provider == "local_peft":
-            importlib.import_module("transformers")
-            importlib.import_module("peft")
-            importlib.import_module("accelerate")
-            logger.info("   ✓ local_peft deps import OK (transformers, peft, accelerate)")
-
-            load_in_4bit = os.getenv("LORA_LOAD_IN_4BIT", "false").strip().lower() in {"1", "true", "yes", "on"}
-            if load_in_4bit:
-                try:
-                    importlib.import_module("bitsandbytes")
-                    logger.info("   ✓ bitsandbytes import OK")
-                except ImportError as exc:
-                    raise StartupError(
-                        "❌ local_peft dependency error: bitsandbytes is required when LORA_LOAD_IN_4BIT=true"
-                    ) from exc
-        
-        logger.info("✅ All critical imports validated")
-    except ImportError as e:
-        raise StartupError(
-            f"❌ IMPORT ERROR - Cannot start backend:\n"
-            f"   {e}\n"
-            f"\n"
-            f"This usually means:\n"
-            f"  - A Python package is missing (check requirements.txt)\n"
-            f"  - A relative import was used (must be absolute in container)\n"
-            f"  - A circular import exists\n"
-            f"\n"
-            f"Deploy will FAIL and backend will restart indefinitely.\n"
-        ) from e
-    except Exception as e:
-        raise StartupError(f"❌ Unexpected import error: {e}") from e
-
-
-def validate_environment() -> None:
-    """Verify required environment variables are set."""
-    logger.info("🔍 Validating environment variables...")
-    
-    # CRITICAL: HF_TOKEN for inference
-    hf_token = os.environ.get("HF_TOKEN")
-    api_key = os.environ.get("HUGGING_FACE_API_TOKEN")
-    legacy_api_key = os.environ.get("HUGGINGFACE_API_TOKEN")
-    if not hf_token and not api_key and not legacy_api_key:
-        logger.warning(
-            "⚠  WARNING: HF_TOKEN is not set as an environment variable.\n"
-            "   On HF Spaces, this should be set as a SPACE SECRET.\n"
-            "   AI inference will fail without this token.\n"
-            "   Use: python set-hf-secrets.py to set the secret."
-        )
-    else:
-        logger.info("   ✓ HF_TOKEN/HUGGING_FACE_API_TOKEN/HUGGINGFACE_API_TOKEN is set")
-    
-    # Check inference provider config
-    inference_provider = os.getenv("INFERENCE_PROVIDER", "hf_inference")
-    logger.info(f"   ✓ INFERENCE_PROVIDER: {inference_provider}")
-    
-    # Check model IDs
-    chat_model = os.getenv("INFERENCE_CHAT_MODEL_ID") or os.getenv("INFERENCE_MODEL_ID") or "Qwen/Qwen2.5-7B-Instruct"
-    logger.info(f"   ✓ Chat model configured: {chat_model}")
-
-    if inference_provider.strip().lower() == "local_peft":
-        lora_base_model_id = os.getenv("LORA_BASE_MODEL_ID", "").strip()
-        lora_adapter_model_id = os.getenv("LORA_ADAPTER_MODEL_ID", "").strip()
-        if not lora_base_model_id:
-            raise StartupError("❌ LORA_BASE_MODEL_ID is required when INFERENCE_PROVIDER=local_peft")
-        if not lora_adapter_model_id:
-            raise StartupError("❌ LORA_ADAPTER_MODEL_ID is required when INFERENCE_PROVIDER=local_peft")
-
-        logger.info(f"   ✓ local_peft base model: {lora_base_model_id}")
-        logger.info(f"   ✓ local_peft adapter model: {lora_adapter_model_id}")
-        logger.info(f"   ✓ local_peft load_in_4bit: {os.getenv('LORA_LOAD_IN_4BIT', 'false')}")
-        logger.info(f"   ✓ local_peft device_map: {os.getenv('LORA_DEVICE_MAP', 'auto')}")
-        logger.info(f"   ✓ local_peft dtype: {os.getenv('LORA_DTYPE', 'float16')}")
-    
-    logger.info("✅ Environment variables OK")
-
-
-def validate_config_files() -> None:
-    """Verify config files exist and are readable."""
-    logger.info("🔍 Validating configuration files...")
-    
-    config_paths = [
-        "config/models.yaml",
-        "backend/config/models.yaml",
-    ]
-    
-    for config_path in config_paths:
-        full_path = Path(config_path)
-        if not full_path.exists():
-            logger.warning(f"   ⚠ Config file not found: {config_path}")
-        else:
-            try:
-                with open(full_path, 'r') as f:
-                    content = f.read()
-                    if not content.strip():
-                        raise StartupError(
-                            f"❌ CONFIG ERROR: {config_path} is empty!\n"
-                            f"   This will cause model routing to fail.\n"
-                        )
-                    logger.info(f"   ✓ {config_path} is readable and non-empty")
-            except Exception as e:
-                raise StartupError(
-                    f"❌ CONFIG ERROR: Cannot read {config_path}:\n"
-                    f"   {e}\n"
-                ) from e
-    
-    logger.info("✅ Configuration files OK")
-
-
-def validate_file_structure() -> None:
-    """Verify critical backend files exist."""
-    logger.info("🔍 Validating file structure...")
-    required_path_sets = [
-        ["main.py", "backend/main.py"],
-        ["services/inference_client.py", "backend/services/inference_client.py"],
-        ["analytics.py", "backend/analytics.py"],
-        ["automation_engine.py", "backend/automation_engine.py"],
-    ]
-
-    for candidates in required_path_sets:
-        found = None
-        for candidate in candidates:
-            if Path(candidate).exists():
-                found = candidate
-                break
-
-        if not found:
-            joined = " or ".join(candidates)
-            raise StartupError(
-                f"❌ FILE MISSING: {joined}\n"
-                f"   Backend structure is broken for this deployment layout.\n"
-            )
-
-        logger.info(f"   ✓ Found {found}")
-
-    docker_candidates = ["Dockerfile", "backend/Dockerfile"]
-    found_dockerfile = next((candidate for candidate in docker_candidates if Path(candidate).exists()), None)
-    if found_dockerfile:
-        logger.info(f"   ✓ Found {found_dockerfile}")
-    else:
-        logger.info("   ℹ Dockerfile not present in runtime image (expected in deployed containers)")
-    
-    logger.info("✅ File structure OK")
-
-
-def validate_inference_client_config() -> None:
-    """Validate InferenceClient can load its config."""
-    logger.info("🔍 Validating InferenceClient configuration...")
-    
-    try:
-        # Try to create the client (this will load config from YAML)
-        from services.inference_client import create_default_client
-        client = create_default_client()
-        
-        # Verify critical attributes
-        if not hasattr(client, 'task_model_map'):
-            raise StartupError("❌ InferenceClient missing task_model_map attribute")
-        
-        if not hasattr(client, 'task_provider_map'):
-            raise StartupError("❌ InferenceClient missing task_provider_map attribute")
-        
-        # Check that required tasks are mapped
-        required_tasks = ['chat', 'verify_solution', 'lesson_generation', 'quiz_generation']
-        for task in required_tasks:
-            if task not in client.task_model_map:
-                raise StartupError(
-                    f"❌ Task '{task}' not in task_model_map.\n"
-                    f"   Check config/models.yaml\n"
-                )
-            model = client.task_model_map[task]
-            provider = client.task_provider_map.get(task, 'unknown')
-            logger.info(f"   ✓ {task}: {model} ({provider})")
-
-        if getattr(client, "provider", "") == "local_peft":
-            if not getattr(client, "lora_base_model_id", ""):
-                raise StartupError("❌ local_peft missing LORA_BASE_MODEL_ID")
-            if not getattr(client, "lora_adapter_model_id", ""):
-                raise StartupError("❌ local_peft missing LORA_ADAPTER_MODEL_ID")
-            logger.info(
-                "   ✓ local_peft runtime config: base=%s adapter=%s",
-                client.lora_base_model_id,
-                client.lora_adapter_model_id,
-            )
-        
-        logger.info("✅ InferenceClient configuration OK")
-        
-    except StartupError:
-        raise
-    except Exception as e:
-        raise StartupError(
-            f"❌ InferenceClient validation failed:\n"
-            f"   {e}\n"
-            f"   Check config/models.yaml and backend/config/models.yaml\n"
-        ) from e
-
-
-def run_all_validations() -> None:
-    """Run comprehensive startup validation.
-    
-    If any check fails, exits with clear error message visible in logs.
-    """
-    logger.info("=" * 70)
-    logger.info("🚀 STARTUP VALIDATION - Checking all critical dependencies")
-    logger.info("=" * 70)
-    
-    strict_mode = os.getenv("STARTUP_VALIDATION_STRICT", "false").strip().lower() in {"1", "true", "yes", "on"}
-
-    try:
-        validate_file_structure()
-        validate_imports()
-        validate_environment()
-        validate_config_files()
-        validate_inference_client_config()
-        
-        logger.info("=" * 70)
-        logger.info("✅ ALL STARTUP VALIDATIONS PASSED")
-        logger.info("=" * 70)
-        
-    except StartupError as e:
-        logger.error("=" * 70)
-        logger.error(str(e))
-        logger.error("=" * 70)
-        if strict_mode:
-            logger.error("\n🛑 DEPLOYMENT WILL FAIL - Fix errors above and redeploy")
-            sys.exit(1)
-        logger.warning(
-            "\n⚠️  Continuing startup because STARTUP_VALIDATION_STRICT is disabled. "
-            "Set STARTUP_VALIDATION_STRICT=true to fail fast."
-        )
-    except Exception as e:
-        logger.exception(f"Unexpected validation error: {e}")
-        if strict_mode:
-            sys.exit(1)
-        logger.warning(
-            "⚠️  Continuing startup after unexpected validation error because "
-            "STARTUP_VALIDATION_STRICT is disabled."
-        )
+"""
+Startup validation for MathPulse AI backend.
+
+This module validates all critical dependencies and configurations BEFORE
+the FastAPI app starts, preventing indefinite restart loops.
+
+If any critical check fails, the process exits with a clear error message
+that's visible in HF Space logs.
+"""
+
+import os
+import sys
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("mathpulse.startup")
+
+
+class StartupError(Exception):
+    """Critical error during startup validation."""
+    pass
+
+
+def validate_imports() -> None:
+    """Verify all critical imports work. Use absolute imports."""
+    logger.info("🔍 Validating Python imports...")
+    try:
+        # Core FastAPI stack
+        import fastapi  # noqa
+        import uvicorn  # noqa
+        import pydantic  # noqa
+        logger.info("   ✓ FastAPI, Uvicorn, Pydantic OK")
+        
+        # Backend services (use ABSOLUTE imports like deployed code)
+        from services.inference_client import InferenceClient, create_default_client  # noqa
+        logger.info("   ✓ InferenceClient imports OK")
+        
+        from automation_engine import automation_engine  # noqa
+        logger.info("   ✓ automation_engine imports OK")
+        
+        from analytics import compute_competency_analysis  # noqa
+        logger.info("   ✓ analytics imports OK")
+        
+        # Firebase
+        try:
+            import firebase_admin  # noqa
+            logger.info("   ✓ firebase_admin imports OK")
+        except ImportError:
+            logger.warning("   ⚠ firebase_admin not available (OK if Firebase not needed)")
+        
+        # ML & inference
+        from huggingface_hub import InferenceClient as HFInferenceClient  # noqa
+        logger.info("   ✓ HuggingFace Hub imports OK")
+        
+        logger.info("✅ All critical imports validated")
+    except ImportError as e:
+        raise StartupError(
+            f"❌ IMPORT ERROR - Cannot start backend:\n"
+            f"   {e}\n"
+            f"\n"
+            f"This usually means:\n"
+            f"  - A Python package is missing (check requirements.txt)\n"
+            f"  - A relative import was used (must be absolute in container)\n"
+            f"  - A circular import exists\n"
+            f"\n"
+            f"Deploy will FAIL and backend will restart indefinitely.\n"
+        ) from e
+    except Exception as e:
+        raise StartupError(f"❌ Unexpected import error: {e}") from e
+
+
+def validate_environment() -> None:
+    """Verify required environment variables are set."""
+    logger.info("🔍 Validating environment variables...")
+    
+    # CRITICAL: HF_TOKEN for inference
+    hf_token = os.environ.get("HF_TOKEN")
+    api_key = os.environ.get("HUGGING_FACE_API_TOKEN")
+    legacy_api_key = os.environ.get("HUGGINGFACE_API_TOKEN")
+    if not hf_token and not api_key and not legacy_api_key:
+        logger.warning(
+            "⚠  WARNING: HF_TOKEN is not set as an environment variable.\n"
+            "   On HF Spaces, this should be set as a SPACE SECRET.\n"
+            "   AI inference will fail without this token.\n"
+            "   Use: python set-hf-secrets.py to set the secret."
+        )
+    else:
+        logger.info("   ✓ HF_TOKEN/HUGGING_FACE_API_TOKEN/HUGGINGFACE_API_TOKEN is set")
+    
+    # Check inference provider config
+    inference_provider = os.getenv("INFERENCE_PROVIDER", "hf_inference")
+    logger.info(f"   ✓ INFERENCE_PROVIDER: {inference_provider}")
+    
+    # Check model IDs
+    chat_model = os.getenv("INFERENCE_CHAT_MODEL_ID") or os.getenv("INFERENCE_MODEL_ID") or "Qwen/Qwen2.5-7B-Instruct"
+    logger.info(f"   ✓ Chat model configured: {chat_model}")
+    
+    logger.info("✅ Environment variables OK")
+
+
+def validate_config_files() -> None:
+    """Verify config files exist and are readable."""
+    logger.info("🔍 Validating configuration files...")
+    
+    config_paths = [
+        "config/models.yaml",
+        "backend/config/models.yaml",
+    ]
+    
+    for config_path in config_paths:
+        full_path = Path(config_path)
+        if not full_path.exists():
+            logger.warning(f"   ⚠ Config file not found: {config_path}")
+        else:
+            try:
+                with open(full_path, 'r') as f:
+                    content = f.read()
+                    if not content.strip():
+                        raise StartupError(
+                            f"❌ CONFIG ERROR: {config_path} is empty!\n"
+                            f"   This will cause model routing to fail.\n"
+                        )
+                    logger.info(f"   ✓ {config_path} is readable and non-empty")
+            except Exception as e:
+                raise StartupError(
+                    f"❌ CONFIG ERROR: Cannot read {config_path}:\n"
+                    f"   {e}\n"
+                ) from e
+    
+    logger.info("✅ Configuration files OK")
+
+
+def validate_file_structure() -> None:
+    """Verify critical backend files exist."""
+    logger.info("🔍 Validating file structure...")
+    required_path_sets = [
+        ["main.py", "backend/main.py"],
+        ["services/inference_client.py", "backend/services/inference_client.py"],
+        ["analytics.py", "backend/analytics.py"],
+        ["automation_engine.py", "backend/automation_engine.py"],
+        ["Dockerfile", "backend/Dockerfile"],
+    ]
+
+    for candidates in required_path_sets:
+        found = None
+        for candidate in candidates:
+            if Path(candidate).exists():
+                found = candidate
+                break
+
+        if not found:
+            joined = " or ".join(candidates)
+            raise StartupError(
+                f"❌ FILE MISSING: {joined}\n"
+                f"   Backend structure is broken for this deployment layout.\n"
+            )
+
+        logger.info(f"   ✓ Found {found}")
+    
+    logger.info("✅ File structure OK")
+
+
+def validate_inference_client_config() -> None:
+    """Validate InferenceClient can load its config."""
+    logger.info("🔍 Validating InferenceClient configuration...")
+    
+    try:
+        # Try to create the client (this will load config from YAML)
+        from services.inference_client import create_default_client
+        client = create_default_client()
+        
+        # Verify critical attributes
+        if not hasattr(client, 'task_model_map'):
+            raise StartupError("❌ InferenceClient missing task_model_map attribute")
+        
+        if not hasattr(client, 'task_provider_map'):
+            raise StartupError("❌ InferenceClient missing task_provider_map attribute")
+        
+        # Check that required tasks are mapped
+        required_tasks = ['chat', 'verify_solution', 'lesson_generation', 'quiz_generation']
+        for task in required_tasks:
+            if task not in client.task_model_map:
+                raise StartupError(
+                    f"❌ Task '{task}' not in task_model_map.\n"
+                    f"   Check config/models.yaml\n"
+                )
+            model = client.task_model_map[task]
+            provider = client.task_provider_map.get(task, 'unknown')
+            logger.info(f"   ✓ {task}: {model} ({provider})")
+        
+        logger.info("✅ InferenceClient configuration OK")
+        
+    except StartupError:
+        raise
+    except Exception as e:
+        raise StartupError(
+            f"❌ InferenceClient validation failed:\n"
+            f"   {e}\n"
+            f"   Check config/models.yaml and backend/config/models.yaml\n"
+        ) from e
+
+
+def run_all_validations() -> None:
+    """Run comprehensive startup validation.
+    
+    If any check fails, exits with clear error message visible in logs.
+    """
+    logger.info("=" * 70)
+    logger.info("🚀 STARTUP VALIDATION - Checking all critical dependencies")
+    logger.info("=" * 70)
+    
+    strict_mode = os.getenv("STARTUP_VALIDATION_STRICT", "false").strip().lower() in {"1", "true", "yes", "on"}
+
+    try:
+        validate_file_structure()
+        validate_imports()
+        validate_environment()
+        validate_config_files()
+        validate_inference_client_config()
+        
+        logger.info("=" * 70)
+        logger.info("✅ ALL STARTUP VALIDATIONS PASSED")
+        logger.info("=" * 70)
+        
+    except StartupError as e:
+        logger.error("=" * 70)
+        logger.error(str(e))
+        logger.error("=" * 70)
+        if strict_mode:
+            logger.error("\n🛑 DEPLOYMENT WILL FAIL - Fix errors above and redeploy")
+            sys.exit(1)
+        logger.warning(
+            "\n⚠️  Continuing startup because STARTUP_VALIDATION_STRICT is disabled. "
+            "Set STARTUP_VALIDATION_STRICT=true to fail fast."
+        )
+    except Exception as e:
+        logger.exception(f"Unexpected validation error: {e}")
+        if strict_mode:
+            sys.exit(1)
+        logger.warning(
+            "⚠️  Continuing startup after unexpected validation error because "
+            "STARTUP_VALIDATION_STRICT is disabled."
+        )

tests/test_api.py

@@ -217,7 +217,7 @@ class TestChatEndpoint:
     def test_chat_with_history(self, mock_chat):
         mock_chat.return_value = "Yes, that's right."
         response = client.post("/api/chat", json={
-            "message": "Is 2 + 2 = 4 correct?",
+            "message": "Is that correct?",
             "history": [
                 {"role": "user", "content": "What is 2+2?"},
                 {"role": "assistant", "content": "4"},
@@ -237,21 +237,11 @@ class TestChatEndpoint:
     def test_chat_hf_failure_returns_502(self, mock_chat):
         mock_chat.side_effect = Exception("HF API down")
         response = client.post("/api/chat", json={
-            "message": "Solve 10 - 3.",
+            "message": "Hello",
             "history": [],
         })
         assert response.status_code == 502
 
-    @patch("main.call_hf_chat")
-    def test_chat_rejects_non_math_query(self, mock_chat):
-        response = client.post("/api/chat", json={
-            "message": "Who is Elon Musk?",
-            "history": [],
-        })
-        assert response.status_code == 200
-        assert response.json()["response"] == main_module.MATH_ONLY_REFUSAL_MESSAGE
-        mock_chat.assert_not_called()
-
     @patch("main.call_hf_chat")
     def test_chat_quadratic_prompt_smoke(self, mock_chat):
         mock_chat.return_value = (
@@ -272,7 +262,7 @@ class TestChatEndpoint:
         mock_stream.return_value = iter(["Hello", " world"])
 
         with client.stream("POST", "/api/chat/stream", json={
-            "message": "What is 3 + 4?",
+            "message": "Say hello",
             "history": [],
         }) as response:
             assert response.status_code == 200
@@ -287,7 +277,7 @@ class TestChatEndpoint:
         mock_stream.side_effect = Exception("HF stream down")
 
         with client.stream("POST", "/api/chat/stream", json={
-            "message": "Solve 2 + 2.",
+            "message": "Say hello",
             "history": [],
         }) as response:
             assert response.status_code == 200
@@ -296,22 +286,6 @@ class TestChatEndpoint:
         assert "event: error" in content
         assert "event: end" in content
 
-    @patch("main.call_hf_chat_stream")
-    def test_chat_stream_rejects_non_math_query(self, mock_stream):
-        with client.stream("POST", "/api/chat/stream", json={
-            "message": "Write me a poem.",
-            "history": [],
-        }) as response:
-            assert response.status_code == 200
-            content = "".join(response.iter_text())
-
-        refusal_payload = json.dumps({"chunk": main_module.MATH_ONLY_REFUSAL_MESSAGE}, ensure_ascii=False)
-        assert "event: chunk" in content
-        assert f"data: {refusal_payload}" in content
-        assert "event: end" in content
-        assert "event: error" not in content
-        mock_stream.assert_not_called()
-
 
 class TestHFChatTransport:
     @patch("main.http_requests.post")
@@ -343,74 +317,6 @@ class TestHFChatTransport:
         assert payload["stream"] is False
         assert isinstance(payload["messages"], list)
 
-    def test_call_hf_chat_stream_supports_local_peft_provider(self):
-        class FakeLocalClient:
-            interactive_timeout_sec = 60
-
-            def _resolve_primary_model(self, req):
-                return "Qwen/Qwen2.5-7B-Instruct", False
-
-            def _model_chain_for_task(self, task_type, selected_model):
-                return [selected_model]
-
-            def _provider_chain_for_task(self, task_type):
-                return ["local_peft"]
-
-            def _resolve_route_label(self, provider, task_type):
-                return "standard"
-
-            def _stream_local_peft(self, req, *, provider, route, fallback_depth):
-                assert provider == "local_peft"
-                assert req.task_type == "chat"
-                yield "Adapter"
-                yield " stream"
-
-        with patch("main.get_inference_client", return_value=FakeLocalClient()):
-            chunks = list(main_module.call_hf_chat_stream(
-                [{"role": "user", "content": "Solve 2x + 4 = 10"}],
-                max_tokens=64,
-                task_type="chat",
-            ))
-
-        assert "".join(chunks) == "Adapter stream"
-
-    def test_call_hf_chat_stream_async_supports_local_peft_provider(self, monkeypatch):
-        monkeypatch.delenv("PYTEST_CURRENT_TEST", raising=False)
-
-        class FakeLocalClient:
-            def _resolve_primary_model(self, req):
-                return "Qwen/Qwen2.5-7B-Instruct", False
-
-            def _model_chain_for_task(self, task_type, selected_model):
-                return [selected_model]
-
-            def _provider_chain_for_task(self, task_type):
-                return ["local_peft"]
-
-            def _resolve_route_label(self, provider, task_type):
-                return "standard"
-
-            def _stream_local_peft(self, req, *, provider, route, fallback_depth):
-                assert provider == "local_peft"
-                assert req.task_type == "chat"
-                yield "Adapter"
-                yield " async"
-
-        async def _collect() -> str:
-            parts: List[str] = []
-            async for chunk in main_module.call_hf_chat_stream_async(
-                [{"role": "user", "content": "Solve 2x + 4 = 10"}],
-                max_tokens=64,
-                task_type="chat",
-            ):
-                parts.append(chunk)
-            return "".join(parts)
-
-        with patch("main.get_inference_client", return_value=FakeLocalClient()):
-            result = asyncio.run(_collect())
-
-        assert result == "Adapter async"
-
 
 # ─── Risk Prediction ──────────────────────────────────────────
 

tests/test_peft_smoke.py

@@ -1,66 +0,0 @@
-"""
-backend/tests/test_peft_smoke.py
-Lightweight smoke tests for local_peft provider routing.
-
-Run with:
-  python -m pytest backend/tests/test_peft_smoke.py -q
-"""
-
-import os
-import sys
-
-# Add backend directory to path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
-
-from services.inference_client import InferenceClient, InferenceRequest
-
-
-def _set_local_peft_env(monkeypatch):
-    monkeypatch.setenv("INFERENCE_PROVIDER", "local_peft")
-    monkeypatch.setenv("INFERENCE_ENABLE_PROVIDER_FALLBACK", "true")
-    monkeypatch.setenv("INFERENCE_GPU_PROVIDER", "hf_inference")
-    monkeypatch.setenv("INFERENCE_CPU_PROVIDER", "hf_inference")
-    monkeypatch.setenv("LORA_BASE_MODEL_ID", "Qwen/Qwen2.5-7B-Instruct")
-    monkeypatch.setenv(
-        "LORA_ADAPTER_MODEL_ID",
-        "Deign86/deped-math-qwen2.5-7b-checkpoint-700-lora",
-    )
-    monkeypatch.setenv("LORA_LOAD_IN_4BIT", "true")
-    monkeypatch.setenv("LORA_DEVICE_MAP", "auto")
-    monkeypatch.setenv("LORA_DTYPE", "float16")
-    monkeypatch.setenv("LORA_MAX_NEW_TOKENS", "576")
-
-
-def test_local_peft_chat_provider_chain_prioritizes_adapter(monkeypatch):
-    _set_local_peft_env(monkeypatch)
-    client = InferenceClient()
-
-    chat_chain = client._provider_chain_for_task("chat")
-    assert chat_chain[0] == "local_peft"
-    assert "hf_inference" in chat_chain
-
-    # Non-chat tasks keep existing forced task provider mapping from models.yaml.
-    verify_chain = client._provider_chain_for_task("verify_solution")
-    assert verify_chain == ["hf_inference"]
-
-
-def test_local_peft_generate_path_returns_text(monkeypatch):
-    _set_local_peft_env(monkeypatch)
-
-    def fake_call_local_peft(self, req, *, provider, route, fallback_depth):
-        assert provider == "local_peft"
-        assert req.task_type == "chat"
-        return "Adapter-generated text"
-
-    monkeypatch.setattr(InferenceClient, "_call_local_peft", fake_call_local_peft)
-    client = InferenceClient()
-
-    req = InferenceRequest(
-        messages=[{"role": "user", "content": "Solve 2x + 4 = 10"}],
-        task_type="chat",
-        max_new_tokens=128,
-    )
-    text = client.generate_from_messages(req)
-
-    assert isinstance(text, str)
-    assert text == "Adapter-generated text"