@rookiestar/eng-lang-tutor 1.0.2 → 1.0.3

package/scripts/cli.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+CLI interface for eng-lang-tutor state management.
+
+This module provides command-line access to state management operations.
+"""
+
+import argparse
+import json
+from datetime import datetime
+from typing import Optional
+
+from state_manager import StateManager
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(description="State Manager for eng-lang-tutor")
+    parser.add_argument('--data-dir', default=None,
+                        help='Data directory path (default: ~/.openclaw/state/eng-lang-tutor or OPENCLAW_STATE_DIR env)')
+    parser.add_argument('command', nargs='?',
+                        choices=['show', 'backup', 'save_daily', 'record_view',
+                                 'stats', 'config', 'errors', 'schedule'],
+                        help='Command to execute')
+    parser.add_argument('--content-type', help='Content type for save_daily (keypoint, quiz)')
+    parser.add_argument('--content', help='JSON content for save_daily')
+    parser.add_argument('--date', help='Date for content (YYYY-MM-DD format)')
+    # Errors command options
+    parser.add_argument('--page', type=int, default=1, help='Page number for errors list')
+    parser.add_argument('--per-page', type=int, default=5, help='Items per page for errors')
+    parser.add_argument('--month', help='Filter errors by month (YYYY-MM)')
+    parser.add_argument('--random', type=int, help='Get N random errors')
+    parser.add_argument('--stats', action='store_true', help='Get error statistics')
+    parser.add_argument('--review', type=int, help='Get N errors for review session')
+    # Config command options
+    parser.add_argument('--cefr', help='Set CEFR level (A1-C2)')
+    parser.add_argument('--style', help='Set tutor style')
+    parser.add_argument('--oral-ratio', type=int, help='Set oral/written ratio (0-100)')
+    # Schedule command options
+    parser.add_argument('--keypoint-time', help='Set keypoint push time (HH:MM)')
+    parser.add_argument('--quiz-time', help='Set quiz push time (HH:MM)')
+
+    args = parser.parse_args()
+
+    sm = StateManager(args.data_dir)
+
+    if args.command == 'show' or not args.command:
+        state = sm.load_state()
+        print(json.dumps(state, indent=2, ensure_ascii=False))
+
+    elif args.command == 'backup':
+        backup_path = sm.backup_state()
+        print(f"Backup created: {backup_path}")
+
+    elif args.command == 'save_daily':
+        if not args.content_type or not args.content:
+            print("Error: --content-type and --content are required for save_daily")
+            exit(1)
+
+        try:
+            content = json.loads(args.content)
+        except json.JSONDecodeError as e:
+            print(f"Error: Invalid JSON content: {e}")
+            exit(1)
+
+        target_date = None
+        if args.date:
+            try:
+                target_date = datetime.strptime(args.date, '%Y-%m-%d').date()
+            except ValueError:
+                print("Error: Invalid date format. Use YYYY-MM-DD")
+                exit(1)
+
+        path = sm.save_daily_content(args.content_type, content, target_date)
+        print(f"Saved to: {path}")
+
+    elif args.command == 'record_view':
+        target_date = None
+        if args.date:
+            try:
+                target_date = datetime.strptime(args.date, '%Y-%m-%d').date()
+            except ValueError:
+                print("Error: Invalid date format. Use YYYY-MM-DD")
+                exit(1)
+
+        state = sm.load_state()
+        sm.record_keypoint_view(state, target_date)
+        sm.save_state(state)
+        print("View recorded successfully")
+
+    elif args.command == 'stats':
+        """Display learning progress summary."""
+        from gamification import GamificationManager
+        state = sm.load_state()
+        gm = GamificationManager()
+        summary = gm.get_progress_summary(state)
+        print(json.dumps(summary, indent=2, ensure_ascii=False))
+
+    elif args.command == 'config':
+        """Display or update user configuration."""
+        state = sm.load_state()
+
+        # If no update options, just show current config
+        if not any([args.cefr, args.style, args.oral_ratio is not None]):
+            config = {
+                "cefr_level": state.get("preferences", {}).get("cefr_level", "B1"),
+                "tutor_style": state.get("preferences", {}).get("tutor_style", "humorous"),
+                "oral_ratio": state.get("preferences", {}).get("oral_ratio", 70),
+                "topic_weights": state.get("preferences", {}).get("topic_weights", {}),
+                "schedule": state.get("schedule", {})
+            }
+            print(json.dumps(config, indent=2, ensure_ascii=False))
+        else:
+            # Update configuration
+            if args.cefr:
+                if args.cefr not in ['A1', 'A2', 'B1', 'B2', 'C1', 'C2']:
+                    print("Error: Invalid CEFR level. Must be A1, A2, B1, B2, C1, or C2")
+                    exit(1)
+                state = sm.update_preferences(state, cefr_level=args.cefr)
+                print(f"Updated CEFR level to: {args.cefr}")
+
+            if args.style:
+                if args.style not in ['humorous', 'rigorous', 'casual', 'professional']:
+                    print("Error: Invalid style. Must be humorous, rigorous, casual, or professional")
+                    exit(1)
+                state = sm.update_preferences(state, tutor_style=args.style)
+                print(f"Updated tutor style to: {args.style}")
+
+            if args.oral_ratio is not None:
+                if not 0 <= args.oral_ratio <= 100:
+                    print("Error: Oral ratio must be between 0 and 100")
+                    exit(1)
+                state = sm.update_preferences(state, oral_ratio=args.oral_ratio)
+                print(f"Updated oral ratio to: {args.oral_ratio}%")
+
+            sm.save_state(state)
+            print("Configuration updated successfully")
+
+    elif args.command == 'errors':
+        """Error notebook operations."""
+        state = sm.load_state()
+
+        if args.stats:
+            # Get error statistics
+            stats = sm.get_error_stats(state)
+            print(json.dumps(stats, indent=2, ensure_ascii=False))
+
+        elif args.review is not None:
+            # Get errors for review session
+            errors = sm.get_review_errors(state, count=args.review)
+            result = {
+                "count": len(errors),
+                "errors": errors
+            }
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+
+        else:
+            # Get paginated errors list
+            result = sm.get_errors_page(
+                state,
+                page=args.page,
+                per_page=args.per_page,
+                month=args.month,
+                random=args.random
+            )
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    elif args.command == 'schedule':
+        """Display or update schedule configuration."""
+        state = sm.load_state()
+
+        # If no update options, just show current schedule
+        if not any([args.keypoint_time, args.quiz_time]):
+            schedule = state.get("schedule", {})
+            print(json.dumps(schedule, indent=2, ensure_ascii=False))
+        else:
+            # Validate quiz_time must be later than keypoint_time
+            current_keypoint = state.get("schedule", {}).get("keypoint_time", "06:45")
+            current_quiz = state.get("schedule", {}).get("quiz_time", "22:45")
+
+            new_keypoint = args.keypoint_time or current_keypoint
+            new_quiz = args.quiz_time or current_quiz
+
+            # Time validation
+            def parse_time(t):
+                h, m = map(int, t.split(':'))
+                return h * 60 + m
+
+            if parse_time(new_quiz) <= parse_time(new_keypoint):
+                print("Error: Quiz time must be later than keypoint time")
+                exit(1)
+
+            state = sm.update_schedule(
+                state,
+                keypoint_time=new_keypoint,
+                quiz_time=new_quiz
+            )
+            sm.save_state(state)
+            print(f"Schedule updated: keypoint at {new_keypoint}, quiz at {new_quiz}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/constants.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""
+Shared constants for eng-lang-tutor.
+
+This module contains constants used across multiple scripts to avoid duplication.
+"""
+
+# Level thresholds (XP needed for each level)
+# Note: Level is Activity Level (活跃等级), measuring engagement depth,
+# NOT language ability (which is CEFR level A1-C2)
+LEVEL_THRESHOLDS = [
+    0, 50, 100, 200, 350,       # 1-5 Starter (启程者)
+    550, 800, 1100, 1500, 2000,  # 6-10 Traveler (行路人)
+    2600, 3300, 4100, 5000, 6000,  # 11-15 Explorer (探索者)
+    7200, 8500, 10000, 12000, 15000  # 16-20 Pioneer (开拓者)
+]
+
+# Level range to name mapping
+LEVEL_NAMES = {
+    (1, 5): "Starter",      # 启程者
+    (6, 10): "Traveler",    # 行路人
+    (11, 15): "Explorer",   # 探索者
+    (16, 20): "Pioneer"     # 开拓者
+}
+
+
+def get_level_name(level: int) -> str:
+    """
+    Get the journey stage name for a level.
+
+    Args:
+        level: Activity level (1-20)
+
+    Returns:
+        Stage name (Starter/Traveler/Explorer/Pioneer)
+    """
+    for (min_level, max_level), name in LEVEL_NAMES.items():
+        if min_level <= level <= max_level:
+            return name
+    return "Unknown"
+
+
+def calculate_level(xp: int) -> int:
+    """
+    Calculate level from total XP.
+
+    Args:
+        xp: Total experience points
+
+    Returns:
+        Level (1-20)
+    """
+    for i in range(len(LEVEL_THRESHOLDS) - 1, -1, -1):
+        if xp >= LEVEL_THRESHOLDS[i]:
+            return i + 1
+    return 1

