@rookiestar/eng-lang-tutor 1.0.1

package/scripts/core/gamification.py

@@ -0,0 +1,405 @@
+#!/usr/bin/env python3
+"""
+Gamification - Duolingo-style achievement system for eng-lang-tutor.
+
+Components:
+1. XP & Levels: XP accumulates, levels up at thresholds
+2. Streaks: Consecutive days of study, with freeze protection
+3. Badges: Achievement milestones
+4. Gems: Currency for streak freeze, hints
+
+Note: Leagues removed - not applicable for single-user scenario.
+"""
+
+from typing import Dict, Any, List, Tuple, Optional
+from datetime import datetime, date, timedelta
+
+from .constants import (
+    LEVEL_THRESHOLDS,
+    get_level_name,
+    calculate_level,
+    get_streak_multiplier,
+    STREAK_FREEZE_COST,
+    HINT_COST
+)
+
+
+class GamificationManager:
+    """Manages gamification elements: levels, streaks, badges, gems."""
+
+    # Badge definitions
+    BADGES = {
+        'first_steps': {
+            'name': 'First Steps',
+            'description': 'Complete your first quiz',
+            'condition': 'total_quizzes >= 1',
+            'gem_reward': 10
+        },
+        'week_warrior': {
+            'name': 'Week Warrior',
+            'description': '7-day streak',
+            'condition': 'streak >= 7',
+            'gem_reward': 25
+        },
+        'month_master': {
+            'name': 'Month Master',
+            'description': '30-day streak',
+            'condition': 'streak >= 30',
+            'gem_reward': 100
+        },
+        'perfect_10': {
+            'name': 'Perfect 10',
+            'description': '10 perfect quizzes',
+            'condition': 'perfect_quizzes >= 10',
+            'gem_reward': 50
+        },
+        'vocab_hunter': {
+            'name': 'Vocab Hunter',
+            'description': 'Learn 100 expressions',
+            'condition': 'expressions_learned >= 100',
+            'gem_reward': 75
+        },
+        'error_slayer': {
+            'name': 'Error Slayer',
+            'description': 'Clear 30 errors from notebook',
+            'condition': 'errors_cleared >= 30',
+            'gem_reward': 30
+        }
+    }
+
+    def __init__(self, state_manager=None):
+        """
+        Initialize the gamification manager.
+
+        Args:
+            state_manager: Optional StateManager instance
+        """
+        self.state_manager = state_manager
+
+    # Wrapper methods for backward compatibility with tests
+    def calculate_level(self, xp: int) -> int:
+        """Wrapper for calculate_level function."""
+        return calculate_level(xp)
+
+    def get_level_name(self, level: int) -> str:
+        """Wrapper for get_level_name function."""
+        return get_level_name(level)
+
+    def get_streak_multiplier(self, streak: int) -> float:
+        """Wrapper for get_streak_multiplier function."""
+        return get_streak_multiplier(streak)
+
+    def update_streak(self, state: Dict[str, Any], study_date: str) -> Tuple[int, bool, str]:
+        """
+        Update streak based on study activity.
+
+        Args:
+            state: Current state dictionary
+            study_date: Date of study (YYYY-MM-DD)
+
+        Returns:
+            Tuple of (new_streak, streak_continued, message)
+        """
+        user = state.get('user', {})
+        progress = state.get('progress', {})
+
+        last_study = progress.get('last_study_date')
+        current_streak = user.get('streak', 0)
+
+        try:
+            today = datetime.strptime(study_date, '%Y-%m-%d').date()
+        except ValueError:
+            return (current_streak, False, "Invalid date format")
+
+        if last_study:
+            try:
+                last = datetime.strptime(last_study, '%Y-%m-%d').date()
+            except ValueError:
+                last = None
+
+            if last == today:
+                # Already studied today
+                return (current_streak, False, "Already studied today")
+
+            days_diff = (today - last).days
+
+            if days_diff == 1:
+                # Consecutive day - streak continues
+                new_streak = current_streak + 1
+                state['user']['streak'] = new_streak
+                return (new_streak, True, f"Streak continued! {new_streak} days")
+
+            elif days_diff == 2 and user.get('streak_freeze', 0) > 0:
+                # Use streak freeze - preserves streak continuity
+                state['user']['streak_freeze'] -= 1
+                new_streak = current_streak + 1
+                state['user']['streak'] = new_streak
+                state['user']['last_freeze_used'] = study_date  # Track for display
+                remaining = state['user']['streak_freeze']
+                return (new_streak, True, f"Streak freeze used! {new_streak} days ({remaining} freeze remaining)")
+
+            else:
+                # Streak broken
+                state['user']['streak'] = 1
+                return (1, False, f"Streak broken. Starting over at 1 day")
+
+        else:
+            # First study ever
+            state['user']['streak'] = 1
+            return (1, True, "Started your streak!")
+
+    def check_level_up(self, old_xp: int, new_xp: int) -> Tuple[bool, Optional[int]]:
+        """
+        Check if user leveled up.
+
+        Args:
+            old_xp: XP before this session
+            new_xp: XP after this session
+
+        Returns:
+            Tuple of (leveled_up, new_level)
+        """
+        old_level = calculate_level(old_xp)
+        new_level = calculate_level(new_xp)
+
+        if new_level > old_level:
+            return (True, new_level)
+        return (False, None)
+
+    def update_level(self, state: Dict[str, Any]) -> Tuple[int, bool]:
+        """
+        Update level based on current XP.
+
+        Args:
+            state: Current state (will be modified in place)
+
+        Returns:
+            Tuple of (level, just_leveled_up)
+        """
+        xp = state.get('user', {}).get('xp', 0)
+        current_level = state.get('user', {}).get('level', 1)
+        new_level = calculate_level(xp)
+
+        state['user']['level'] = new_level
+
+        leveled_up = new_level > current_level
+        return (new_level, leveled_up)
+
+    def _check_badge_condition(self, badge_id: str, check_data: Dict[str, int]) -> bool:
+        """
+        Check if a badge condition is met using explicit condition functions.
+
+        Args:
+            badge_id: Badge identifier
+            check_data: Dictionary with stats for condition checking
+
+        Returns:
+            True if condition is met, False otherwise
+        """
+        # Explicit condition functions for each badge (no eval() for security)
+        conditions = {
+            'first_steps': lambda d: d.get('total_quizzes', 0) >= 1,
+            'week_warrior': lambda d: d.get('streak', 0) >= 7,
+            'month_master': lambda d: d.get('streak', 0) >= 30,
+            'perfect_10': lambda d: d.get('perfect_quizzes', 0) >= 10,
+            'vocab_hunter': lambda d: d.get('expressions_learned', 0) >= 100,
+            'error_slayer': lambda d: d.get('errors_cleared', 0) >= 30,
+        }
+        checker = conditions.get(badge_id)
+        return checker(check_data) if checker else False
+
+    def check_badges(self, state: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """
+        Check and award new badges.
+
+        Args:
+            state: Current state
+
+        Returns:
+            List of newly earned badges with details
+        """
+        earned = []
+        current_badges = state.get('user', {}).get('badges', [])
+        progress = state.get('progress', {})
+        user = state.get('user', {})
+
+        # Prepare badge check data
+        check_data = {
+            'total_quizzes': progress.get('total_quizzes', 0),
+            'streak': user.get('streak', 0),
+            'perfect_quizzes': progress.get('perfect_quizzes', 0),
+            'expressions_learned': progress.get('expressions_learned', 0),
+            'errors_cleared': sum(1 for e in state.get('error_notebook', []) if e.get('reviewed'))
+        }
+
+        for badge_id, badge_info in self.BADGES.items():
+            if badge_id in current_badges:
+                continue
+
+            if self._check_badge_condition(badge_id, check_data):
+                earned.append({
+                    'id': badge_id,
+                    'name': badge_info['name'],
+                    'description': badge_info['description'],
+                    'gem_reward': badge_info['gem_reward']
+                })
+                current_badges.append(badge_id)
+
+        state['user']['badges'] = current_badges
+        return earned
+
+    def award_gems(self, state: Dict[str, Any], action: str, amount: int = 0) -> int:
+        """
+        Award gems for various actions.
+
+        Args:
+            state: Current state
+            action: Type of action
+            amount: Specific amount (overrides default)
+
+        Returns:
+            Number of gems awarded
+        """
+        GEM_REWARDS = {
+            'quiz_complete': 5,
+            'perfect_quiz': 10,
+            'streak_milestone': 20,
+            'level_up': 25,
+            'badge_earned': 0,  # Use badge-specific amount
+            'daily_goal': 15
+        }
+
+        gems = amount if amount > 0 else GEM_REWARDS.get(action, 0)
+        state['user']['gems'] = state.get('user', {}).get('gems', 0) + gems
+
+        return gems
+
+    def spend_gems(self, state: Dict[str, Any], action: str) -> Tuple[bool, int]:
+        """
+        Spend gems on items.
+
+        Reserved for future gem economy features:
+        - Buy streak freeze: 50 gems
+        - Buy quiz hint: 10 gems
+
+        Args:
+            state: Current state
+            action: What to spend gems on
+
+        Returns:
+            Tuple of (success, gems_spent)
+        """  # noqa: DOC501 - Reserved for future use
+        GEM_COSTS = {
+            'streak_freeze': STREAK_FREEZE_COST,
+            'hint': HINT_COST
+        }
+
+        cost = GEM_COSTS.get(action, 0)
+        current_gems = state.get('user', {}).get('gems', 0)
+
+        if current_gems >= cost:
+            state['user']['gems'] = current_gems - cost
+
+            if action == 'streak_freeze':
+                state['user']['streak_freeze'] = state.get('user', {}).get('streak_freeze', 0) + 1
+
+            return (True, cost)
+
+        return (False, 0)
+
+    def get_progress_summary(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Get a summary of user's progress.
+
+        Args:
+            state: Current state
+
+        Returns:
+            Summary dictionary
+        """
+        user = state.get('user', {})
+        progress = state.get('progress', {})
+
+        xp = user.get('xp', 0)
+        level = user.get('level', 1)
+
+        # Calculate XP to next level
+        next_threshold = LEVEL_THRESHOLDS[min(level, 19)]
+        current_threshold = LEVEL_THRESHOLDS[level - 1]
+        xp_in_level = xp - current_threshold
+        xp_to_next = next_threshold - xp if level < 20 else 0
+
+        # Safe division for level progress
+        threshold_diff = next_threshold - current_threshold
+        if level < 20 and threshold_diff > 0:
+            level_progress = (xp_in_level / threshold_diff) * 100
+        else:
+            level_progress = 100.0 if level >= 20 else 0.0
+
+        return {
+            'xp': xp,
+            'level': level,
+            'level_name': get_level_name(level),
+            'xp_in_level': xp_in_level,
+            'xp_to_next_level': xp_to_next,
+            'level_progress': round(level_progress, 1),
+            'streak': user.get('streak', 0),
+            'streak_multiplier': get_streak_multiplier(user.get('streak', 0)),
+            'gems': user.get('gems', 0),
+            'badges': len(user.get('badges', [])),
+            'total_badges': len(self.BADGES)
+        }
+
+
+# CLI interface for testing
+if __name__ == "__main__":
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(description="Gamification for eng-lang-tutor")
+    parser.add_argument('--demo', action='store_true', help='Run demo')
+    parser.add_argument('--state', type=str, help='Path to state JSON file')
+
+    args = parser.parse_args()
+
+    gm = GamificationManager()
+
+    if args.demo:
+        state = {
+            "user": {
+                "xp": 1250,
+                "level": 7,
+                "streak": 5,
+                "streak_freeze": 2,
+                "gems": 100,
+                "badges": ["first_steps"]
+            },
+            "progress": {
+                "total_quizzes": 15,
+                "perfect_quizzes": 3,
+                "expressions_learned": 45,
+                "last_study_date": "2026-02-19"
+            },
+            "error_notebook": [
+                {"reviewed": True}, {"reviewed": True}, {"reviewed": False}
+            ]
+        }
+
+        print("=== Progress Summary ===")
+        summary = gm.get_progress_summary(state)
+        print(json.dumps(summary, indent=2))
+
+        print("\n=== Update Streak (today: 2026-02-20) ===")
+        streak, continued, msg = gm.update_streak(state, "2026-02-20")
+        print(f"Streak: {streak}, Continued: {continued}, Message: {msg}")
+
+        print("\n=== Check Badges ===")
+        new_badges = gm.check_badges(state)
+        print(f"New badges earned: {new_badges}")
+
+    elif args.state:
+        with open(args.state) as f:
+            state = json.load(f)
+
+        summary = gm.get_progress_summary(state)
+        print(json.dumps(summary, indent=2))

package/scripts/core/scorer.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+Scorer - Answer evaluation and XP calculation for eng-lang-tutor.
+
+XP Rules (Duolingo-style):
+- Correct answer: +10-15 XP (based on difficulty)
+- Perfect quiz (100%): +20 bonus XP
+- Streak multiplier: 1.0 + (streak_days * 0.05), max 2.0
+- Wrong answer: 0 XP, add to error notebook
+"""
+
+from typing import Dict, Any, List, Tuple, Optional
+from datetime import datetime
+
+from .constants import LEVEL_THRESHOLDS, calculate_level, get_streak_multiplier
+
+
+class Scorer:
+    """Handles answer evaluation and XP calculation."""
+
+    # Base XP values by question type
+    BASE_XP = {
+        'multiple_choice': 10,
+        'fill_blank': 12,
+        'dialogue_completion': 15,
+        'chinglish_fix': 15
+    }
+
+    # Bonus XP
+    PERFECT_QUIZ_BONUS = 20
+
+    def __init__(self, state_manager=None):
+        """
+        Initialize the scorer.
+
+        Args:
+            state_manager: Optional StateManager instance for state updates
+        """
+        self.state_manager = state_manager
+
+    # Wrapper methods for backward compatibility with tests
+    def calculate_level(self, xp: int) -> int:
+        """Wrapper for calculate_level function."""
+        return calculate_level(xp)
+
+    def get_streak_multiplier(self, streak: int) -> float:
+        """Wrapper for get_streak_multiplier function."""
+        return get_streak_multiplier(streak)
+
+    def evaluate_quiz(
+        self,
+        quiz: Dict[str, Any],
+        user_answers: Dict[str, Any],
+        state: Dict[str, Any]
+    ) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        """
+        Evaluate user answers and calculate XP.
+
+        Args:
+            quiz: Quiz dictionary with questions and correct answers
+            user_answers: User's answers (question_id -> answer)
+            state: Current state dictionary
+
+        Returns:
+            Tuple of (results, updated_state)
+        """
+        results = {
+            'date': datetime.now().strftime('%Y-%m-%d'),
+            'quiz_date': quiz.get('quiz_date', ''),
+            'total_questions': len(quiz.get('questions', [])),
+            'correct_count': 0,
+            'wrong_count': 0,
+            'base_xp': 0,
+            'streak_multiplier': 1.0,
+            'bonus_xp': 0,
+            'total_xp_earned': 0,
+            'accuracy': 0.0,
+            'passed': False,
+            'details': [],
+            'errors': []
+        }
+
+        questions = quiz.get('questions', [])
+        total_base_xp = 0
+        correct_count = 0
+
+        for question in questions:
+            qid = str(question.get('id', ''))
+            user_answer = user_answers.get(qid, '').strip()
+            is_correct = self._check_answer(question, user_answer)
+
+            question_type = question.get('type', 'multiple_choice')
+            base_xp = self.BASE_XP.get(question_type, 10)
+
+            detail = {
+                'question_id': qid,
+                'question_type': question_type,
+                'user_answer': user_answer,
+                'correct_answer': str(question.get('correct_answer', '')),
+                'is_correct': is_correct,
+                'base_xp': base_xp if is_correct else 0
+            }
+
+            if is_correct:
+                total_base_xp += base_xp
+                correct_count += 1
+            else:
+                # Record error
+                results['errors'].append({
+                    'question_id': qid,
+                    'question': question.get('question', ''),
+                    'question_type': question_type,
+                    'user_answer': user_answer,
+                    'correct_answer': question.get('correct_answer', ''),
+                    'explanation': question.get('explanation', '')
+                })
+
+            results['details'].append(detail)
+
+        # Calculate accuracy
+        total_questions = len(questions)
+        accuracy = (correct_count / total_questions * 100) if total_questions > 0 else 0
+
+        # Calculate streak multiplier
+        streak = state.get('user', {}).get('streak', 0)
+        streak_multiplier = get_streak_multiplier(streak)
+
+        # Calculate total XP with streak bonus
+        total_xp = int(total_base_xp * streak_multiplier)
+
+        # Perfect quiz bonus
+        bonus_xp = 0
+        if correct_count == total_questions and total_questions > 0:
+            bonus_xp = self.PERFECT_QUIZ_BONUS
+            total_xp += bonus_xp
+
+        # Update results
+        results['correct_count'] = correct_count
+        results['wrong_count'] = total_questions - correct_count
+        results['base_xp'] = total_base_xp
+        results['streak_multiplier'] = streak_multiplier
+        results['bonus_xp'] = bonus_xp
+        results['total_xp_earned'] = total_xp
+        results['accuracy'] = round(accuracy, 1)
+        results['passed'] = accuracy >= quiz.get('passing_score', 70)
+
+        # Update state
+        updated_state = self._update_state(state, results)
+
+        return results, updated_state
+
+    def _check_answer(self, question: Dict[str, Any], user_answer: str) -> bool:
+        """
+        Check if user answer matches correct answer.
+
+        Args:
+            question: Question dictionary with correct_answer
+            user_answer: User's answer string
+
+        Returns:
+            True if correct, False otherwise
+        """
+        correct = str(question.get('correct_answer', '')).strip()
+        user = user_answer.strip()
+
+        # Case-insensitive comparison
+        return user.lower() == correct.lower()
+
+    def _update_state(self, state: Dict[str, Any], results: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Update state with quiz results (modifies state in place).
+
+        Args:
+            state: Current state (will be modified)
+            results: Quiz evaluation results
+
+        Returns:
+            The same state dict (for convenience)
+        """
+        # Update XP
+        state['user']['xp'] = state.get('user', {}).get('xp', 0) + results['total_xp_earned']
+
+        # Update progress
+        progress = state.get('progress', {})
+        old_total = progress.get('total_quizzes', 0)
+        old_rate = progress.get('correct_rate', 0.0)
+
+        # Update correct rate (running average)
+        new_total = old_total + 1
+        new_rate = ((old_rate * old_total) + results['accuracy']) / new_total
+
+        progress['total_quizzes'] = new_total
+        progress['correct_rate'] = round(new_rate, 1)
+        progress['last_study_date'] = results['date']
+
+        # Track perfect quizzes
+        if results['accuracy'] == 100:
+            progress['perfect_quizzes'] = progress.get('perfect_quizzes', 0) + 1
+
+        state['progress'] = progress
+
+        # Add errors to notebook
+        if results['errors']:
+            error_notebook = state.get('error_notebook', [])
+            for error in results['errors']:
+                error_entry = {
+                    'date': results['date'],
+                    'question': error.get('question', ''),
+                    'user_answer': error.get('user_answer', ''),
+                    'correct_answer': error.get('correct_answer', ''),
+                    'explanation': error.get('explanation', ''),
+                    'reviewed': False
+                }
+                error_notebook.append(error_entry)
+            state['error_notebook'] = error_notebook
+
+        return state
+
+    def get_xp_for_next_level(self, current_xp: int) -> Tuple[int, int]:
+        """
+        Get XP needed for next level.
+
+        Args:
+            current_xp: Current total XP
+
+        Returns:
+            Tuple of (xp_needed, xp_into_current_level)
+        """
+        current_level = calculate_level(current_xp)
+
+        if current_level >= 20:
+            return (0, current_xp - LEVEL_THRESHOLDS[-1])
+
+        next_threshold = LEVEL_THRESHOLDS[current_level]
+        current_threshold = LEVEL_THRESHOLDS[current_level - 1]
+
+        xp_needed = next_threshold - current_xp
+        xp_into_level = current_xp - current_threshold
+
+        return (xp_needed, xp_into_level)
+
+
+# CLI interface for testing
+if __name__ == "__main__":
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(description="Scorer for eng-lang-tutor")
+    parser.add_argument('--quiz', type=str, help='Path to quiz JSON file')
+    parser.add_argument('--answers', type=str, help='Path to user answers JSON file')
+    parser.add_argument('--state', type=str, help='Path to state JSON file')
+    parser.add_argument('--demo', action='store_true', help='Run demo')
+
+    args = parser.parse_args()
+
+    scorer = Scorer()
+
+    if args.demo:
+        # Demo quiz
+        quiz = {
+            "quiz_date": "2026-02-20",
+            "questions": [
+                {"id": 1, "type": "multiple_choice", "correct_answer": "B", "xp_value": 10},
+                {"id": 2, "type": "fill_blank", "correct_answer": "gonna", "xp_value": 12},
+                {"id": 3, "type": "dialogue_completion", "correct_answer": "Touch base", "xp_value": 15}
+            ],
+            "passing_score": 70
+        }
+
+        # Demo answers (2 correct, 1 wrong)
+        answers = {"1": "B", "2": "gonna", "3": "wrong answer"}
+
+        # Demo state
+        state = {
+            "user": {"xp": 100, "streak": 5, "level": 2},
+            "progress": {"total_quizzes": 10, "correct_rate": 75.0}
+        }
+
+        results, updated = scorer.evaluate_quiz(quiz, answers, state)
+        print("Results:")
+        print(json.dumps(results, indent=2))
+        print("\nUpdated State (user section):")
+        print(json.dumps(updated['user'], indent=2))
+        print(json.dumps(updated['progress'], indent=2))
+
+    elif args.quiz and args.answers and args.state:
+        with open(args.quiz) as f:
+            quiz = json.load(f)
+        with open(args.answers) as f:
+            answers = json.load(f)
+        with open(args.state) as f:
+            state = json.load(f)
+
+        results, updated = scorer.evaluate_quiz(quiz, answers, state)
+        print(json.dumps(results, indent=2))