feat: quiz package

quiz/engine.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from quiz.models import QuizSession
+from quiz.scoring import xp_for_question, streak_label, compute_grade
+
+@dataclass
+class AnswerResult:
+    is_correct: bool
+    correct_idx: int
+    xp_delta: int
+    streak_label: str
+    grade: str
+    was_boss: bool
+
+class QuizEngine:
+    def submit_next(self, session: QuizSession, selected_idx: int) -> AnswerResult:
+        """Submit answer for the current question (regular or boss — auto-detected via is_boss)."""
+        if session.is_finished:
+            raise RuntimeError("Cannot submit answer: session is finished.")
+        question = session.current_question
+        is_correct = (selected_idx == question.correct_idx)
+        xp_delta = 0
+
+        if is_correct:
+            session.score += 1
+            xp_delta = xp_for_question(question.difficulty, is_boss=question.is_boss)
+            session.xp_earned += xp_delta
+            if not question.is_boss:
+                session.consecutive_correct += 1
+        else:
+            session.consecutive_correct = 0
+            if question.topic not in session.wrong_topics:
+                session.wrong_topics.append(question.topic)
+
+        session.current_idx += 1
+        label = streak_label(session.consecutive_correct)
+        grade = compute_grade(session.score, session.current_idx)
+        return AnswerResult(is_correct=is_correct, correct_idx=question.correct_idx,
+                            xp_delta=xp_delta, streak_label=label, grade=grade,
+                            was_boss=question.is_boss)
+
+    def final_grade(self, session: QuizSession) -> str:
+        return compute_grade(session.score, len(session.questions))

quiz/models.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import List
+import time
+
+VALID_DIFFICULTIES = {"easy", "medium", "hard"}
+VALID_TYPES = {"mcq", "tf", "fill"}
+
+@dataclass
+class Question:
+    text: str
+    topic: str                      # subject area — "Determinants" not question text
+    options: List[str]
+    correct_idx: int
+    explanation: str
+    difficulty: str
+    q_type: str
+    is_boss: bool = False
+    source_excerpt: str = ""        # snippet from original material for tutor context
+    language: str = "en"
+
+    def __post_init__(self):
+        if self.difficulty not in VALID_DIFFICULTIES:
+            raise ValueError(f"difficulty must be one of {VALID_DIFFICULTIES}, got '{self.difficulty}'")
+        if self.q_type not in VALID_TYPES:
+            raise ValueError(f"q_type must be one of {VALID_TYPES}, got '{self.q_type}'")
+        if not (0 <= self.correct_idx < len(self.options)):
+            raise ValueError(f"correct_idx {self.correct_idx} out of range for {len(self.options)} options")
+
+    @property
+    def correct_answer(self) -> str:
+        return self.options[self.correct_idx]
+
+@dataclass
+class QuizSession:
+    quest_name: str
+    questions: List[Question] = field(default_factory=list)
+    current_idx: int = 0
+    score: int = 0
+    consecutive_correct: int = 0
+    xp_earned: int = 0
+    start_time: float = field(default_factory=time.time)
+    wrong_topics: List[str] = field(default_factory=list)  # topic strings, not question text
+
+    @property
+    def is_finished(self) -> bool:
+        return self.current_idx >= len(self.questions)
+
+    @property
+    def current_question(self) -> Question | None:
+        if self.is_finished:
+            return None
+        return self.questions[self.current_idx]
+
+@dataclass
+class Quest:
+    name: str
+    topics: List[str]
+    boss_topic: str
+    difficulty: str
+    questions: List[Question] = field(default_factory=list)
+    unlocked: bool = True
+    completed: bool = False         # True only after user finishes the quest
+
+    def has_questions(self) -> bool:
+        return len(self.questions) > 0
+
+    def total_questions(self) -> int:
+        return len(self.questions)

quiz/scoring.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+_XP_TABLE = {"easy": 10, "medium": 20, "hard": 40}
+_BOSS_XP = 75
+_WEAK_THRESHOLD = 0.5
+_STREAK_LABELS = {0: "", 1: "Nice!", 2: "Good!", 3: "Great!", 4: "Excellent!"}
+
+def xp_for_question(difficulty: str, is_boss: bool) -> int:
+    if is_boss:
+        return _BOSS_XP
+    return _XP_TABLE.get(difficulty, 10)
+
+def streak_label(consecutive: int) -> str:
+    if consecutive >= 5:
+        return "LEGENDARY!"
+    return _STREAK_LABELS.get(consecutive, "")
+
+def compute_grade(score: int, total: int) -> str:
+    if total == 0:
+        return "Apprentice"
+    pct = score / total * 100
+    if pct >= 80: return "Champion"
+    if pct >= 60: return "Warrior"
+    return "Apprentice"
+
+def compute_mastery_delta(correct: int, total: int) -> float:
+    if total == 0:
+        return 0.0
+    return correct / total
+
+def should_unlock_revision_quest(mastery: float) -> bool:
+    return mastery < _WEAK_THRESHOLD
+
+def mastery_recommendation(mastery: float) -> str:
+    if mastery < 0.3:
+        return "Seriously review this topic before moving on."
+    if mastery < 0.5:
+        return "More practice needed — try the revision quest."
+    if mastery < 0.8:
+        return "Getting there — a few more battles will sharpen this."
+    return "Strong mastery — ready for the next challenge!"