package/scripts/gamification.py

@@ -14,17 +14,14 @@ 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
+
 
 class GamificationManager:
     """Manages gamification elements: levels, streaks, badges, gems."""
 
-    # Level thresholds (XP needed for each level)
-    LEVEL_THRESHOLDS = [
-        0, 50, 100, 200, 350,       # 1-5 Beginner
-        550, 800, 1100, 1500, 2000,  # 6-10 Intermediate
-        2600, 3300, 4100, 5000, 6000,  # 11-15 Advanced
-        7200, 8500, 10000, 12000, 15000  # 16-20 Expert
-    ]
+    # Use shared constants
+    LEVEL_THRESHOLDS = LEVEL_THRESHOLDS
 
     # Badge definitions
     BADGES = {
@@ -120,11 +117,13 @@ class GamificationManager:
                 return (new_streak, True, f"Streak continued! {new_streak} days")
 
             elif days_diff == 2 and user.get('streak_freeze', 0) > 0:
-                # Use streak freeze
+                # Use streak freeze - preserves streak continuity
                 state['user']['streak_freeze'] -= 1
                 new_streak = current_streak + 1
                 state['user']['streak'] = new_streak
-                return (new_streak, True, f"Streak freeze used! {new_streak} days")
+                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
@@ -146,10 +145,7 @@ class GamificationManager:
         Returns:
             Level (1-20)
         """
-        for i in range(len(self.LEVEL_THRESHOLDS) - 1, -1, -1):
-            if xp >= self.LEVEL_THRESHOLDS[i]:
-                return i + 1
-        return 1
+        return calculate_level(xp)
 
     def get_level_name(self, level: int) -> str:
         """Get the name for a level range (Journey Stage).
@@ -157,14 +153,7 @@ class GamificationManager:
         Note: This is Activity Level (活跃等级), measuring engagement depth,
         NOT language ability. For language ability, see CEFR level.
         """
-        if level <= 5:
-            return "Starter"      # 启程者
-        elif level <= 10:
-            return "Traveler"     # 行路人
-        elif level <= 15:
-            return "Explorer"     # 探索者
-        else:
-            return "Pioneer"      # 开拓者
+        return get_level_name(level)
 
     def check_level_up(self, old_xp: int, new_xp: int) -> Tuple[bool, Optional[int]]:
         """
@@ -203,6 +192,29 @@ class GamificationManager:
         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.
@@ -231,18 +243,14 @@ class GamificationManager:
             if badge_id in current_badges:
                 continue
 
-            condition = badge_info['condition']
-            try:
-                if eval(condition, {"__builtins__": {}}, 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)
-            except:
-                pass
+            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
@@ -335,7 +343,13 @@ class GamificationManager:
         current_threshold = self.LEVEL_THRESHOLDS[level - 1]
         xp_in_level = xp - current_threshold
         xp_to_next = next_threshold - xp if level < 20 else 0
-        level_progress = (xp_in_level / (next_threshold - current_threshold)) * 100 if level < 20 else 100
+
+        # 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,

package/scripts/scorer.py

@@ -12,6 +12,8 @@ XP Rules (Duolingo-style):
 from typing import Dict, Any, List, Tuple, Optional
 from datetime import datetime
 
+from constants import LEVEL_THRESHOLDS, calculate_level
+
 
 class Scorer:
     """Handles answer evaluation and XP calculation."""
@@ -164,23 +166,20 @@ class Scorer:
 
     def _update_state(self, state: Dict[str, Any], results: Dict[str, Any]) -> Dict[str, Any]:
         """
-        Update state with quiz results.
+        Update state with quiz results (modifies state in place).
 
         Args:
-            state: Current state
+            state: Current state (will be modified)
             results: Quiz evaluation results
 
         Returns:
-            Updated state
+            The same state dict (for convenience)
         """
-        import copy
-        updated_state = copy.deepcopy(state)
-
         # Update XP
-        updated_state['user']['xp'] += results['total_xp_earned']
+        state['user']['xp'] = state.get('user', {}).get('xp', 0) + results['total_xp_earned']
 
         # Update progress
-        progress = updated_state.get('progress', {})
+        progress = state.get('progress', {})
         old_total = progress.get('total_quizzes', 0)
         old_rate = progress.get('correct_rate', 0.0)
 
@@ -196,10 +195,11 @@ class Scorer:
         if results['accuracy'] == 100:
             progress['perfect_quizzes'] = progress.get('perfect_quizzes', 0) + 1
 
-        updated_state['progress'] = progress
+        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'],
@@ -209,9 +209,10 @@ class Scorer:
                     'explanation': error.get('explanation', ''),
                     'reviewed': False
                 }
