Add files via upload

backend/models.py

@@ -525,6 +525,7 @@ class StudentDescriptiveQuestionResult(BaseModel):
     key_points_covered: List[str] = Field(default_factory=list)
     key_points_missing: List[str] = Field(default_factory=list)
     evidence_quote: Optional[str] = None
+    explanation: Optional[str] = None
 
 
 class StudentDescriptiveQuizResult(BaseModel):

backend/quiz_engine.py

@@ -98,16 +98,68 @@ def _is_similar_question(q_text: str, existing_q_texts: List[str], threshold: fl
     return False
 
 
+def _resolve_mcq_correct_option(corr_val: Any, options: List[MCQOption]) -> Optional[str]:
+    """
+    Robustly resolves correct option letter ('A', 'B', 'C', 'D') even if LLM returns
+    'Option B', '(C)', 'B.', or the full text of the option statement.
+    """
+    if not corr_val:
+        return None
+
+    raw_str = str(corr_val).strip()
+    upper_str = raw_str.upper()
+
+    # Direct match: 'A', 'B', 'C', 'D'
+    if upper_str in ("A", "B", "C", "D"):
+        return upper_str
+
+    # Prefix/regex match: 'Option B', '(B)', 'B:', 'B)'
+    match = re.search(r'(?:OPTION|ANSWER)?\s*[\(\[]?\s*([A-D])\s*[\)\]\:\.\-]?', upper_str)
+    if match and len(raw_str) <= 12:
+        return match.group(1)
+
+    # If LLM returned text (e.g. "Newton's first law..."), find the best matching option
+    corr_tokens = _normalize_tokens(raw_str)
+    if corr_tokens and options:
+        best_opt_id = None
+        best_score = 0.0
+        for opt in options:
+            opt_tokens = _normalize_tokens(opt.text)
+            if not opt_tokens:
+                continue
+            inter = len(corr_tokens & opt_tokens)
+            union = len(corr_tokens | opt_tokens)
+            score = (inter / union) if union > 0 else 0.0
+            if score > best_score and score >= 0.40:
+                best_score = score
+                best_opt_id = opt.id.upper()
+        if best_opt_id in ("A", "B", "C", "D"):
+            return best_opt_id
+
+    # Fallback to single character if it is strictly A-D
+    first_char = upper_str[:1]
+    if first_char in ("A", "B", "C", "D"):
+        return first_char
+
+    return None
+
+
 def _is_valid_mcq(q: Any) -> bool:
-    """Validates that a generated MCQ is complete, non-dummy, and has 4 valid distinct options."""
+    """Validates that a generated MCQ is complete, non-dummy, has valid correct_option, and 4 distinct options."""
     if not isinstance(q, QuizQuestion) or not q.question or len(q.question.strip()) < 10:
         return False
-    if len(q.options) != 4:
+    if not q.correct_option or q.correct_option.strip().upper() not in ("A", "B", "C", "D"):
+        return False
+    if not q.options or len(q.options) != 4:
         return False
     seen_texts = set()
+    option_ids = set()
     for opt in q.options:
         text = opt.text.strip()
         opt_id = opt.id.strip().upper()
+        if opt_id not in ("A", "B", "C", "D") or opt_id in option_ids:
+            return False
+        option_ids.add(opt_id)
         if len(text) <= 1:
             return False
         if text.upper() in (opt_id, f"OPTION {opt_id}", "A", "B", "C", "D"):
@@ -116,6 +168,17 @@ def _is_valid_mcq(q: Any) -> bool:
         if lower_t in seen_texts:
             return False
         seen_texts.add(lower_t)
+
+    # Check pairwise word overlap (Jaccard similarity) between options to catch near-duplicates / rephrasings
+    tokens_list = [_normalize_tokens(opt.text) for opt in q.options]
+    for i in range(len(tokens_list)):
+        for j in range(i + 1, len(tokens_list)):
+            t1, t2 = tokens_list[i], tokens_list[j]
+            if len(t1) >= 5 and len(t2) >= 5:
+                inter = len(t1 & t2)
+                union = len(t1 | t2)
+                if union > 0 and (inter / union) >= 0.82:
+                    return False
     return True
 
 
@@ -143,11 +206,13 @@ def _is_valid_truefalse(q: Any) -> bool:
 
 
 def _is_valid_descriptive(q: Any) -> bool:
-    """Validates that a generated Descriptive question is complete, non-dummy, and has a substantive answer."""
+    """Validates that a generated Descriptive question is complete, non-dummy, and has a substantive answer and explanation."""
     if not isinstance(q, DescriptiveQuestion) or not q.question or len(q.question.strip()) < 10:
         return False
     if not q.model_answer or len(q.model_answer.strip()) < 15:
         return False
+    if not q.explanation or len(q.explanation.strip()) < 5 or q.explanation.strip().lower() in ("none", "null"):
+        return False
     return True
 
 
@@ -599,7 +664,7 @@ class RAGQuizEngine:
         self.gemini_api_key = new_key.strip()
         self._init_client()
 
-    def _create_fresh_llm(self):
+    def _create_fresh_llm(self, max_new_tokens: int = 700):
         """Creates a fresh LangChain LLM instance bound to the active event loop to prevent 'Event loop is closed' errors."""
         if not self.token:
             return None
@@ -609,7 +674,7 @@ class RAGQuizEngine:
                 repo_id=self.model,
                 huggingfacehub_api_token=self.token,
                 task="text-generation",
-                max_new_tokens=1500,
+                max_new_tokens=max_new_tokens,
                 temperature=0.7
             )
             return ChatHuggingFace(llm=endpoint)
