🚀 Auto-deploy backend from GitHub (5544829)

main.py

@@ -290,6 +290,7 @@ def call_hf_chat(
     top_p: float = 0.9,
     repetition_penalty: float = 1.15,
     model: Optional[str] = None,
+    timeout: int = 90,
 ) -> str:
     """
     Call the HF Serverless Inference API (OpenAI-compatible chat endpoint)
@@ -314,7 +315,7 @@ def call_hf_chat(
     }
 
     for attempt in range(3):
-        resp = http_requests.post(url, headers=headers, json=payload, timeout=60)
+        resp = http_requests.post(url, headers=headers, json=payload, timeout=timeout)
         if resp.status_code == 503 and attempt < 2:
             logger.warning(f"HF chat 503 (model loading), retry {attempt + 1}/3")
             time.sleep(3)
@@ -1342,48 +1343,70 @@ class CalculatorResponse(BaseModel):
     latex: Optional[str] = None
 
 
-# ─── Quiz Topics Database ─────────────────────────────────────
+# ─── Quiz Topics Database (SHS Grade 11-12 Only) ─────────────
 
 MATH_TOPICS_BY_GRADE: Dict[str, Dict[str, List[str]]] = {
-    "Grade 7": {
-        "Number Sense": ["Integers", "Fractions & Decimals", "Ratios & Proportions", "Percentages"],
-        "Algebra": ["Variables & Expressions", "One-Step Equations", "Inequalities", "Patterns"],
-        "Geometry": ["Angles", "Triangles", "Area & Perimeter", "Volume"],
-        "Statistics": ["Mean, Median, Mode", "Bar & Line Graphs", "Probability Basics"],
-    },
-    "Grade 8": {
-        "Algebra": ["Linear Equations", "Systems of Equations (Introduction)", "Slope & Rate of Change", "Functions"],
-        "Geometry": ["Pythagorean Theorem", "Transformations", "Congruence & Similarity", "Surface Area & Volume"],
-        "Number Sense": ["Exponents & Powers", "Scientific Notation", "Square & Cube Roots", "Rational & Irrational Numbers"],
-        "Statistics": ["Scatter Plots", "Two-Way Tables", "Probability of Compound Events"],
-    },
-    "Grade 9": {
-        "Algebra": ["Linear Functions", "Quadratic Equations", "Polynomials", "Factoring"],
-        "Geometry": ["Coordinate Geometry", "Circles", "Trigonometric Ratios", "Proofs"],
-        "Statistics": ["Data Analysis", "Normal Distribution Basics", "Sampling Methods"],
-        "Number Sense": ["Radicals & Exponents", "Rational Expressions"],
-    },
-    "Grade 10": {
-        "Algebra": ["Quadratic Functions", "Systems of Equations", "Exponential Functions", "Radical Equations"],
-        "Geometry": ["Circle Theorems", "Solid Geometry", "Coordinate Proofs", "Trigonometry"],
-        "Statistics & Probability": ["Permutations & Combinations", "Conditional Probability", "Binomial Probability"],
-        "Pre-Calculus": ["Sequences & Series", "Polynomial Functions"],
-    },
     "Grade 11": {
-        "Pre-Calculus": ["Functions & Graphs", "Polynomial Division", "Rational Functions", "Logarithmic Functions", "Trigonometric Functions"],
-        "Statistics": ["Regression Analysis", "Confidence Intervals", "Hypothesis Testing Basics"],
-        "Algebra": ["Complex Numbers", "Matrices (Introduction)", "Conic Sections"],
+        "General Mathematics - Functions and Their Graphs": [
+            "Functions and Relations", "Evaluating Functions", "Operations on Functions",
+            "Composite Functions", "Inverse Functions", "Rational Functions",
+            "Exponential Functions", "Logarithmic Functions",
+        ],
+        "General Mathematics - Business Mathematics": [
+            "Simple Interest", "Compound Interest", "Annuities",
+            "Loans and Amortization", "Stocks and Bonds",
+        ],
+        "General Mathematics - Logic": [
+            "Propositions and Connectives", "Truth Tables",
+            "Logical Equivalence", "Valid Arguments and Fallacies",
+        ],
+        "Statistics and Probability - Random Variables": [
+            "Random Variables", "Discrete Probability Distributions",
+            "Mean and Variance of Discrete RV",
+        ],
+        "Statistics and Probability - Normal Distribution": [
+            "Normal Distribution", "Standard Normal Distribution and Z-scores",
+            "Areas Under the Normal Curve",
+        ],
+        "Statistics and Probability - Sampling and Estimation": [
+            "Sampling Distributions", "Central Limit Theorem",
+            "Point Estimation", "Confidence Intervals",
+        ],
+        "Statistics and Probability - Hypothesis Testing": [
+            "Hypothesis Testing Concepts", "T-test", "Z-test",
+            "Correlation and Regression",
+        ],
     },
     "Grade 12": {
-        "Basic Calculus": ["Limits", "Derivatives", "Integration", "Applications of Derivatives", "Area Under a Curve"],
-        "Statistics": ["Normal Distribution", "Z-Scores", "Chi-Square Tests"],
-        "Advanced Algebra": ["Series & Convergence", "Parametric Equations", "Polar Coordinates"],
-    },
-    "College": {
-        "Calculus": ["Multivariable Calculus", "Differential Equations", "Vector Calculus", "Infinite Series"],
-        "Linear Algebra": ["Matrices & Determinants", "Eigenvalues & Eigenvectors", "Vector Spaces", "Linear Transformations"],
-        "Discrete Mathematics": ["Set Theory", "Graph Theory", "Combinatorics", "Number Theory"],
-        "Statistics": ["Probability Distributions", "Bayesian Statistics", "Statistical Inference", "ANOVA"],
+        "Pre-Calculus - Analytic Geometry": [
+            "Conic Sections - Parabola", "Conic Sections - Ellipse",
+            "Conic Sections - Hyperbola", "Conic Sections - Circle",
+            "Systems of Nonlinear Equations",
+        ],
+        "Pre-Calculus - Series and Induction": [
+            "Sequences and Series", "Arithmetic Sequences", "Geometric Sequences",
+            "Mathematical Induction", "Binomial Theorem",
+        ],
+        "Pre-Calculus - Trigonometry": [
+            "Angles and Unit Circle", "Trigonometric Functions",
+            "Trigonometric Identities", "Sum and Difference Formulas",
+            "Inverse Trigonometric Functions", "Polar Coordinates",
+        ],
+        "Basic Calculus - Limits": [
+            "Limits of Functions", "Limit Theorems", "One-Sided Limits",
+            "Infinite Limits and Limits at Infinity", "Continuity of Functions",
+        ],
+        "Basic Calculus - Derivatives": [
+            "Definition of the Derivative", "Differentiation Rules", "Chain Rule",
+            "Implicit Differentiation", "Higher-Order Derivatives", "Related Rates",
+            "Extrema and the First Derivative Test",
+            "Concavity and the Second Derivative Test", "Optimization Problems",
+        ],
+        "Basic Calculus - Integration": [
+            "Antiderivatives and Indefinite Integrals",
+            "Definite Integrals and the FTC",
+            "Integration by Substitution", "Area Under a Curve",
+        ],
     },
 }
 
@@ -1630,15 +1653,64 @@ Remember:
 
         logger.info(f"Generating quiz: {request.numQuestions} questions, topics={effective_topics}")
 
-        raw_content = call_hf_chat(messages, max_tokens=4096, temperature=0.3, top_p=0.9)
-        logger.info(f"Raw quiz response length: {len(raw_content)} chars")
+        # Scale max_tokens based on requested questions — each question needs ~400-600 tokens
+        max_tokens = min(16384, max(4096, request.numQuestions * 600))
+        # Use longer HTTP timeout for quiz generation (scales with question count)
+        http_timeout = max(90, request.numQuestions * 12)
 
-        parsed_questions = _parse_quiz_json(raw_content)
-        if not parsed_questions:
-            logger.error(f"Failed to parse quiz JSON. Raw content:\n{raw_content[:500]}")
-            raise HTTPException(
-                status_code=500,
-                detail="Failed to parse quiz questions from AI response. Please try again.",
+        parsed_questions: List[Dict[str, Any]] = []
+        max_attempts = 2  # Retry once if LLM generates too few questions
+
+        for attempt in range(max_attempts):
+            raw_content = call_hf_chat(
+                messages, max_tokens=max_tokens, temperature=0.3, top_p=0.9,
+                timeout=http_timeout,
+            )
+            logger.info(f"Raw quiz response length: {len(raw_content)} chars (attempt {attempt + 1})")
+
+            parsed_questions = _parse_quiz_json(raw_content)
+
+            if not parsed_questions:
+                logger.error(f"Failed to parse quiz JSON (attempt {attempt + 1}). Raw content:\n{raw_content[:500]}")
+                if attempt < max_attempts - 1:
+                    logger.info("Retrying quiz generation...")
+                    continue
+                raise HTTPException(
+                    status_code=500,
+                    detail="Failed to parse quiz questions from AI response. Please try again.",
+                )
+
+            # If we got at least 70% of requested questions, accept the result
+            if len(parsed_questions) >= request.numQuestions * 0.7:
+                break
+
+            # Otherwise retry with a stronger nudge
+            if attempt < max_attempts - 1:
+                logger.warning(
+                    f"LLM generated only {len(parsed_questions)}/{request.numQuestions} questions "
+                    f"(attempt {attempt + 1}). Retrying with reinforced prompt..."
+                )
+                # Add an assistant + user turn to push the LLM harder
+                messages = [
+                    {"role": "system", "content": QUIZ_GENERATION_SYSTEM_PROMPT},
+                    {"role": "user", "content": prompt},
+                    {"role": "assistant", "content": raw_content},
+                    {
+                        "role": "user",
+                        "content": (
+                            f"You only generated {len(parsed_questions)} questions but I need "
+                            f"exactly {request.numQuestions}. Please generate ALL "
+                            f"{request.numQuestions} questions in a single JSON array. "
+                            f"Do not stop early."
+                        ),
+                    },
+                ]
+
+        # Warn if the LLM still generated fewer questions than requested
+        if len(parsed_questions) < request.numQuestions:
+            logger.warning(
+                f"LLM generated {len(parsed_questions)}/{request.numQuestions} questions "
+                f"after {max_attempts} attempts (raw length={len(raw_content)} chars)."
             )
 
         validated = _validate_quiz_questions(parsed_questions, distribution)
@@ -1712,7 +1784,8 @@ async def preview_quiz(request: QuizGenerationRequest):
 @app.get("/api/quiz/topics")
 async def get_quiz_topics(gradeLevel: Optional[str] = None):
     """
