@rookiestar/eng-lang-tutor 1.0.1

package/scripts/eng-lang-tutor

@@ -0,0 +1,16 @@
+#!/bin/bash
+# eng-lang-tutor wrapper script
+# Automatically uses venv Python if available, falls back to system Python
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VENV_PYTHON="$HOME/.venvs/eng-lang-tutor/bin/python"
+
+# Prefer venv Python if it exists
+if [ -x "$VENV_PYTHON" ]; then
+    PYTHON="$VENV_PYTHON"
+else
+    PYTHON="python3"
+fi
+
+# Run the CLI with all arguments
+exec "$PYTHON" "$SCRIPT_DIR/cli.py" "$@"

package/scripts/scheduling/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python3
+"""Scheduling: cron-triggered content push."""
+
+from .cron_push import CronPusher
+
+__all__ = ['CronPusher']

package/scripts/scheduling/cron_push.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+Cron Push - Handles scheduled content generation and notifications.
+
+This script is called by cron to:
+1. Generate and push daily keypoints
+2. Generate and push daily quizzes
+
+Usage:
+    python3 cron_push.py --task keypoint
+    python3 cron_push.py --task quiz
+    python3 cron_push.py --task status
+"""
+
+import argparse
+import json
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+# Import local modules
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+try:
+    from scripts.core.state_manager import StateManager
+except ImportError:
+    from core.state_manager import StateManager
+
+
+class CronPusher:
+    """Handles scheduled content push operations."""
+
+    def __init__(self, data_dir: str = "data"):
+        """
+        Initialize the cron pusher.
+
+        Args:
+            data_dir: Path to the data directory
+        """
+        self.state_manager = StateManager(data_dir)
+        self.today = date.today()
+
+    def push_keypoint(self) -> Dict[str, Any]:
+        """
+        Generate and save today's knowledge point.
+
+        Returns:
+            Result dictionary with status and content
+        """
+        # Check if already exists
+        existing = self.state_manager.load_daily_content('keypoint', self.today)
+        if existing:
+            return {
+                "status": "exists",
+                "message": f"Keypoint for {self.today} already exists",
+                "keypoint": existing
+            }
+
+        # Load state
+        state = self.state_manager.load_state()
+        self.state_manager.save_state(state)
+
+        # Generate keypoint (placeholder - actual LLM generation happens in Agent)
+        keypoint = {
+            "date": self.today.isoformat(),
+            "topic_fingerprint": f"auto_{self.today.isoformat()}",
+            "category": "oral",
+            "scene": {
+                "context": "Auto-generated placeholder",
+                "formality": "casual"
+            },
+            "expressions": [],
+            "alternatives": [],
+            "chinglish_trap": {},
+            "examples": [],
+            "generated": False,
+            "needs_generation": True
+        }
+
+        # Save and log
+        self.state_manager.save_daily_content('keypoint', keypoint, self.today)
+        self.state_manager.append_event('keypoint_pushed', {
+            "date": self.today.isoformat(),
+            "fingerprint": keypoint.get("topic_fingerprint")
+        })
+
+        # Update state
+        state = self.state_manager.load_state()
+        state['recent_topics'].append(keypoint.get("topic_fingerprint"))
+        # Keep only last 50 topics
+        state['recent_topics'] = state['recent_topics'][-50:]
+
+        # Record view for this keypoint
+        state = self.state_manager.record_keypoint_view(state, self.today)
+
+        self.state_manager.save_state(state)
+
+        return {
+            "status": "created",
+            "message": f"Keypoint for {self.today} created (needs generation)",
+            "keypoint": keypoint
+        }
+
+    def push_quiz(self) -> Dict[str, Any]:
+        """
+        Generate and save today's quiz.
+
+        Returns:
+            Result dictionary with status and content
+        """
+        # Check if already exists
+        existing = self.state_manager.load_daily_content('quiz', self.today)
+        if existing:
+            return {
+                "status": "exists",
+                "message": f"Quiz for {self.today} already exists",
+                "quiz": existing
+            }
+
+        # Load state
+        state = self.state_manager.load_state()
+        self.state_manager.save_state(state)
+
+        # Load today's keypoint
+        keypoint = self.state_manager.load_daily_content('keypoint', self.today)
+        if not keypoint:
+            # Need to create keypoint first
+            keypoint_result = self.push_keypoint()
+            keypoint = keypoint_result.get("keypoint")
+
+        # Generate quiz (placeholder - actual LLM generation happens in Agent)
+        quiz = {
+            "quiz_date": self.today.isoformat(),
+            "keypoint_fingerprint": keypoint.get("topic_fingerprint") if keypoint else None,
+            "questions": [],
+            "total_xp": 0,
+            "passing_score": 70,
+            "generated": False,
+            "needs_generation": True
+        }
+
+        # Save and log
+        self.state_manager.save_daily_content('quiz', quiz, self.today)
+        self.state_manager.append_event('quiz_pushed', {
+            "date": self.today.isoformat()
+        })
+
+        return {
+            "status": "created",
+            "message": f"Quiz for {self.today} created (needs generation)",
+            "quiz": quiz
+        }
+
+    def reset_daily_flags(self) -> Dict[str, Any]:
+        """
+        Reset daily completion flags (called at midnight).
+
+        Returns:
+            Result dictionary with status
+        """
+        state = self.state_manager.load_state()
+
+        # Reset quiz completion flag for new day
+        if "completion_status" in state:
+            # Keep the date, just let the new day's check handle it
+            pass
+
+        self.state_manager.save_state(state)
+
+        return {
+            "status": "success",
+            "message": f"Daily flags reset for {self.today}"
+        }
+
+    def get_status(self) -> Dict[str, Any]:
+        """
+        Get current status of today's content.
+
+        Returns:
+            Status dictionary
+        """
+        state = self.state_manager.load_state()
+
+        keypoint = self.state_manager.load_daily_content('keypoint', self.today)
+        quiz = self.state_manager.load_daily_content('quiz', self.today)
+
+        return {
+            "date": self.today.isoformat(),
+            "initialized": state.get("initialized", False),
+            "keypoint_exists": keypoint is not None,
+            "quiz_exists": quiz is not None,
+            "can_take_quiz": self.state_manager.can_take_quiz(state),
+            "user_xp": state.get("user", {}).get("xp", 0),
+            "user_streak": state.get("user", {}).get("streak", 0)
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Cron Push for eng-lang-tutor")
+    parser.add_argument('--task', required=True,
+                        choices=['keypoint', 'quiz', 'reset_daily', 'status'],
+                        help='Task to execute')
+    parser.add_argument('--data-dir', default='data', help='Data directory path')
+    parser.add_argument('--json', action='store_true', help='Output as JSON only')
+
+    args = parser.parse_args()
+
+    pusher = CronPusher(args.data_dir)
+
+    if args.task == 'keypoint':
+        result = pusher.push_keypoint()
+    elif args.task == 'quiz':
+        result = pusher.push_quiz()
+    elif args.task == 'reset_daily':
+        result = pusher.reset_daily_flags()
+    elif args.task == 'status':
+        result = pusher.get_status()
+
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"[{datetime.now().isoformat()}] Task: {args.task}")
+        print(f"Status: {result.get('status')}")
+        print(f"Message: {result.get('message')}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/utils/__init__.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Utilities: helper functions and deduplication."""
+
+from .helpers import safe_divide, deep_merge, clamp
+from .dedup import DeduplicationManager
+
+__all__ = [
+    'safe_divide',
+    'deep_merge',
+    'clamp',
+    'DeduplicationManager',
+]