-                updated_state['error_notebook'].append(error_entry)
+                error_notebook.append(error_entry)
+            state['error_notebook'] = error_notebook
 
-        return updated_state
+        return state
 
     def calculate_level(self, xp: int) -> int:
         """
@@ -223,19 +224,7 @@ class Scorer:
         Returns:
             Level (1-20)
         """
-        # Level thresholds (cumulative XP needed)
-        # Note: Level is Activity Level (活跃等级), measuring engagement depth
-        LEVEL_THRESHOLDS = [
-            0, 50, 100, 200, 350,      # 1-5 Starter (启程者)
-            550, 800, 1100, 1500, 2000,  # 6-10 Traveler (行路人)
-            2600, 3300, 4100, 5000, 6000,  # 11-15 Explorer (探索者)
-            7200, 8500, 10000, 12000, 15000  # 16-20 Pioneer (开拓者)
-        ]
-
-        for i in range(len(LEVEL_THRESHOLDS) - 1, -1, -1):
-            if xp >= LEVEL_THRESHOLDS[i]:
-                return i + 1
-        return 1
+        return calculate_level(xp)
 
     def get_xp_for_next_level(self, current_xp: int) -> Tuple[int, int]:
         """
@@ -247,14 +236,7 @@ class Scorer:
         Returns:
             Tuple of (xp_needed, xp_into_current_level)
         """
-        LEVEL_THRESHOLDS = [
-            0, 50, 100, 200, 350,
-            550, 800, 1100, 1500, 2000,
-            2600, 3300, 4100, 5000, 6000,
-            7200, 8500, 10000, 12000, 15000
-        ]
-
-        current_level = self.calculate_level(current_xp)
+        current_level = calculate_level(current_xp)
 
         if current_level >= 20:
             return (0, current_xp - LEVEL_THRESHOLDS[-1])