@rookiestar/eng-lang-tutor 1.0.2 → 1.0.3

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:
         """
@@ -375,6 +373,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 +392,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 +854,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()

package/scripts/utils.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""
+Utility functions for eng-lang-tutor.
+
+Common utilities used across multiple modules.
+"""
+
+from typing import Dict, Any
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+    """
+    Safe division that returns default if denominator is zero.
+
+    Args:
+        numerator: The number to divide
+        denominator: The number to divide by
+        default: Value to return if denominator is zero
+
+    Returns:
+        Result of division, or default if denominator is zero
+
+    Examples:
+        >>> safe_divide(10, 2)
+        5.0
+        >>> safe_divide(10, 0)
+        0.0
+        >>> safe_divide(10, 0, default=100)
+        100.0
+    """
+    return numerator / denominator if denominator != 0 else default
+
+
+def deep_merge(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Recursively merge override dictionary into base dictionary.
+
+    Creates a new dictionary with values from base, updated with values from override.
+    Nested dictionaries are merged recursively; other values are overwritten.
+
+    Args:
+        base: Base dictionary (not modified)
+        override: Dictionary with values to override/add
+
+    Returns:
+        New merged dictionary
+
+    Examples:
+        >>> base = {'a': 1, 'b': {'c': 2, 'd': 3}}
+        >>> override = {'b': {'c': 10}}
+        >>> deep_merge(base, override)
+        {'a': 1, 'b': {'c': 10, 'd': 3}}
+    """
+    import copy
+    result = copy.deepcopy(base)
+
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = copy.deepcopy(value)
+
+    return result
+
+
+def clamp(value: float, min_val: float, max_val: float) -> float:
+    """
+    Clamp a value to a range.
+
+    Args:
+        value: Value to clamp
+        min_val: Minimum allowed value
+        max_val: Maximum allowed value
+
+    Returns:
+        Value clamped to [min_val, max_val]
+    """
+    return max(min_val, min(max_val, value))