package/scripts/utils/dedup.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""
+Deduplication - Prevents repeated content within 14-day window for eng-lang-tutor.
+
+Methods:
+1. Topic fingerprint matching
+2. Expression similarity check
+3. Phrase root matching
+"""
+
+from typing import Dict, Any, List, Set, Optional, Tuple
+from datetime import datetime, timedelta
+import re
+
+
+class DeduplicationManager:
+    """Manages content deduplication to avoid repetitive learning."""
+
+    def __init__(self, lookback_days: int = 14):
+        """
+        Initialize the deduplication manager.
+
+        Args:
+            lookback_days: Number of days to look back for duplicates
+        """
+        self.lookback_days = lookback_days
+
+    def get_excluded_topics(self, state: Dict[str, Any]) -> List[str]:
+        """
+        Get topic fingerprints from recent days.
+
+        Args:
+            state: Current state with recent_topics
+
+        Returns:
+            List of topic fingerprints to exclude
+        """
+        recent = state.get('recent_topics', [])
+        # Return last 50 topics (or all if fewer)
+        return recent[-50:] if len(recent) > 50 else recent
+
+    def check_duplicate(
+        self,
+        new_content: Dict[str, Any],
+        recent_content: List[Dict[str, Any]]
+    ) -> Tuple[bool, str]:
+        """
+        Check if new content duplicates recent content.
+
+        Args:
+            new_content: New knowledge point to check
+            recent_content: List of recent knowledge points
+
+        Returns:
+            Tuple of (is_duplicate, reason)
+        """
+        new_fingerprint = new_content.get('topic_fingerprint', '')
+
+        # Check fingerprint match
+        for old in recent_content:
+            if old.get('topic_fingerprint') == new_fingerprint:
+                return (True, f"Topic fingerprint matches: {new_fingerprint}")
+
+        # Check expression overlap
+        new_expressions = self._extract_expressions(new_content)
+        for old in recent_content:
+            old_expressions = self._extract_expressions(old)
+            overlap = new_expressions & old_expressions
+
+            # If more than 50% overlap, consider it duplicate
+            if len(overlap) > 0:
+                overlap_ratio = len(overlap) / max(len(new_expressions), 1)
+                if overlap_ratio > 0.5:
+                    return (True, f"Expression overlap: {overlap}")
+
+        # Check phrase root similarity
+        new_roots = self._extract_phrase_roots(new_content)
+        for old in recent_content:
+            old_roots = self._extract_phrase_roots(old)
+            root_overlap = new_roots & old_roots
+
+            if len(root_overlap) >= 2:
+                return (True, f"Phrase root overlap: {root_overlap}")
+
+        return (False, "")
+
+    def _extract_expressions(self, content: Dict[str, Any]) -> Set[str]:
+        """
+        Extract normalized expressions from content.
+
+        Args:
+            content: Knowledge point content
+
+        Returns:
+            Set of normalized expression strings
+        """
+        expressions = set()
+
+        # Main expressions
+        for expr in content.get('expressions', []):
+            phrase = expr.get('phrase', '').lower().strip()
+            # Normalize: remove punctuation, collapse whitespace
+            normalized = re.sub(r'[^\w\s]', '', phrase)
+            normalized = ' '.join(normalized.split())
+            if normalized:
+                expressions.add(normalized)
+
+        # Alternatives
+        for alt in content.get('alternatives', []):
+            normalized = re.sub(r'[^\w\s]', '', alt.lower())
+            normalized = ' '.join(normalized.split())
+            if normalized:
+                expressions.add(normalized)
+
+        return expressions
+
+    def _extract_phrase_roots(self, content: Dict[str, Any]) -> Set[str]:
+        """
+        Extract phrase roots/concepts from content.
+
+        Args:
+            content: Knowledge point content
+
+        Returns:
+            Set of phrase root strings
+        """
+        roots = set()
+
+        # From fingerprint
+        fingerprint = content.get('topic_fingerprint', '')
+        if fingerprint:
+            # Split by underscore and get key concepts
+            parts = fingerprint.split('_')
+            for part in parts:
+                if len(part) > 3:  # Skip short words
+                    roots.add(part)
+
+        # From expressions (first significant word)
+        for expr in content.get('expressions', []):
+            phrase = expr.get('phrase', '').lower()
+            words = phrase.split()
+            for word in words:
+                # Skip common words
+                if word not in ['the', 'a', 'an', 'to', 'for', 'and', 'or', 'is', 'are']:
+                    if len(word) > 3:
+                        roots.add(word)
+                        break
+
+        return roots
+
+    def add_to_recent_topics(self, state: Dict[str, Any],
+                              fingerprint: str) -> Dict[str, Any]:
+        """
+        Add a topic fingerprint to recent topics list.
+
+        Args:
+            state: Current state
+            fingerprint: Topic fingerprint to add
+
+        Returns:
+            Updated state
+        """
+        recent = state.get('recent_topics', [])
+        recent.append(fingerprint)
+
+        # Keep only last 50
+        state['recent_topics'] = recent[-50:]
+        return state
+
+    def generate_excluded_list_prompt(self, excluded_topics: List[str]) -> str:
+        """
+        Generate a prompt-friendly list of excluded topics.
+
+        Args:
+            excluded_topics: List of topic fingerprints
+
+        Returns:
+            Formatted string for LLM prompt
+        """
+        if not excluded_topics:
+            return "None (first content or no recent topics)"
+
+        # Group by prefix (e.g., "asking_", "workplace_")
+        grouped = {}
+        for topic in excluded_topics:
+            parts = topic.split('_')
+            if len(parts) > 1:
+                prefix = parts[0]
+            else:
+                prefix = 'other'
+
+            if prefix not in grouped:
+                grouped[prefix] = []
+            grouped[prefix].append(topic)
+
+        lines = []
+        for prefix, topics in sorted(grouped.items()):
+            lines.append(f"- {prefix}: {', '.join(topics[:3])}{'...' if len(topics) > 3 else ''}")
+
+        return '\n'.join(lines)
+
+    def suggest_alternative_topic(
+        self,
+        excluded_topics: List[str],
+        available_topics: List[str]
+    ) -> Optional[str]:
+        """
+        Suggest an alternative topic that hasn't been used recently.
+
+        TODO: This function is defined but not currently used in production code.
+        Could be integrated with LLM generation to suggest topics when duplicates detected.
+
+        Args:
+            excluded_topics: Topics to avoid
+            available_topics: All available topics
+
+        Returns:
+            A topic not in excluded list, or None if all exhausted
+        """
+        excluded_set = set(excluded_topics)
+
+        for topic in available_topics:
+            if topic not in excluded_set:
+                return topic
+
+        return None
+
+    def get_content_diversity_score(
+        self,
+        recent_content: List[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """
+        Calculate content diversity metrics.
+
+        TODO: This function is defined but not currently used in production code.
+        Could be used for analytics dashboard or adaptive content generation.
+
+        Args:
+            recent_content: List of recent content
+
+        Returns:
+            Dictionary with diversity metrics
+        """
+        if not recent_content:
+            return {
+                'total_content': 0,
+                'unique_topics': 0,
+                'topic_diversity': 1.0,
+                'category_distribution': {}
+            }
+
+        topics = set()
+        categories = {'oral': 0, 'written': 0}
+        topic_themes = {}
+
+        for content in recent_content:
+            fingerprint = content.get('topic_fingerprint', '')
+            if fingerprint:
+                topics.add(fingerprint)
+                # Extract theme
+                theme = fingerprint.split('_')[0] if '_' in fingerprint else fingerprint
+                topic_themes[theme] = topic_themes.get(theme, 0) + 1
+
+            category = content.get('category', 'oral')
+            categories[category] = categories.get(category, 0) + 1
+
+        total = len(recent_content)
+        unique = len(topics)
+
+        return {
+            'total_content': total,
+            'unique_topics': unique,
+            'topic_diversity': unique / total if total > 0 else 1.0,
+            'category_distribution': categories,
+            'theme_distribution': topic_themes
+        }
+
+
+# CLI interface for testing
+if __name__ == "__main__":
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(description="Deduplication for eng-lang-tutor")
+    parser.add_argument('--demo', action='store_true', help='Run demo')
+
+    args = parser.parse_args()
+
+    dm = DeduplicationManager()
+
+    if args.demo:
+        # Simulate recent content
+        recent = [
+            {
+                "topic_fingerprint": "asking_favor_casual",
+                "category": "oral",
+                "expressions": [{"phrase": "Can you do me a favor?"}]
+            },
+            {
+                "topic_fingerprint": "workplace_meeting",
+                "category": "oral",
+                "expressions": [{"phrase": "Let's circle back"}]
+            },
+            {
+                "topic_fingerprint": "gaming_slang",
+                "category": "oral",
+                "expressions": [{"phrase": "GG, that was clutch"}]
+            }
+        ]
+
+        # Test duplicate detection
+        new_content = {
+            "topic_fingerprint": "asking_favor_formal",
+            "category": "oral",
+            "expressions": [{"phrase": "Could you help me out?"}]
+        }
+
+        is_dup, reason = dm.check_duplicate(new_content, recent)
+        print(f"Is duplicate: {is_dup}")
+        print(f"Reason: {reason}")
+
+        # Test diversity score
+        print("\n=== Diversity Score ===")
+        score = dm.get_content_diversity_score(recent)
+        print(json.dumps(score, indent=2))
+
+        # Test excluded list prompt
+        print("\n=== Excluded Topics (for LLM prompt) ===")
+        excluded = ['asking_favor_casual', 'workplace_meeting', 'gaming_slang',
+                    'social_greeting', 'news_vocabulary']
+        print(dm.generate_excluded_list_prompt(excluded))

package/scripts/utils/helpers.py

@@ -0,0 +1,82 @@
+#!/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.
+
+    Reserved for future use in XP/ratio calculations.
+
+    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
+    """  # noqa: DOC501 - Reserved for future use
+    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.
+
+    Reserved for future use in streak multiplier capping or level calculations.
+
+    Args:
+        value: Value to clamp
+        min_val: Minimum allowed value
+        max_val: Maximum allowed value
+
+    Returns:
+        Value clamped to [min_val, max_val]
+    """  # noqa: DOC501 - Reserved for future use
+    return max(min_val, min(max_val, value))