@@ -643,16 +708,20 @@ class RAGQuizEngine:
             anchor = BLOOM_ANCHORS[idx % len(BLOOM_ANCHORS)]
             seed = random.randint(1000, 9999999)
 
-            focal_clause = ""
+            focal = None
             if context_chunks and len(context_chunks) > 0:
                 focal = context_chunks[idx % len(context_chunks)]
-                focal_clause = f"\nFOCAL PASSAGE EXCERPT (Base this question on the specific facts or events in this excerpt):\n{focal}\n"
 
             exclude_clause = ""
             if exclude_stems:
                 clean_stems = [s[:60] for s in exclude_stems[:3]]
                 exclude_clause = f"\nDO NOT repeat or ask about these already covered topics: {'; '.join(clean_stems)}\n"
 
+            knowledge_block = (
+                f"FOCAL TEXTBOOK EXCERPT (Base your question and options strictly on this specific passage):\n{focal}\n"
+                if focal else f"Textbook Knowledge:\n{context_text}\n"
+            )
+
             if is_hindi:
                 system_prompt = (
                     f"You are an expert Hindi language and literature (हिन्दी भाषा एवं साहित्य) examiner for "
@@ -672,9 +741,8 @@ class RAGQuizEngine:
                     + (f"Topic: {topic}\n" if topic else "")
                     + f"Question #{idx+1} Cognitive Level: {anchor['level']}\n"
                     f"Entropy Seed: {seed}\n"
-                    f"{focal_clause}"
                     f"{exclude_clause}\n"
-                    f"Textbook Context:\n{context_text}\n\n"
+                    f"{knowledge_block}\n\n"
                     "Generate exactly 1 high-quality multiple choice question with 4 options, the correct option, and an explanation."
                 )
             else:
@@ -689,7 +757,10 @@ class RAGQuizEngine:
                     "3. CRITICAL RULE FOR OPTIONS:\n"
                     "   - The 'text' field of each option MUST contain the full descriptive answer statement (e.g. '100 pesos', 'To preserve Lencho faith in God', 'It increases quadratically').\n"
                     "   - NEVER set 'text' to just 'A', 'B', 'C', 'D' or single letters. All 4 option texts must be meaningful and distinct.\n"
