Create llm_explainer.py

utils/llm_explainer.py

@@ -0,0 +1,337 @@
+"""
+LLM-powered explanation generator for RewardPilot recommendations.
+Uses Hugging Face Inference API with Llama 3.2 for natural language explanations.
+"""
+
+from huggingface_hub import InferenceClient
+import os
+from typing import Dict, List, Optional
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class LLMExplainer:
+    """Generate natural language explanations for credit card recommendations using LLM"""
+    
+    def __init__(self, model: str = "meta-llama/Llama-3.2-3B-Instruct"):
+        """
+        Initialize LLM explainer with Hugging Face Inference API
+        
+        Args:
+            model: HuggingFace model ID to use for generation
+        """
+        self.model = model
+        self.client = None
+        
+        # Try to initialize with token
+        hf_token = os.getenv("HF_TOKEN", "")
+        if hf_token:
+            try:
+                self.client = InferenceClient(token=hf_token)
+                logger.info(f"✅ LLM Explainer initialized with model: {model}")
+            except Exception as e:
+                logger.warning(f"⚠️ Could not initialize HF client: {e}")
+                self.client = None
+        else:
+            logger.warning("⚠️ No HF_TOKEN found. LLM explanations will use fallback mode.")
+    
+    def explain_recommendation(
+        self,
+        card: str,
+        rewards: float,
+        rewards_rate: str,
+        merchant: str,
+        category: str,
+        amount: float,
+        warnings: Optional[List[str]] = None,
+        annual_potential: Optional[float] = None,
+        alternatives: Optional[List[Dict]] = None
+    ) -> str:
+        """
+        Generate natural language explanation for a card recommendation
+        
+        Args:
+            card: Recommended card name
+            rewards: Rewards earned for this transaction
+            rewards_rate: Rewards rate (e.g., "4x points")
+            merchant: Merchant name
+            category: Transaction category
+            amount: Transaction amount
+            warnings: List of warning messages
+            annual_potential: Annual rewards potential
+            alternatives: Alternative card options
+            
+        Returns:
+            Natural language explanation string
+        """
+        
+        # Fallback if LLM not available
+        if not self.client:
+            return self._generate_fallback_explanation(
+                card, rewards, rewards_rate, merchant, category, amount, warnings
+            )
+        
+        # Build context-aware prompt
+        prompt = self._build_prompt(
+            card, rewards, rewards_rate, merchant, category, amount,
+            warnings, annual_potential, alternatives
+        )
+        
+        try:
+            # Generate explanation using LLM
+            response = self.client.text_generation(
+                prompt,
+                model=self.model,
+                max_new_tokens=200,
+                temperature=0.7,
+                do_sample=True,
+                top_p=0.9,
+                repetition_penalty=1.1
+            )
+            
+            # Clean up response
+            explanation = response.strip()
+            
+            # Remove any prompt artifacts
+            if "Explanation:" in explanation:
+                explanation = explanation.split("Explanation:")[-1].strip()
+            
+            logger.info(f"✅ Generated LLM explanation for {card}")
+            return explanation
+            
+        except Exception as e:
+            logger.error(f"❌ LLM generation failed: {e}")
+            return self._generate_fallback_explanation(
+                card, rewards, rewards_rate, merchant, category, amount, warnings
+            )
+    
+    def _build_prompt(
+        self,
+        card: str,
+        rewards: float,
+        rewards_rate: str,
+        merchant: str,
+        category: str,
+        amount: float,
+        warnings: Optional[List[str]],
+        annual_potential: Optional[float],
+        alternatives: Optional[List[Dict]]
+    ) -> str:
+        """Build optimized prompt for LLM"""
+        
+        prompt = f"""You are a friendly credit card rewards expert. Explain why this card is recommended.
+
+Transaction Details:
+- Merchant: {merchant}
+- Category: {category}
+- Amount: ${amount:.2f}
+
+Recommendation:
+- Best Card: {card}
+- Rewards Earned: ${rewards:.2f} ({rewards_rate})
+"""
+        
+        if annual_potential:
+            prompt += f"- Annual Potential: ${annual_potential:.2f} in this category\n"
+        
+        if warnings:
+            prompt += f"- Important Warning: {warnings[0]}\n"
+        
+        if alternatives and len(alternatives) > 0:
+            alt_text = ", ".join([f"{alt['card']} (${alt['rewards']:.2f})" 
+                                  for alt in alternatives[:2]])
+            prompt += f"- Alternatives: {alt_text}\n"
+        
+        prompt += """
+Provide a friendly, concise explanation (2-3 sentences) that:
+1. Explains why this card is the best choice
+2. Highlights the key benefit
+3. Mentions any important warnings if present
+
+Keep it conversational and helpful. Don't repeat the numbers already shown."""
+        
+        return prompt
+    
+    def _generate_fallback_explanation(
+        self,
+        card: str,
+        rewards: float,
+        rewards_rate: str,
+        merchant: str,
+        category: str,
+        amount: float,
+        warnings: Optional[List[str]]
+    ) -> str:
+        """Generate rule-based explanation when LLM is unavailable"""
+        
+        explanation = f"The {card} is your best choice for this {category.lower()} purchase at {merchant}. "
+        explanation += f"You'll earn {rewards_rate}, which gives you the highest rewards rate among your cards. "
+        
+        if warnings:
+            explanation += f"⚠️ Note: {warnings[0]}"
+        else:
+            explanation += "This optimizes your rewards while staying within spending caps."
+        
+        return explanation
+    
+    def generate_spending_insights(
+        self,
+        user_id: str,
+        total_spending: float,
+        total_rewards: float,
+        optimization_score: int,
+        top_categories: List[Dict],
+        recommendations_count: int
+    ) -> str:
+        """
+        Generate personalized spending insights for analytics dashboard
+        
+        Args:
+            user_id: User identifier
+            total_spending: Total spending amount
+            total_rewards: Total rewards earned
+            optimization_score: Optimization score (0-100)
+            top_categories: List of top spending categories
+            recommendations_count: Number of optimized transactions
+            
+        Returns:
+            Personalized insights text
+        """
+        
+        if not self.client:
+            return self._generate_fallback_insights(
+                total_spending, total_rewards, optimization_score
+            )
+        
+        prompt = f"""You are a financial advisor analyzing credit card usage. Provide 2-3 personalized insights.
+
+User Spending Summary:
+- Total Spending: ${total_spending:.2f}
+- Total Rewards: ${total_rewards:.2f}
+- Optimization Score: {optimization_score}/100
+- Optimized Transactions: {recommendations_count}
+- Top Categories: {', '.join([cat['category'] for cat in top_categories[:3]])}
+
+Provide actionable insights about:
+1. Their optimization performance
+2. Opportunities to earn more rewards
+3. One specific tip to improve their score
+
+Be encouraging and specific. Keep it under 100 words."""
+        
+        try:
+            response = self.client.text_generation(
+                prompt,
+                model=self.model,
+                max_new_tokens=150,
+                temperature=0.8,
+                do_sample=True
+            )
+            
+            return response.strip()
+            
+        except Exception as e:
+            logger.error(f"❌ Insights generation failed: {e}")
+            return self._generate_fallback_insights(
+                total_spending, total_rewards, optimization_score
+            )
+    
+    def _generate_fallback_insights(
+        self,
+        total_spending: float,
+        total_rewards: float,
+        optimization_score: int
+    ) -> str:
+        """Generate rule-based insights when LLM unavailable"""
+        
+        rewards_rate = (total_rewards / total_spending * 100) if total_spending > 0 else 0
+        
+        insights = f"You're earning ${total_rewards:.2f} in rewards on ${total_spending:.2f} of spending "
+        insights += f"({rewards_rate:.1f}% effective rate). "
+        
+        if optimization_score >= 80:
+            insights += "Excellent optimization! You're maximizing your rewards effectively. "
+        elif optimization_score >= 60:
+            insights += "Good progress! Consider using our recommendations more consistently. "
+        else:
+            insights += "There's room for improvement. Follow our card suggestions to boost your rewards. "
+        
+        insights += "Keep tracking your spending to identify new optimization opportunities."
+        
+        return insights
+    
+    def chat_response(
+        self,
+        user_message: str,
+        user_context: Dict,
+        chat_history: List[tuple] = None
+    ) -> str:
+        """
+        Generate conversational response for chat interface
+        
+        Args:
+            user_message: User's question/message
+            user_context: User's spending data and card portfolio
+            chat_history: Previous conversation history
+            
+        Returns:
+            AI assistant response
+        """
+        
+        if not self.client:
+            return "I'm currently in fallback mode. Please ask specific questions about your cards or transactions."
+        
+        # Build context from user data
+        context = f"""User Profile:
+- Cards: {', '.join(user_context.get('cards', ['Unknown']))}
+- Monthly Spending: ${user_context.get('monthly_spending', 0):.2f}
+- Top Category: {user_context.get('top_category', 'Unknown')}
+"""
+        
+        # Add chat history for context
+        history_text = ""
+        if chat_history:
+            recent_history = chat_history[-3:]  # Last 3 exchanges
+            history_text = "\n".join([
+                f"User: {user}\nAssistant: {assistant}"
+                for user, assistant in recent_history
+            ])
+        
+        prompt = f"""You are RewardPilot AI, a helpful credit card rewards assistant.
+
+{context}
+
+Previous Conversation:
+{history_text if history_text else "None"}
+
+User Question: {user_message}
+
+Provide a helpful, concise response (2-3 sentences). Be friendly and specific."""
+        
+        try:
+            response = self.client.text_generation(
+                prompt,
+                model=self.model,
+                max_new_tokens=150,
+                temperature=0.8,
+                do_sample=True
+            )
+            
+            return response.strip()
+            
+        except Exception as e:
+            logger.error(f"❌ Chat response failed: {e}")
+            return "I'm having trouble generating a response. Please try rephrasing your question."
+
+
+# Singleton instance
+_llm_explainer = None
+
+def get_llm_explainer() -> LLMExplainer:
+    """Get or create singleton LLM explainer instance"""
+    global _llm_explainer
+    if _llm_explainer is None:
+        _llm_explainer = LLMExplainer()
+    return _llm_explainer