-    Return structured list of math topics organised by grade level.
+    Return structured list of SHS math topics organised by grade level.
+    Only Grade 11 and Grade 12 are supported.
     If gradeLevel is provided, return topics for that grade only.
     """
     if gradeLevel:
@@ -1729,7 +1802,11 @@ async def get_quiz_topics(gradeLevel: Optional[str] = None):
             detail=f"Grade level '{gradeLevel}' not found. Available: {list(MATH_TOPICS_BY_GRADE.keys())}",
         )
 
-    return {"allTopics": MATH_TOPICS_BY_GRADE}
+    # Return all SHS topics organized by grade
+    return {
+        "gradeLevels": list(MATH_TOPICS_BY_GRADE.keys()),
+        "allTopics": MATH_TOPICS_BY_GRADE,
+    }
 
 
 # ─── Student Competency Assessment ────────────────────────────
@@ -2195,6 +2272,165 @@ async def get_analytics_config():
     }
 
 
+# ─── Topic Mastery Analytics ──────────────────────────────────
+
+# SHS topic data for fallback/mock generation
+_SHS_TOPICS = {
+    "gen-math": {
+        "name": "General Mathematics",
+        "topics": [
+            ("Functions and Relations", "Functions and Their Graphs"),
+            ("Evaluating Functions", "Functions and Their Graphs"),
+            ("Operations on Functions", "Functions and Their Graphs"),
+            ("Composite Functions", "Functions and Their Graphs"),
+            ("Inverse Functions", "Functions and Their Graphs"),
+            ("Rational Functions", "Functions and Their Graphs"),
+            ("Exponential Functions", "Functions and Their Graphs"),
+            ("Logarithmic Functions", "Functions and Their Graphs"),
+            ("Simple Interest", "Business Mathematics"),
+            ("Compound Interest", "Business Mathematics"),
+            ("Annuities", "Business Mathematics"),
+            ("Loans and Amortization", "Business Mathematics"),
+            ("Stocks and Bonds", "Business Mathematics"),
+            ("Propositions and Connectives", "Logic"),
+            ("Truth Tables", "Logic"),
+            ("Logical Equivalence", "Logic"),
+            ("Valid Arguments and Fallacies", "Logic"),
+        ],
+    },
+    "stats-prob": {
+        "name": "Statistics and Probability",
+        "topics": [
+            ("Random Variables", "Random Variables"),
+            ("Discrete Probability Distributions", "Random Variables"),
+            ("Mean and Variance of Discrete RV", "Random Variables"),
+            ("Normal Distribution", "Normal Distribution"),
+            ("Standard Normal Distribution and Z-scores", "Normal Distribution"),
+            ("Areas Under the Normal Curve", "Normal Distribution"),
+            ("Sampling Distributions", "Sampling and Estimation"),
+            ("Central Limit Theorem", "Sampling and Estimation"),
+            ("Point Estimation", "Sampling and Estimation"),
+            ("Confidence Intervals", "Sampling and Estimation"),
+            ("Hypothesis Testing Concepts", "Hypothesis Testing"),
+            ("T-test", "Hypothesis Testing"),
+            ("Z-test", "Hypothesis Testing"),
+            ("Correlation and Regression", "Correlation and Regression"),
+        ],
+    },
+    "pre-calc": {
+        "name": "Pre-Calculus",
+        "topics": [
+            ("Conic Sections - Parabola", "Analytic Geometry"),
+            ("Conic Sections - Ellipse", "Analytic Geometry"),
+            ("Conic Sections - Hyperbola", "Analytic Geometry"),
+            ("Conic Sections - Circle", "Analytic Geometry"),
+            ("Systems of Nonlinear Equations", "Analytic Geometry"),
+            ("Sequences and Series", "Series and Induction"),
+            ("Arithmetic Sequences", "Series and Induction"),
+            ("Geometric Sequences", "Series and Induction"),
+            ("Mathematical Induction", "Series and Induction"),
+            ("Binomial Theorem", "Series and Induction"),
+            ("Angles and Unit Circle", "Trigonometry"),
+            ("Trigonometric Functions", "Trigonometry"),
+            ("Trigonometric Identities", "Trigonometry"),
+            ("Sum and Difference Formulas", "Trigonometry"),
+            ("Inverse Trigonometric Functions", "Trigonometry"),
+            ("Polar Coordinates", "Trigonometry"),
+        ],
+    },
+    "basic-calc": {
+        "name": "Basic Calculus",
+        "topics": [
+            ("Limits of Functions", "Limits"),
+            ("Limit Theorems", "Limits"),
+            ("One-Sided Limits", "Limits"),
+            ("Infinite Limits and Limits at Infinity", "Limits"),
+            ("Continuity of Functions", "Limits"),
+            ("Definition of the Derivative", "Derivatives"),
+            ("Differentiation Rules", "Derivatives"),
+            ("Chain Rule", "Derivatives"),
+            ("Implicit Differentiation", "Derivatives"),
+            ("Higher-Order Derivatives", "Derivatives"),
+            ("Related Rates", "Derivatives"),
+            ("Extrema and the First Derivative Test", "Derivatives"),
+            ("Concavity and the Second Derivative Test", "Derivatives"),
+            ("Optimization Problems", "Derivatives"),
+            ("Antiderivatives and Indefinite Integrals", "Integration"),
+            ("Definite Integrals and the FTC", "Integration"),
+            ("Integration by Substitution", "Integration"),
+            ("Area Under a Curve", "Integration"),
+        ],
+    },
+}
+
+
+@app.get("/api/analytics/topic-mastery")
+async def topic_mastery_analytics(
+    teacherId: str = Query(..., description="Teacher UID"),
+    classId: Optional[str] = Query(None, description="Optional class ID filter"),
+):
+    """
+    Aggregate per-topic mastery statistics for a teacher's class.
+    Returns topic-level averages, attempt counts, and mastery status.
+    """
+    import random
+
+    try:
+        # In production, this would query Firestore quiz submissions.
+        # For now, generate realistic mock data seeded by teacherId.
+        rng = random.Random(hash(teacherId))
+        total_students = 30
+
+        topics_out = []
+        mastered_count = 0
+        needs_attention_count = 0
+        excluded_count = 0
+
+        for subj_id, subj_data in _SHS_TOPICS.items():
+            for topic_name, unit in subj_data["topics"]:
+                attempted = rng.randint(3, total_students)
+                class_avg = round(rng.uniform(35, 95), 1)
+                above_85 = int(attempted * (rng.uniform(0.6, 0.95) if class_avg >= 85 else rng.uniform(0.05, 0.35)))
+                mastery_pct = round((above_85 / total_students) * 100, 1)
+
+                if attempted < 3:
+                    status = "no_data"
+                elif mastery_pct >= 75:
+                    status = "mastered"
+                    mastered_count += 1
+                elif class_avg >= 60:
+                    status = "on_track"
+                else:
+                    status = "needs_attention"
+                    needs_attention_count += 1
+
+                topics_out.append({
+                    "topicName": topic_name,
+                    "subjectId": subj_id,
+                    "unit": unit,
+                    "classAverage": class_avg,
+                    "studentsAttempted": attempted,
+                    "totalStudents": total_students,
+                    "studentsAbove85": above_85,
+                    "masteryPercentage": mastery_pct,
+                    "masteryStatus": status,
+                    "isExcluded": False,
+                })
+
+        return {
+            "topics": topics_out,
+            "summary": {
+                "totalTopicsTracked": len(topics_out),
+                "masteredCount": mastered_count,
+                "needsAttentionCount": needs_attention_count,
+                "excludedCount": excluded_count,
+            },
+        }
+    except Exception as e:
+        logger.error(f"Topic mastery analytics error: {e}")
+        raise HTTPException(status_code=500, detail=f"Topic mastery error: {str(e)}")
+
+
 # ─── Automation Engine Endpoints ──────────────────────────────