-                    "4. Exactly ONE option must be correct. The other 3 must be plausible distractors.\n"
+                    "4. ALL 4 OPTIONS MUST BE DISTINCT AND UNIQUE:\n"
+                    "   - Exactly ONE option must be correct. The other 3 must be plausible distractors.\n"
+                    "   - Distractors must NOT be slight rephrasings or synonyms of the correct answer or each other.\n"
+                    "   - Each distractor must represent a completely distinct concept, alternative scientific law/effect, or different outcome.\n"
                     "5. Shuffle the correct option position randomly.\n"
                     "6. SCIENTIFIC NOTATION: Use clean symbols (e.g. ε₀, μ₀, π, ℏ, °C) and superscripts/subscripts (e.g. 10⁻¹², C² N⁻¹ m⁻², m/s²).\n"
                     "7. NEVER mention page numbers or figure numbers."
@@ -699,10 +770,9 @@ class RAGQuizEngine:
                     + (f"Topic: {topic}\n" if topic else "")
                     + f"Question #{idx+1} Cognitive Level: {anchor['level']}\n"
                     f"Entropy Seed: {seed}\n"
-                    f"{focal_clause}"
                     f"{exclude_clause}\n"
-                    f"Textbook Knowledge:\n{context_text}\n\n"
-                    "Generate exactly 1 high-quality multiple choice question with 4 options, the correct option, and an explanation."
+                    f"{knowledge_block}\n\n"
+                    "Generate exactly 1 high-quality multiple choice question with 4 distinct options, the correct option identifier (A, B, C, or D), and an explanation."
                 )
 
             messages = [
@@ -723,11 +793,11 @@ class RAGQuizEngine:
                     ))
 
                 q_val = getattr(raw, "question", None) or (raw.get("question") if isinstance(raw, dict) else "")
-                corr_val = getattr(raw, "correct_option", None) or (raw.get("correct_option") if isinstance(raw, dict) else "A")
+                corr_val = getattr(raw, "correct_option", None) or (raw.get("correct_option") if isinstance(raw, dict) else "")
                 expl_val = getattr(raw, "explanation", None) or (raw.get("explanation") if isinstance(raw, dict) else "")
 
                 q_text = format_scientific_symbols(_sanitize_text(str(q_val)))
