Upload app/agents/recall_agent.py with huggingface_hub

app/agents/recall_agent.py

@@ -0,0 +1,293 @@
+"""
+Recall Agent - Spaced Repetition with SM-2 Algorithm
+
+Manages spaced repetition reviews using the SM-2 algorithm:
+- Calculates optimal review intervals
+- Tracks mastery levels
+- Schedules reviews
+"""
+
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+import math
+
+
+@dataclass
+class RecallCard:
+    """A card for spaced repetition review"""
+    card_id: str
+    front: str
+    back: str
+    topic: str
+    ease_factor: float = 2.5
+    interval: int = 1
+    repetitions: int = 0
+    next_review: datetime = field(default_factory=datetime.now)
+    last_review: Optional[datetime] = None
+    quality_history: List[int] = field(default_factory=list)
+
+
+@dataclass
+class ReviewResult:
+    """Result of a review session"""
+    card_id: str
+    quality: int
+    new_ease_factor: float
+    new_interval: int
+    new_repetitions: int
+    next_review: datetime
+    xp_earned: int
+
+
+class RecallAgent:
+    """
+    Spaced repetition agent using SM-2 algorithm.
+    
+    SM-2 Algorithm:
+    - Quality: 0-5 (0-2 = fail, 3 = hard, 4 = good, 5 = easy)
+    - Ease Factor: starts at 2.5, adjusted after each review
+    - Interval: starts at 1 day, multiplied by EF each success
+    """
+    
+    def __init__(self, user_id: str, config: Optional[Dict] = None):
+        self.user_id = user_id
+        self.config = config or {}
+        
+        self.cards: Dict[str, RecallCard] = {}
+        self.review_history: List[Dict] = []
+    
+    def create_card(
+        self, 
+        front: str, 
+        back: str, 
+        topic: str,
+        metadata: Optional[Dict] = None
+    ) -> RecallCard:
+        """Create a new recall card from a doubt"""
+        card_id = f"card_{datetime.now().timestamp()}"
+        
+        card = RecallCard(
+            card_id=card_id,
+            front=front,
+            back=back,
+            topic=topic
+        )
+        
+        self.cards[card_id] = card
+        return card
+    
+    def create_cards_from_doubt(self, doubt_data: Dict) -> List[RecallCard]:
+        """Create recall cards from a captured doubt"""
+        cards = []
+        
+        front = doubt_data.get('formattedTitle', doubt_data.get('rawText', ''))
+        back = doubt_data.get('formattedSummary', '')
+        topic = doubt_data.get('topic', 'General')
+        
+        card = self.create_card(front, back, topic, doubt_data)
+        cards.append(card)
+        
+        if doubt_data.get('conceptTags'):
+            for tag in doubt_data['conceptTags'][:2]:
+                tag_card = self.create_card(
+                    f"How does '{tag}' relate to '{topic}'?",
+                    f"{tag} is a key concept within {topic}...",
+                    topic
+                )
+                cards.append(tag_card)
+        
+        return cards
+    
+    async def get_due_recalls(self, topic: Optional[str] = None) -> List[RecallCard]:
+        """Get cards due for review"""
+        now = datetime.now()
+        due_cards = []
+        
+        for card in self.cards.values():
+            if topic and card.topic != topic:
+                continue
+            
+            if card.next_review <= now:
+                due_cards.append(card)
+        
+        due_cards.sort(key=lambda c: c.next_review)
+        return due_cards
+    
+    async def complete_review(
+        self, 
+        card_id: str, 
+        quality: int
+    ) -> Optional[ReviewResult]:
+        """
+        Complete a review using SM-2 algorithm.
+        
+        Quality ratings:
+        0 - Complete blackout
+        1 - Incorrect, but recognized answer
+        2 - Incorrect, but easy to recall
+        3 - Correct with difficulty
+        4 - Correct after hesitation
+        5 - Perfect recall
+        """
+        if card_id not in self.cards:
+            return None
+        
+        card = self.cards[card_id]
+        
+        card.last_review = datetime.now()
+        card.quality_history.append(quality)
+        
+        if quality < 3:
+            card.repetitions = 0
+            card.interval = 1
+        else:
+            if card.repetitions == 0:
+                card.interval = 1
+            elif card.repetitions == 1:
+                card.interval = 6
+            else:
+                card.interval = round(card.interval * card.ease_factor)
+            
+            card.repetitions += 1
+        
+        card.ease_factor = max(
+            1.3,
+            card.ease_factor + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02))
+        )
+        
+        card.next_review = datetime.now() + timedelta(days=card.interval)
+        
+        xp_earned = self._calculate_xp(quality)
+        
+        result = ReviewResult(
+            card_id=card_id,
+            quality=quality,
+            new_ease_factor=card.ease_factor,
+            new_interval=card.interval,
+            new_repetitions=card.repetitions,
+            next_review=card.next_review,
+            xp_earned=xp_earned
+        )
+        
+        self.review_history.append({
+            'card_id': card_id,
+            'quality': quality,
+            'timestamp': datetime.now().isoformat(),
+            'xp_earned': xp_earned
+        })
+        
+        return result
+    
+    def _calculate_xp(self, quality: int) -> int:
+        """Calculate XP earned for review quality"""
+        xp_map = {0: 1, 1: 2, 2: 3, 3: 5, 4: 10, 5: 15}
+        return xp_map.get(quality, 1)
+    
+    def get_review_stats(self) -> Dict:
+        """Get review statistics"""
+        now = datetime.now()
+        
+        total_cards = len(self.cards)
+        due_cards = sum(1 for c in self.cards.values() if c.next_review <= now)
+        mastered_cards = sum(1 for c in self.cards.values() 
+                           if c.ease_factor > 2.5 and c.repetitions >= 5)
+        
+        total_reviews = len(self.review_history)
+        avg_quality = 0
+        if self.review_history:
+            avg_quality = sum(r['quality'] for r in self.review_history) / total_reviews
+        
+        return {
+            'total_cards': total_cards,
+            'due_today': due_cards,
+            'mastered': mastered_cards,
+            'total_reviews': total_reviews,
+            'average_quality': round(avg_quality, 2),
+            'total_xp': sum(r['xp_earned'] for r in self.review_history)
+        }
+    
+    def get_learning_progress(self) -> Dict:
+        """Get learning progress for dashboard"""
+        stats = self.get_review_stats()
+        
+        progress = {
+            'cards_created': stats['total_cards'],
+            'cards_mastered': stats['mastered'],
+            'mastery_percentage': (
+                stats['mastered'] / stats['total_cards'] * 100 
+                if stats['total_cards'] > 0 else 0
+            ),
+            'reviews_completed': stats['total_reviews'],
+            'due_today': stats['due_today'],
+            'topic_breakdown': self._get_topic_breakdown()
+        }
+        
+        return progress
+    
+    def _get_topic_breakdown(self) -> Dict[str, Dict]:
+        """Get breakdown by topic"""
+        topics = {}
+        
+        for card in self.cards.values():
+            if card.topic not in topics:
+                topics[card.topic] = {
+                    'total': 0,
+                    'due': 0,
+                    'mastered': 0,
+                    'avg_ease': 0
+                }
+            
+            topics[card.topic]['total'] += 1
+            
+            if card.next_review <= datetime.now():
+                topics[card.topic]['due'] += 1
+            
+            if card.ease_factor > 2.5 and card.repetitions >= 5:
+                topics[card.topic]['mastered'] += 1
+            
+            topics[card.topic]['avg_ease'] += card.ease_factor
+        
+        for topic in topics:
+            if topics[topic]['total'] > 0:
+                topics[topic]['avg_ease'] /= topics[topic]['total']
+        
+        return topics
+    
+    def export_cards(self) -> List[Dict]:
+        """Export all cards for backup"""
+        return [
+            {
+                'card_id': c.card_id,
+                'front': c.front,
+                'back': c.back,
+                'topic': c.topic,
+                'ease_factor': c.ease_factor,
+                'interval': c.interval,
+                'repetitions': c.repetitions,
+                'next_review': c.next_review.isoformat(),
+                'last_review': c.last_review.isoformat() if c.last_review else None,
+                'quality_history': c.quality_history
+            }
+            for c in self.cards.values()
+        ]
+    
+    def import_cards(self, cards_data: List[Dict]):
+        """Import cards from backup"""
+        for card_data in cards_data:
+            card = RecallCard(
+                card_id=card_data['card_id'],
+                front=card_data['front'],
+                back=card_data['back'],
+                topic=card_data['topic'],
+                ease_factor=card_data.get('ease_factor', 2.5),
+                interval=card_data.get('interval', 1),
+                repetitions=card_data.get('repetitions', 0),
+                next_review=datetime.fromisoformat(card_data['next_review']),
+                last_review=(
+                    datetime.fromisoformat(card_data['last_review']) 
+                    if card_data.get('last_review') else None
+                ),
+                quality_history=card_data.get('quality_history', [])
+            )
+            self.cards[card.card_id] = card