@rookiestar/eng-lang-tutor 1.0.2 → 1.0.4

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])

package/scripts/state_manager.py

@@ -16,6 +16,8 @@ from datetime import datetime, date
 from typing import Dict, Any, Optional, List
 import shutil
 
+from utils import deep_merge
+
 
 def get_default_state_dir() -> Path:
     """
@@ -116,6 +118,16 @@ class StateManager:
         except Exception as e:
             print(f"Warning: Migration failed: {e}")
             print("Will use new empty state directory.")
+            # Log migration failure to event log (after ensuring directories exist)
+            try:
+                self._ensure_directories()
+                self.append_event('migration_failed', {
+                    "error": str(e),
+                    "source_dir": str(old_data_dir),
+                    "target_dir": str(self.data_dir)
+                })
+            except Exception:
+                pass  # Silently ignore logging failures during migration
 
     def _ensure_directories(self) -> None:
         """Create necessary directories if they don't exist."""
@@ -163,7 +175,6 @@ class StateManager:
                 "dedup_days": 14
             },
             "progress": {
-                "total_points": 0,
                 "total_quizzes": 0,
                 "correct_rate": 0.0,
                 "last_study_date": None,
@@ -195,26 +206,13 @@ class StateManager:
             return self._default_state()
 
     def _merge_with_defaults(self, state: Dict[str, Any]) -> Dict[str, Any]:
-        """Merge loaded state with defaults to ensure all fields exist."""
-        defaults = self._default_state()
-        merged = defaults.copy()
-
-        # Handle top-level boolean/integer fields
-        for key in ['initialized', 'onboarding_step', 'version']:
-            if key in state:
-                merged[key] = state[key]
-
-        # Handle nested objects
-        for key in ['user', 'preferences', 'progress', 'completion_status', 'schedule']:
-            if key in state and isinstance(state[key], dict):
-                merged[key] = {**defaults.get(key, {}), **state[key]}
-
-        # Handle arrays
-        for key in ['recent_topics', 'error_notebook', 'error_archive']:
-            if key in state:
-                merged[key] = state[key]
+        """
+        Merge loaded state with defaults to ensure all fields exist.
 
-        return merged
+        Uses deep merge to handle nested structures properly.
+        """
+        defaults = self._default_state()
+        return deep_merge(defaults, state)
 
     def save_state(self, state: Dict[str, Any]) -> None:
         """
@@ -289,7 +287,8 @@ class StateManager:
         return daily_path
 
     def save_daily_content(self, content_type: str, content: Dict[str, Any],
-                           target_date: Optional[date] = None) -> Path:
+                           target_date: Optional[date] = None,
+                           generate_audio: bool = True) -> Path:
         """
         Save content to the daily directory.
 
@@ -297,6 +296,7 @@ class StateManager:
             content_type: Type of content ('keypoint', 'quiz', 'user_answers')
             content: Content dictionary to save
             target_date: Date for the content (defaults to today)
+            generate_audio: Whether to auto-generate audio for keypoints (default True)
 
         Returns:
             Path to the saved file
@@ -312,8 +312,95 @@ class StateManager:
         with open(file_path, 'w', encoding='utf-8') as f:
             json.dump(content, f, ensure_ascii=False, indent=2)
 
+        # Auto-generate audio for keypoints
+        if content_type == 'keypoint' and generate_audio:
+            try:
+                audio_result = self.generate_keypoint_audio(target_date)
+                if audio_result.get('success'):
+                    # Update keypoint with audio metadata
+                    content['audio'] = {
+                        'composed': audio_result.get('audio_path'),
+                        'duration_seconds': audio_result.get('duration_seconds'),
+                        'generated_at': datetime.now().isoformat()
+                    }
+                    # Re-save with audio info
+                    with open(file_path, 'w', encoding='utf-8') as f:
+                        json.dump(content, f, ensure_ascii=False, indent=2)
+            except Exception as e:
+                print(f"Warning: Audio generation failed: {e}")
+
         return file_path
 
+    def generate_keypoint_audio(self, target_date: Optional[date] = None) -> Dict[str, Any]:
+        """
+        Generate composed audio for a keypoint.
+
+        Args:
+            target_date: Date for the keypoint (defaults to today)
+
+        Returns:
+            Dictionary with:
+                - success: bool
+                - audio_path: str (relative path from data_dir)
+                - duration_seconds: float
+                - error_message: str (if failed)
+        """
+        try:
+            from .audio_composer import AudioComposer
+            from .tts import TTSManager
+        except ImportError:
+            from audio_composer import AudioComposer
+            from tts import TTSManager
+
+        if target_date is None:
+            target_date = date.today()
+
+        # Load the keypoint
+        keypoint = self.load_daily_content('keypoint', target_date)
+        if not keypoint:
+            return {
+                'success': False,
+                'error_message': f'No keypoint found for {target_date}'
+            }
+
+        # Prepare output path
+        date_str = target_date.strftime('%Y-%m-%d')
+        self.audio_dir.mkdir(parents=True, exist_ok=True)
+        output_path = self.audio_dir / date_str / "keypoint_full.mp3"
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            # Initialize TTS and composer (handle both package and direct imports)
+            try:
+                from .audio_composer import AudioComposer
+                from .tts import TTSManager
+            except ImportError:
+                from audio_composer import AudioComposer
+                from tts import TTSManager
+
+            tts = TTSManager.from_env()
+            composer = AudioComposer(tts)
+
+            # Compose audio
+            result = composer.compose_keypoint_audio(keypoint, output_path)
+
+            if result.success:
+                return {
+                    'success': True,
+                    'audio_path': f"audio/{date_str}/keypoint_full.mp3",
+                    'duration_seconds': result.duration_seconds
+                }
+            else:
+                return {
+                    'success': False,
+                    'error_message': result.error_message
+                }
+        except Exception as e:
+            return {
+                'success': False,
+                'error_message': str(e)
+            }
+
     def load_daily_content(self, content_type: str,
                            target_date: Optional[date] = None) -> Optional[Dict[str, Any]]:
         """
@@ -375,6 +462,9 @@ class StateManager:
         recent_content = self.get_recent_daily_content(days)
         return [c.get('topic_fingerprint', '') for c in recent_content if c.get('topic_fingerprint')]
 
+    # Maximum size for error notebook before auto-archiving
+    MAX_ERROR_NOTEBOOK_SIZE = 100
+
     def add_to_error_notebook(self, state: Dict[str, Any],
                                error: Dict[str, Any]) -> Dict[str, Any]:
         """
@@ -391,7 +481,23 @@ class StateManager:
         error['reviewed'] = False
         error['wrong_count'] = error.get('wrong_count', 1)
         # keypoint_date and question_type are optional
-        state['error_notebook'].append(error)
+
+        errors = state.get('error_notebook', [])
+        errors.append(error)
+
+        # Auto-archive oldest if over size limit
+        if len(errors) > self.MAX_ERROR_NOTEBOOK_SIZE:
+            # Sort by date to find oldest
+            errors.sort(key=lambda x: x.get('date', ''))
+            # Archive the oldest
+            oldest = errors.pop(0)
+            archive = state.get('error_archive', [])
+            oldest['archived_at'] = date.today().isoformat()
+            oldest['archived_reason'] = 'notebook_full'
+            archive.append(oldest)
+            state['error_archive'] = archive
+
+        state['error_notebook'] = errors
         return state
 
     def get_errors_page(self, state: Dict[str, Any],
@@ -837,189 +943,7 @@ class StateManager:
             return False
 
 
-# CLI interface
+# CLI interface - delegated to cli.py for better code organization
 if __name__ == "__main__":
-    import argparse
-
-    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}")
+    from cli import main
+    main()