-                corr_opt = str(corr_val).strip().upper()[:1] or "A"
+                corr_opt = _resolve_mcq_correct_option(corr_val, options) or ""
                 expl = format_scientific_symbols(str(expl_val))
 
                 candidate = QuizQuestion(
@@ -754,7 +824,7 @@ class RAGQuizEngine:
 
         for r in results:
             if isinstance(r, QuizQuestion) and _is_valid_mcq(r):
-                if not _is_similar_question(r.question, accepted_stems):
+                if not _is_similar_question(r.question, accepted_stems, threshold=0.70):
                     valid_questions.append(r)
                     accepted_stems.append(r.question)
                     if len(valid_questions) == num_questions:
@@ -772,7 +842,7 @@ class RAGQuizEngine:
             topup_results = await asyncio.gather(*topup_tasks, return_exceptions=True)
             for r in topup_results:
                 if isinstance(r, QuizQuestion) and _is_valid_mcq(r):
-                    if not _is_similar_question(r.question, accepted_stems):
+                    if not _is_similar_question(r.question, accepted_stems, threshold=0.70):
                         valid_questions.append(r)
                         accepted_stems.append(r.question)
                         if len(valid_questions) == num_questions:
@@ -788,7 +858,7 @@ class RAGQuizEngine:
             final_topup_results = await asyncio.gather(*final_topup_tasks, return_exceptions=True)
             for r in final_topup_results:
                 if isinstance(r, QuizQuestion) and _is_valid_mcq(r):
-                    if not _is_similar_question(r.question, accepted_stems):
+                    if not _is_similar_question(r.question, accepted_stems, threshold=0.70):
                         valid_questions.append(r)
                         accepted_stems.append(r.question)
                         if len(valid_questions) == num_questions:
@@ -1332,8 +1402,9 @@ class RAGQuizEngine:
                     "1. Formulate 1 clear, academic descriptive question grounded strictly in the provided textbook context.\n"
                     "2. MODEL ANSWER: Provide a thorough, authoritative reference answer that would achieve full marks.\n"
                     "3. KEY FACTS: List 3 to 6 distinct, concrete facts, terms, or steps that are mandatory in a correct answer.\n"
-                    "4. SCIENTIFIC NOTATION: Use clean scientific symbols (e.g. ε₀, μ₀, π, 10⁻¹², m/s²) where applicable.\n"
-                    "5. ZERO FLUFF: Keep the question direct and unambiguous. Do not reference 'in the passage' or 'according to the text'."
+                    "4. EXPLANATION: Provide a 1-2 sentence educational explanation summarizing the core principle being tested.\n"
+                    "5. SCIENTIFIC NOTATION: Use clean scientific symbols (e.g. ε₀, μ₀, π, 10⁻¹², m/s²) where applicable.\n"
+                    "6. ZERO FLUFF: Keep the question direct and unambiguous. Do not reference 'in the passage' or 'according to the text'."
                 )
                 user_prompt = (
                     f"Board: {board_id.upper()} | Class: {class_id} | Subject: {subject} | Chapter: {chapter}\n"
@@ -1342,7 +1413,7 @@ class RAGQuizEngine:
                     f"Entropy Seed: {seed}\n"
                     f"{exclude_clause}\n"
                     f"{knowledge_block}\n\n"
-                    f"Generate exactly 1 descriptive question with model answer and key facts."
+                    f"Generate exactly 1 descriptive question with model answer, key facts, and educational explanation."
                 )
 
             messages = [
@@ -1363,7 +1434,10 @@ class RAGQuizEngine:
                 q_text = format_scientific_symbols(_sanitize_text(str(q_val)))
                 model_ans = format_scientific_symbols(str(ans_val))
                 cleaned_facts = [format_scientific_symbols(str(f).strip()) for f in facts_val if str(f).strip()]
-                expl = format_scientific_symbols(str(expl_val) or f"Tests understanding of {topic or chapter}.")
+                clean_expl = str(expl_val).strip() if expl_val is not None else ""
+                if not clean_expl or clean_expl.lower() in ("none", "null", ""):
+                    clean_expl = f"Tests comprehensive conceptual understanding of {topic or chapter} principles."
+                expl = format_scientific_symbols(clean_expl)
 
                 candidate = DescriptiveQuestion(
                     id=idx + 1,
@@ -3068,7 +3142,8 @@ class RAGQuizEngine:
                     feedback="No answer provided.",
                     key_points_covered=[],
                     key_points_missing=q.key_facts,
-                    evidence_quote=q.source_context
+                    evidence_quote=q.source_context,
+                    explanation=q.explanation
                 )
 
             system_prompt = (
@@ -3136,7 +3211,8 @@ class RAGQuizEngine:
                     feedback=str(fb) or ("Good answer." if is_correct else "Needs improvement on key details."),
                     key_points_covered=[str(c) for c in covered if str(c).strip()],
                     key_points_missing=[str(m) for m in missing if str(m).strip()],
-                    evidence_quote=str(ev) if ev else q.source_context
+                    evidence_quote=str(ev) if ev else q.source_context,
+                    explanation=q.explanation
                 )
             except Exception as e:
                 print(f"[AI Engine] Error grading descriptive question #{q.id}: {e}")
@@ -3154,7 +3230,8 @@ class RAGQuizEngine:
                     feedback="Automated grading fallback applied.",
                     key_points_covered=[],
                     key_points_missing=q.key_facts,
-                    evidence_quote=q.source_context
+                    evidence_quote=q.source_context,
+                    explanation=q.explanation
                 )
 
         async def grade_all_answers() -> List[StudentDescriptiveQuestionResult]: