Initial commit: LLM Evaluation Dashboard

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.env
+.venv
+venv/
+ENV/

README.md

@@ -0,0 +1,202 @@
+# LLM Evaluation Metrics Dashboard
+
+[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://huggingface.co/spaces/your-username/llm-evaluation-dashboard)
+
+A comprehensive **educational dashboard** demonstrating 5 key NLP evaluation metrics with interactive visualizations and mathematical explanations.
+
+![Dashboard Preview](https://via.placeholder.com/800x400.png?text=LLM+Evaluation+Dashboard+Preview)
+
+## 🎯 Features
+
+### 5 Complete Metric Implementations
+
+| Metric | Focus | Use Case |
+|--------|-------|----------|
+| **BLEU** | N-gram Precision | Machine Translation |
+| **ROGUE** | N-gram Recall (5 variants) | Text Summarization |
+| **Perplexity** | Model Confidence | Language Modeling |
+| **MRR** | Ranking Quality | Question Answering |
+| **BERT Score** | Semantic Similarity | Paraphrase Detection |
+
+### Interactive Visualizations
+
+- 📊 **Radar charts** for multi-metric comparison
+- 📈 **Bar charts** for precision/recall breakdown
+- 🔥 **Heatmaps** for token-level similarity
+- 🎚️ **Gauge charts** for score visualization
+- 📝 **Step-by-step** calculation breakdowns
+
+### Educational Focus
+
+- 🧮 **Mathematical formulas** with LaTeX rendering
+- 🔍 **N-gram matching** visualizations
+- 🎓 **Preset examples** for quick learning
+- 💡 **Quality interpretations** for each score
+
+## 🚀 Quick Start
+
+### Local Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/llm-evaluation-dashboard.git
+cd llm-evaluation-dashboard
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Download NLTK data
+python -c "import nltk; nltk.download('punkt')"
+
+# Run the app
+streamlit run app.py
+```
+
+### Online Demo
+
+Visit the live demo: [HuggingFace Spaces](https://huggingface.co/spaces/your-username/llm-evaluation-dashboard)
+
+## 📁 Project Structure
+
+```
+llm-evaluation-dashboard/
+├── app.py                          # Main entry point
+├── pages/
+│   ├── 01_overview.py              # All metrics comparison
+│   ├── 02_bleu_score.py            # BLEU with n-gram viz
+│   ├── 03_rogue_score.py           # 5 ROGUE variants
+│   ├── 04_perplexity.py            # Token-level perplexity
+│   ├── 05_mrr.py                   # Ranking evaluation
+│   └── 06_bert_score.py            # Semantic similarity
+├── modules/
+│   ├── metrics/                    # Metric implementations
+│   │   ├── bleu.py
+│   │   ├── rogue.py
+│   │   ├── perplexity.py
+│   │   ├── mrr.py
+│   │   └── bert_score.py
+│   ├── visualizations/             # Plotly charts
+│   │   ├── charts.py
+│   │   └── explanations.py
+│   └── utils/                      # Helpers
+│       ├── text_processing.py
+│       └── examples.py
+├── data/
+│   └── sample_evaluations.json     # Test cases
+├── requirements.txt
+└── README.md
+```
+
+## 🎓 Learning Resources
+
+### BLEU Score
+- Bilingual Evaluation Understudy
+- N-gram precision (1-4 grams)
+- Brevity penalty for short outputs
+- Best for: Machine translation
+
+### ROGUE Score (5 Variants)
+- **ROGUE-N**: Unigram/bigram overlap
+- **ROGUE-L**: Longest Common Subsequence
+- **ROGUE-S**: Skip-bigram matching
+- **ROGUE-SU**: Skip + Unigram combined
+- **ROGUE-W**: Weighted consecutive matches
+- Best for: Text summarization
+
+### Perplexity
+- Model confidence metric
+- Lower = more confident
+- No reference needed
+- Best for: Language model evaluation
+
+### MRR (Mean Reciprocal Rank)
+- Ranking quality metric
+- 1/rank_of_correct_answer
+- Batch evaluation support
+- Best for: Question answering / IR
+
+### BERT Score
+- Contextual embedding similarity
+- Semantic vs lexical matching
+- Token-level alignment
+- Best for: Paraphrase detection
+
+## 💻 Usage Examples
+
+### Compare Two Translations
+
+1. Go to **Overview** page
+2. Paste reference translation
+3. Paste candidate translation
+4. Click "Compare All Metrics"
+5. See radar chart showing BLEU, ROGUE, and BERT Score
+
+### Evaluate Summarization Quality
+
+1. Go to **ROGUE Score** page
+2. Select "ROGUE-L" variant
+3. Enter original article as reference
+4. Enter summary as candidate
+5. Check LCS (Longest Common Subsequence) visualization
+
+### Test Question Answering
+
+1. Go to **MRR** page
+2. Enter question and correct answer
+3. Enter ranked model outputs
+4. See reciprocal rank calculation
+
+## 🛠️ Tech Stack
+
+- **Framework**: Streamlit
+- **Visualizations**: Plotly, Matplotlib
+- **NLP**: NLTK
+- **Metrics**: rouge-score, bert-score, sentence-transformers
+- **Math**: NumPy, Pandas
+
+## 📝 Implementation Notes
+
+### Educational Simplifications
+
+- **Perplexity**: Uses probability simulation (real calculation requires model logprobs)
+- **BERT Score**: Uses simplified embeddings (install sentence-transformers for full BERT)
+- **Tokenization**: Simple word-based (no subword tokenization)
+
+### For Production Use
+
+Consider these libraries for production:
+```python
+# Official implementations
+from nltk.translate.bleu_score import sentence_bleu
+from rouge_score import rouge_scorer
+from bert_score import score as bert_score
+from evaluate import load as load_metric
+```
+
+## 🤝 Contributing
+
+Contributions welcome! Areas for improvement:
+- Add more evaluation metrics (METEOR, chrF, etc.)
+- Implement real LLM API integration for perplexity
+- Add multilingual support
+- Create video tutorials
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🙏 Acknowledgments
+
+- Inspired by academic papers on NLG evaluation
+- Built with Streamlit community best practices
+- Icons from [Twemoji](https://twemoji.twitter.com/)
+
+## 📧 Contact
+
+For questions or feedback:
+- Open an issue on GitHub
+- Email: your-email@example.com
+
+---
+
+**Star ⭐ this repo if you found it helpful!**

app.py

@@ -0,0 +1,59 @@
+"""LLM Evaluation Metrics Dashboard
+
+A comprehensive educational dashboard demonstrating 5 key NLP evaluation metrics:
+- BLEU Score (n-gram precision with brevity penalty)
+- ROGUE Score (recall-oriented with 5 variants)
+- Perplexity (model confidence measurement)
+- Mean Reciprocal Rank (ranking evaluation)
+- BERT Score (semantic similarity via embeddings)
+"""
+
+import streamlit as st
+
+st.set_page_config(
+    page_title="LLM Evaluation Dashboard",
+    page_icon="📊",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+st.title("📊 LLM Evaluation Metrics Dashboard")
+
+st.markdown("""
+## Welcome!
+
+This dashboard provides **interactive visualizations** of 5 essential NLP evaluation metrics
+covering both **lexical overlap** (BLEU, ROGUE) and **semantic similarity** (BERT Score) approaches,
+along with **model confidence** (Perplexity) and **ranking quality** (MRR) metrics.
+
+### 📚 What You'll Learn
+
+| Metric | Focus | Use Case |
+|--------|-------|----------|
+| **BLEU Score** | N-gram precision | Machine translation evaluation |
+| **ROGUE Score** | N-gram recall | Text summarization evaluation |
+| **Perplexity** | Token probability | Language model confidence |
+| **MRR** | Ranking position | Question-answering / retrieval |
+| **BERT Score** | Semantic similarity | Paraphrase detection |
+
+### 🎯 Getting Started
+
+Use the **sidebar navigation** to explore each metric:
+- **Overview**: Compare all metrics side-by-side
+- **Individual Pages**: Deep dive into each metric with step-by-step calculations
+
+### 💡 Key Concepts
+
+**Ground Truth vs Prediction**: Most metrics compare a *reference* (ground truth) text
+against a *candidate* (model prediction) to measure quality.
+
+**Precision vs Recall**: 
+- **Precision** (BLEU): Of the words generated, how many are correct?
+- **Recall** (ROGUE): Of the correct words, how many were generated?
+
+---
+
+*Built with ❤️ using Streamlit, NLTK, and Transformers*
+""")
+
+st.sidebar.success("Select a page above to explore metrics!")

data/sample_evaluations.json

@@ -0,0 +1,40 @@
+{
+  "examples": [
+    {
+      "name": "Exact Match",
+      "ground_truth": "The cat sat on the mat",
+      "prediction": "The cat sat on the mat",
+      "description": "Perfect match - all metrics should be 1.0"
+    },
+    {
+      "name": "Paraphrase",
+      "ground_truth": "The cat sat on the mat",
+      "prediction": "The cat was sitting on the mat",
+      "description": "Same meaning, different words - BERT > BLEU"
+    },
+    {
+      "name": "Partial Match",
+      "ground_truth": "The cat sat on the mat and looked outside",
+      "prediction": "The cat sat on the mat",
+      "description": "Incomplete - brevity penalty applies"
+    },
+    {
+      "name": "Wrong Answer",
+      "ground_truth": "Paris is the capital of France",
+      "prediction": "Berlin is the capital of France",
+      "description": "Completely wrong but similar structure"
+    },
+    {
+      "name": "Extra Content",
+      "ground_truth": "The cat sat on the mat",
+      "prediction": "The cat sat on the mat and then jumped off quickly",
+      "description": "Extra words added - recall suffers"
+    },
+    {
+      "name": "Word Reorder",
+      "ground_truth": "The cat sat on the mat",
+      "prediction": "On the mat sat the cat",
+      "description": "Same words, different order - ROGUE-L handles this"
+    }
+  ]
+}

modules/metrics/bert_score.py

@@ -0,0 +1,270 @@
+"""BERT Score metric implementation using sentence embeddings."""
+
+from typing import List, Dict, Tuple
+import numpy as np
+from ..utils.text_processing import tokenize
+
+# Try to import sentence-transformers, fall back to simple implementation
+try:
+    from sentence_transformers import SentenceTransformer
+    SENTENCE_TRANSFORMERS_AVAILABLE = True
+except ImportError:
+    SENTENCE_TRANSFORMERS_AVAILABLE = False
+
+
+def cosine_similarity(vec1: np.ndarray, vec2: np.ndarray) -> float:
+    """Calculate cosine similarity between two vectors.
+    
+    Args:
+        vec1: First vector
+        vec2: Second vector
+        
+    Returns:
+        Cosine similarity (-1 to 1)
+    """
+    dot_product = np.dot(vec1, vec2)
+    norm1 = np.linalg.norm(vec1)
+    norm2 = np.linalg.norm(vec2)
+    
+    if norm1 == 0 or norm2 == 0:
+        return 0.0
+    
+    return dot_product / (norm1 * norm2)
+
+
+def simple_embedding(text: str, embedding_dim: int = 384) -> np.ndarray:
+    """Create a simple deterministic embedding for demonstration.
+    
+    In production, use sentence-transformers or bert-score library.
+    This is a simulation that creates consistent embeddings based on text content.
+    
+    Args:
+        text: Input text
+        embedding_dim: Dimension of embedding vector
+        
+    Returns:
+        Embedding vector
+    """
+    # Simple hash-based embedding for demonstration
+    tokens = tokenize(text)
+    
+    # Initialize embedding
+    embedding = np.zeros(embedding_dim)
+    
+    # Create embedding based on token hashes
+    for i, token in enumerate(tokens):
+        # Use hash to create deterministic but distributed values
+        token_hash = hash(token) % (2**32)
+        np.random.seed(token_hash)
+        
+        # Add weighted contribution
+        token_embedding = np.random.randn(embedding_dim)
+        # Weight by position (earlier tokens slightly more important)
+        weight = 1.0 / (1 + i * 0.1)
+        embedding += token_embedding * weight
+    
+    # Normalize
+    if len(tokens) > 0:
+        embedding /= len(tokens)
+    
+    # Add some sentence-level statistics
+    np.random.seed(hash(text) % (2**32))
+    embedding += np.random.randn(embedding_dim) * 0.1
+    
+    return embedding
+
+
+def calculate_bert_score_simple(reference: str, 
+                                 candidate: str,
+                                 model_name: str = "demo") -> Dict:
+    """Calculate BERT-like score using simple embeddings.
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        model_name: Model identifier (for demo purposes)
+        
+    Returns:
+        Dictionary with precision, recall, F1
+    """
+    # Get embeddings
+    ref_embedding = simple_embedding(reference)
+    cand_embedding = simple_embedding(candidate)
+    
+    # Calculate cosine similarity
+    similarity = cosine_similarity(ref_embedding, cand_embedding)
+    
+    # Normalize to 0-1 range (cosine similarity is -1 to 1)
+    similarity = (similarity + 1) / 2
+    
+    # For sentence-level similarity, precision = recall = F1
+    # BERT Score at token level would have different P/R
+    return {
+        "precision": similarity,
+        "recall": similarity,
+        "f1": similarity,
+        "similarity": similarity,
+        "cosine_similarity": similarity * 2 - 1,  # Back to -1 to 1
+        "model": model_name,
+        "embedding_dim": len(ref_embedding),
+        "reference_tokens": len(tokenize(reference)),
+        "candidate_tokens": len(tokenize(candidate))
+    }
+
+
+def calculate_token_level_similarity(reference: str, 
+                                      candidate: str) -> Dict:
+    """Simulate token-level BERT Score with alignment visualization.
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        
+    Returns:
+        Dictionary with token-level alignment
+    """
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    # Create token embeddings
+    ref_embeddings = [simple_embedding(token, 128) for token in ref_tokens]
+    cand_embeddings = [simple_embedding(token, 128) for token in cand_tokens]
+    
+    # Calculate similarity matrix
+    similarity_matrix = np.zeros((len(ref_tokens), len(cand_tokens)))
+    
+    for i, ref_emb in enumerate(ref_embeddings):
+        for j, cand_emb in enumerate(cand_embeddings):
+            sim = cosine_similarity(ref_emb, cand_emb)
+            # Normalize to 0-1
+            similarity_matrix[i, j] = (sim + 1) / 2
+    
+    # Greedy matching for visualization
+    matches = []
+    used_cand = set()
+    
+    for i in range(len(ref_tokens)):
+        best_match = -1
+        best_score = -1
+        
+        for j in range(len(cand_tokens)):
+            if j not in used_cand and similarity_matrix[i, j] > best_score:
+                best_score = similarity_matrix[i, j]
+                best_match = j
+        
+        if best_match >= 0 and best_score > 0.3:  # Threshold
+            matches.append({
+                "ref_token": ref_tokens[i],
+                "ref_pos": i,
+                "cand_token": cand_tokens[best_match],
+                "cand_pos": best_match,
+                "similarity": best_score
+            })
+            used_cand.add(best_match)
+    
+    # Calculate metrics from matches
+    if matches:
+        avg_similarity = sum(m["similarity"] for m in matches) / len(matches)
+        precision = len(matches) / len(cand_tokens) if cand_tokens else 0
+        recall = len(matches) / len(ref_tokens) if ref_tokens else 0
+        f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0
+    else:
+        avg_similarity = 0
+        precision = recall = f1 = 0
+    
+    return {
+        "precision": precision,
+        "recall": recall,
+        "f1": f1,
+        "avg_similarity": avg_similarity,
+        "similarity_matrix": similarity_matrix.tolist(),
+        "matches": matches,
+        "ref_tokens": ref_tokens,
+        "cand_tokens": cand_tokens,
+        "num_matches": len(matches)
+    }
+
+
+def calculate_bert_score(reference: str, 
+                         candidate: str,
+                         use_real_model: bool = False) -> Dict:
+    """Calculate BERT Score with fallback to simple implementation.
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        use_real_model: Whether to try loading real sentence-transformers model
+        
+    Returns:
+        Dictionary with BERT Score results
+    """
+    if use_real_model and SENTENCE_TRANSFORMERS_AVAILABLE:
+        try:
+            # Try to use real model
+            model = SentenceTransformer('all-MiniLM-L6-v2')
+            ref_emb = model.encode(reference)
+            cand_emb = model.encode(candidate)
+            
+            similarity = cosine_similarity(ref_emb, cand_emb)
+            similarity = (similarity + 1) / 2
+            
+            return {
+                "precision": similarity,
+                "recall": similarity,
+                "f1": similarity,
+                "similarity": similarity,
+                "model": "sentence-transformers/all-MiniLM-L6-v2",
+                "is_real_model": True
+            }
+        except Exception as e:
+            # Fall back to simple implementation
+            pass
+    
+    # Use simple implementation
+    result = calculate_bert_score_simple(reference, candidate)
+    result["is_real_model"] = False
+    result["note"] = "Using simulation. Install sentence-transformers for real embeddings."
+    
+    return result
+
+
+def interpret_bert_score(f1: float) -> str:
+    """Interpret BERT Score F1 quality.
+    
+    Args:
+        f1: BERT Score F1 (0-1)
+        
+    Returns:
+        Quality description
+    """
+    if f1 >= 0.9:
+        return "Excellent (Semantically identical)"
+    elif f1 >= 0.7:
+        return "Good (Very similar meaning)"
+    elif f1 >= 0.5:
+        return "Fair (Related meaning)"
+    elif f1 >= 0.3:
+        return "Poor (Some semantic overlap)"
+    else:
+        return "Very Poor (Little semantic relation)"
+
+
+def get_bert_score_grade(f1: float) -> str:
+    """Get letter grade for BERT Score.
+    
+    Args:
+        f1: BERT Score F1
+        
+    Returns:
+        Letter grade (A-F)
+    """
+    if f1 >= 0.85:
+        return "A"
+    elif f1 >= 0.75:
+        return "B"
+    elif f1 >= 0.60:
+        return "C"
+    elif f1 >= 0.40:
+        return "D"
+    else:
+        return "F"

modules/metrics/bleu.py

@@ -0,0 +1,199 @@
+"""BLEU Score implementation with visualization support."""
+
+import math
+from typing import List, Tuple, Dict
+from collections import Counter
+from ..utils.text_processing import tokenize, count_ngrams
+
+
+def calculate_bleu(reference: str, candidate: str, max_n: int = 4, 
+                   weights: List[float] = None) -> Dict:
+    """Calculate BLEU score with detailed breakdown.
+    
+    BLEU = BP * exp(Σ w_n * log(p_n))
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        max_n: Maximum n-gram size (default 4 for BLEU-4)
+        weights: Weights for each n-gram precision (default uniform)
+        
+    Returns:
+        Dictionary with BLEU score and component breakdown
+    """
+    if weights is None:
+        weights = [1.0 / max_n] * max_n
+    
+    # Tokenize
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    # Calculate n-gram precisions
+    precisions = []
+    clipped_counts = []
+    total_counts = []
+    
+    for n in range(1, max_n + 1):
+        # Count n-grams
+        ref_counts = count_ngrams(ref_tokens, n)
+        cand_counts = count_ngrams(cand_tokens, n)
+        
+        # Calculate clipped counts
+        clipped_count = 0
+        total_count = 0
+        
+        for ngram, count in cand_counts.items():
+            total_count += count
+            clipped_count += min(count, ref_counts.get(ngram, 0))
+        
+        # Calculate precision
+        if total_count == 0:
+            precision = 0.0
+        else:
+            precision = clipped_count / total_count
+        
+        precisions.append(precision)
+        clipped_counts.append(clipped_count)
+        total_counts.append(total_count)
+    
+    # Calculate brevity penalty
+    ref_len = len(ref_tokens)
+    cand_len = len(cand_tokens)
+    
+    if cand_len > ref_len:
+        bp = 1.0
+    elif cand_len == 0:
+        bp = 0.0
+    else:
+        bp = math.exp(1 - ref_len / cand_len)
+    
+    # Calculate weighted log precision
+    log_precisions = [math.log(p) if p > 0 else -999 for p in precisions]
+    weighted_log_sum = sum(w * lp for w, lp in zip(weights, log_precisions))
+    
+    # Final BLEU score
+    if all(p == 0 for p in precisions):
+        bleu = 0.0
+    else:
+        bleu = bp * math.exp(weighted_log_sum)
+    
+    return {
+        "bleu": bleu,
+        "brevity_penalty": bp,
+        "precisions": precisions,
+        "clipped_counts": clipped_counts,
+        "total_counts": total_counts,
+        "ref_length": ref_len,
+        "cand_length": cand_len,
+        "weights": weights,
+        "geo_mean_precision": math.exp(weighted_log_sum) if any(p > 0 for p in precisions) else 0
+    }
+
+
+def calculate_modified_precision(reference: str, candidate: str, n: int) -> Tuple[float, int, int]:
+    """Calculate modified n-gram precision for BLEU.
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        n: N-gram size
+        
+    Returns:
+        (precision, clipped_count, total_count)
+    """
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    ref_counts = count_ngrams(ref_tokens, n)
+    cand_counts = count_ngrams(cand_tokens, n)
+    
+    clipped_count = 0
+    total_count = 0
+    
+    for ngram, count in cand_counts.items():
+        total_count += count
+        clipped_count += min(count, ref_counts.get(ngram, 0))
+    
+    if total_count == 0:
+        return 0.0, 0, 0
+    
+    return clipped_count / total_count, clipped_count, total_count
+
+
+def get_matching_ngrams_detailed(reference: str, candidate: str, n: int) -> Dict:
+    """Get detailed matching information for visualization.
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        n: N-gram size
+        
+    Returns:
+        Dictionary with matching details
+    """
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    ref_counts = count_ngrams(ref_tokens, n)
+    cand_counts = count_ngrams(cand_tokens, n)
+    
+    matches = []
+    over_matches = []
+    
+    for ngram, cand_count in cand_counts.items():
+        ref_count = ref_counts.get(ngram, 0)
+        if ref_count > 0:
+            matches.append({
+                "ngram": ngram,
+                "candidate_count": cand_count,
+                "reference_count": ref_count,
+                "clipped_count": min(cand_count, ref_count)
+            })
+        
+        if cand_count > ref_count:
+            over_matches.append({
+                "ngram": ngram,
+                "candidate_count": cand_count,
+                "reference_count": ref_count,
+                "excess": cand_count - ref_count
+            })
+    
+    # Non-matching n-grams
+    non_matches = []
+    for ngram, cand_count in cand_counts.items():
+        if ngram not in ref_counts:
+            non_matches.append({
+                "ngram": ngram,
+                "count": cand_count
+            })
+    
+    return {
+        "matches": matches,
+        "over_matches": over_matches,
+        "non_matches": non_matches,
+        "ref_ngrams": list(ref_counts.keys()),
+        "cand_ngrams": list(cand_counts.keys()),
+        "total_ref_ngrams": len(ref_tokens) - n + 1 if len(ref_tokens) >= n else 0,
+        "total_cand_ngrams": len(cand_tokens) - n + 1 if len(cand_tokens) >= n else 0
+    }
+
+
+def interpret_bleu_score(bleu: float) -> str:
+    """Interpret BLEU score quality.
+    
+    Args:
+        bleu: BLEU score (0-1)
+        
+    Returns:
+        Quality description
+    """
+    if bleu >= 0.8:
+        return "Excellent (Human-level quality)"
+    elif bleu >= 0.6:
+        return "Good (Understandable, minor errors)"
+    elif bleu >= 0.4:
+        return "Fair (Understandable but awkward)"
+    elif bleu >= 0.2:
+        return "Poor (Many errors, hard to understand)"
+    else:
+        return "Very Poor (Unintelligible)"

modules/metrics/mrr.py

@@ -0,0 +1,214 @@
+"""Mean Reciprocal Rank (MRR) metric implementation."""
+
+from typing import List, Dict, Tuple, Union
+import statistics
+
+
+def calculate_reciprocal_rank(ranked_list: List[str], 
+                               correct_answer: str,
+                               case_sensitive: bool = False) -> Dict:
+    """Calculate Reciprocal Rank for a single query.
+    
+    RR = 1 / rank_of_correct_answer
+    If not found, RR = 0
+    
+    Args:
+        ranked_list: List of ranked answers (best first)
+        correct_answer: The correct answer to find
+        case_sensitive: Whether matching is case-sensitive
+        
+    Returns:
+        Dictionary with RR and rank information
+    """
+    if not case_sensitive:
+        ranked_list_lower = [item.lower() for item in ranked_list]
+        correct_answer_lower = correct_answer.lower()
+        search_list = ranked_list_lower
+        search_answer = correct_answer_lower
+    else:
+        search_list = ranked_list
+        search_answer = correct_answer
+    
+    # Find rank of correct answer
+    rank = None
+    for i, item in enumerate(search_list, 1):
+        if item == search_answer:
+            rank = i
+            break
+    
+    if rank is None:
+        return {
+            "reciprocal_rank": 0.0,
+            "rank": None,
+            "found": False,
+            "correct_answer": correct_answer,
+            "total_candidates": len(ranked_list)
+        }
+    
+    return {
+        "reciprocal_rank": 1.0 / rank,
+        "rank": rank,
+        "found": True,
+        "correct_answer": correct_answer,
+        "total_candidates": len(ranked_list),
+        "top_k": rank <= 3  # Considered good if in top 3
+    }
+
+
+def calculate_mrr(query_results: List[Dict]) -> Dict:
+    """Calculate Mean Reciprocal Rank across multiple queries.
+    
+    MRR = (1/|Q|) * Σ (1/rank_i)
+    
+    Args:
+        query_results: List of dictionaries containing:
+            - "question": The question text
+            - "ranked_answers": List of ranked answers
+            - "correct_answer": The correct answer
+            
+    Returns:
+        Dictionary with MRR and breakdown
+    """
+    rr_scores = []
+    query_details = []
+    
+    for result in query_results:
+        question = result.get("question", "")
+        ranked_answers = result.get("ranked_answers", [])
+        correct_answer = result.get("correct_answer", "")
+        
+        rr_result = calculate_reciprocal_rank(ranked_answers, correct_answer)
+        
+        rr_scores.append(rr_result["reciprocal_rank"])
+        query_details.append({
+            "question": question,
+            "correct_answer": correct_answer,
+            "rank": rr_result["rank"],
+            "reciprocal_rank": rr_result["reciprocal_rank"],
+            "found": rr_result["found"],
+            "ranked_answers": ranked_answers[:5]  # Store top 5 for display
+        })
+    
+    # Calculate MRR
+    mrr = statistics.mean(rr_scores) if rr_scores else 0.0
+    
+    # Additional statistics
+    found_count = sum(1 for q in query_details if q["found"])
+    top1_count = sum(1 for q in query_details if q["rank"] == 1)
+    top3_count = sum(1 for q in query_details if q["rank"] and q["rank"] <= 3)
+    
+    return {
+        "mrr": mrr,
+        "num_queries": len(query_results),
+        "reciprocal_ranks": rr_scores,
+        "query_details": query_details,
+        "found_rate": found_count / len(query_results) if query_results else 0,
+        "top1_accuracy": top1_count / len(query_results) if query_results else 0,
+        "top3_accuracy": top3_count / len(query_results) if query_results else 0,
+        "hits_at_1": top1_count,
+        "hits_at_3": top3_count
+    }
+
+
+def calculate_mrr_simple(ranked_lists: List[List[str]], 
+                          correct_answers: List[str]) -> Dict:
+    """Simplified MRR calculation from parallel lists.
+    
+    Args:
+        ranked_lists: List of ranked answer lists
+        correct_answers: List of correct answers (parallel to ranked_lists)
+        
+    Returns:
+        Dictionary with MRR results
+    """
+    query_results = [
+        {
+            "question": f"Query {i+1}",
+            "ranked_answers": ranked,
+            "correct_answer": correct
+        }
+        for i, (ranked, correct) in enumerate(zip(ranked_lists, correct_answers))
+    ]
+    
+    return calculate_mrr(query_results)
+
+
+def interpret_mrr(mrr: float) -> str:
+    """Interpret MRR score quality.
+    
+    MRR ranges from 0 to 1 (perfect ranking).
+    
+    Args:
+        mrr: Mean Reciprocal Rank (0-1)
+        
+    Returns:
+        Quality description
+    """
+    if mrr >= 0.8:
+        return "Excellent (Usually ranks correct answer at #1)"
+    elif mrr >= 0.6:
+        return "Good (Usually in top 2)"
+    elif mrr >= 0.4:
+        return "Fair (Usually in top 3)"
+    elif mrr >= 0.2:
+        return "Poor (Correct answer often buried)"
+    else:
+        return "Very Poor (Rarely finds correct answer)"
+
+
+def get_mrr_grade(mrr: float) -> str:
+    """Get letter grade for MRR.
+    
+    Args:
+        mrr: Mean Reciprocal Rank
+        
+    Returns:
+        Letter grade (A-F)
+    """
+    if mrr >= 0.9:
+        return "A+"
+    elif mrr >= 0.8:
+        return "A"
+    elif mrr >= 0.7:
+        return "B+"
+    elif mrr >= 0.6:
+        return "B"
+    elif mrr >= 0.5:
+        return "C+"
+    elif mrr >= 0.4:
+        return "C"
+    elif mrr >= 0.3:
+        return "D"
+    else:
+        return "F"
+
+
+def visualize_ranking(ranked_list: List[str], 
+                     correct_answer: str,
+                     max_display: int = 5) -> List[Dict]:
+    """Create visualization data for a ranking.
+    
+    Args:
+        ranked_list: List of ranked answers
+        correct_answer: The correct answer
+        max_display: Maximum items to display
+        
+    Returns:
+        List of dictionaries with rank info for display
+    """
+    result = []
+    found_rank = None
+    
+    for i, answer in enumerate(ranked_list[:max_display], 1):
+        is_correct = answer.lower() == correct_answer.lower()
+        if is_correct:
+            found_rank = i
+        
+        result.append({
+            "rank": i,
+            "answer": answer,
+            "is_correct": is_correct,
+            "reciprocal_score": 1.0 / i if is_correct else 0.0
+        })
+    
+    return result

modules/metrics/perplexity.py

@@ -0,0 +1,195 @@
+"""Perplexity metric implementation."""
+
+import math
+from typing import List, Dict, Tuple
+from ..utils.text_processing import tokenize
+
+
+def calculate_perplexity_from_probs(token_probs: List[float]) -> Dict:
+    """Calculate perplexity from token probabilities.
+    
+    Perplexity = exp(-1/N * Σ log(P(token_i)))
+    
+    Args:
+        token_probs: List of probabilities for each token (0 to 1)
+        
+    Returns:
+        Dictionary with perplexity and components
+    """
+    if not token_probs or any(p <= 0 for p in token_probs):
+        return {
+            "perplexity": float('inf'),
+            "avg_log_prob": float('-inf'),
+            "num_tokens": len(token_probs),
+            "token_details": []
+        }
+    
+    # Calculate log probabilities
+    log_probs = [math.log(p) for p in token_probs]
+    avg_log_prob = sum(log_probs) / len(log_probs)
+    
+    # Calculate perplexity
+    perplexity = math.exp(-avg_log_prob)
+    
+    # Token-level details
+    token_details = [
+        {
+            "token_index": i,
+            "probability": p,
+            "log_probability": lp,
+            "perplexity_contrib": math.exp(-lp)
+        }
+        for i, (p, lp) in enumerate(zip(token_probs, log_probs))
+    ]
+    
+    return {
+        "perplexity": perplexity,
+        "avg_log_prob": avg_log_prob,
+        "num_tokens": len(token_probs),
+        "token_details": token_details,
+        "cross_entropy": -avg_log_prob
+    }
+
+
+def simulate_token_probabilities(text: str, 
+                                  base_confidence: float = 0.7,
+                                  variation: float = 0.2) -> List[float]:
+    """Simulate token probabilities for demonstration.
+    
+    In real scenarios, these come from the language model's softmax output.
+    This is a simulation for educational purposes.
+    
+    Args:
+        text: Input text
+        base_confidence: Average probability (0-1)
+        variation: How much probabilities vary
+        
+    Returns:
+        List of simulated token probabilities
+    """
+    tokens = tokenize(text)
+    import random
+    
+    # Set seed for reproducibility
+    random.seed(sum(ord(c) for c in text))
+    
+    probs = []
+    for i, token in enumerate(tokens):
+        # Vary probability based on token characteristics
+        # Common words have higher probability
+        is_common = len(token) <= 4 and token.isalpha()
+        
+        if is_common:
+            base = base_confidence + 0.1
+        else:
+            base = base_confidence - 0.1
+        
+        # Add some randomness
+        prob = base + random.uniform(-variation, variation)
+        prob = max(0.01, min(0.99, prob))  # Clamp between 0.01 and 0.99
+        
+        probs.append(prob)
+    
+    return probs
+
+
+def calculate_perplexity_approximation(text: str, 
+                                        model_confidence: str = "medium") -> Dict:
+    """Calculate approximate perplexity for demonstration.
+    
+    Args:
+        text: Input text
+        model_confidence: "high", "medium", or "low"
+        
+    Returns:
+        Dictionary with perplexity and token breakdown
+    """
+    tokens = tokenize(text)
+    
+    # Map confidence to base probability
+    confidence_map = {
+        "high": 0.85,
+        "medium": 0.65,
+        "low": 0.40
+    }
+    
+    base_confidence = confidence_map.get(model_confidence, 0.65)
+    
+    # Generate simulated probabilities
+    token_probs = simulate_token_probabilities(text, base_confidence, 0.15)
+    
+    # Calculate perplexity
+    result = calculate_perplexity_from_probs(token_probs)
+    
+    # Add token text for display
+    for i, token in enumerate(tokens):
+        if i < len(result["token_details"]):
+            result["token_details"][i]["token"] = token
+    
+    return result
+
+
+def interpret_perplexity(perplexity: float) -> str:
+    """Interpret perplexity score.
+    
+    Lower is better. Perplexity = number of choices the model had at each step.
+    
+    Args:
+        perplexity: Perplexity score (>= 1)
+        
+    Returns:
+        Interpretation string
+    """
+    if perplexity < 10:
+        return "Excellent (Model is very confident, almost deterministic)"
+    elif perplexity < 50:
+        return "Good (Model is confident with minor uncertainty)"
+    elif perplexity < 100:
+        return "Fair (Model has moderate uncertainty)"
+    elif perplexity < 500:
+        return "Poor (Model is often confused)"
+    else:
+        return "Very Poor (Model is very confused, near random)"
+
+
+def get_perplexity_grade(perplexity: float) -> str:
+    """Get letter grade for perplexity.
+    
+    Args:
+        perplexity: Perplexity score
+        
+    Returns:
+        Letter grade (A-F)
+    """
+    if perplexity < 20:
+        return "A"
+    elif perplexity < 50:
+        return "B"
+    elif perplexity < 100:
+        return "C"
+    elif perplexity < 200:
+        return "D"
+    else:
+        return "F"
+
+
+def calculate_perplexity_with_external_model(text: str, 
+                                               api_provider: str = "openai") -> Dict:
+    """Placeholder for real API-based perplexity calculation.
+    
+    Note: Most LLM APIs don't expose raw token probabilities.
+    This would require using a local model or special API endpoints.
+    
+    Args:
+        text: Input text
+        api_provider: API provider name
+        
+    Returns:
+        Dictionary with perplexity (placeholder)
+    """
+    # Placeholder - real implementation would call API or local model
+    return {
+        "perplexity": None,
+        "note": f"Real perplexity calculation requires local model or {api_provider} logprobs API",
+        "simulation_available": True
+    }

modules/metrics/rogue.py

@@ -0,0 +1,352 @@
+"""ROGUE Score implementation with 5 variants."""
+
+from typing import List, Tuple, Dict
+from collections import Counter
+import math
+from ..utils.text_processing import tokenize, get_ngrams, get_skip_bigrams
+
+
+def longest_common_subsequence(X: List[str], Y: List[str]) -> List[str]:
+    """Find the Longest Common Subsequence (LCS) between two sequences.
+    
+    Args:
+        X: First sequence
+        Y: Second sequence
+        
+    Returns:
+        The LCS as a list of elements
+    """
+    m, n = len(X), len(Y)
+    
+    # Build LCS table
+    L = [[0] * (n + 1) for _ in range(m + 1)]
+    
+    for i in range(1, m + 1):
+        for j in range(1, n + 1):
+            if X[i-1] == Y[j-1]:
+                L[i][j] = L[i-1][j-1] + 1
+            else:
+                L[i][j] = max(L[i-1][j], L[i][j-1])
+    
+    # Backtrack to find LCS
+    lcs = []
+    i, j = m, n
+    while i > 0 and j > 0:
+        if X[i-1] == Y[j-1]:
+            lcs.append(X[i-1])
+            i -= 1
+            j -= 1
+        elif L[i-1][j] > L[i][j-1]:
+            i -= 1
+        else:
+            j -= 1
+    
+    return lcs[::-1]
+
+
+def weighted_lcs(X: List[str], Y: List[str], weight_func=None) -> Tuple[int, float]:
+    """Calculate Weighted Longest Common Subsequence (ROGUE-W).
+    
+    Args:
+        X: First sequence
+        Y: Second sequence
+        weight_func: Function to calculate weight based on consecutive length
+        
+    Returns:
+        (lcs_length, weighted_lcs_score)
+    """
+    if weight_func is None:
+        weight_func = lambda x: x ** 1.2  # Default: f(k) = k^1.2
+    
+    lcs = longest_common_subsequence(X, Y)
+    
+    if not lcs:
+        return 0, 0.0
+    
+    # Find consecutive sequences in LCS
+    consecutive_lengths = []
+    current_len = 1
+    
+    for i in range(1, len(lcs)):
+        # Check if consecutive in both sequences
+        try:
+            idx1_x = X.index(lcs[i-1])
+            idx2_x = X.index(lcs[i])
+            idx1_y = Y.index(lcs[i-1])
+            idx2_y = Y.index(lcs[i])
+            
+            if idx2_x == idx1_x + 1 and idx2_y == idx1_y + 1:
+                current_len += 1
+            else:
+                consecutive_lengths.append(current_len)
+                current_len = 1
+        except ValueError:
+            consecutive_lengths.append(current_len)
+            current_len = 1
+    
+    consecutive_lengths.append(current_len)
+    
+    # Calculate weighted LCS
+    wlcs = sum(weight_func(length) for length in consecutive_lengths)
+    
+    return len(lcs), wlcs
+
+
+def calculate_rogue_n(reference: str, candidate: str, n: int = 1) -> Dict:
+    """Calculate ROGUE-N (n-gram based).
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        n: N-gram size (1 for unigram, 2 for bigram)
+        
+    Returns:
+        Dictionary with precision, recall, F1
+    """
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    # Get n-grams
+    ref_ngrams = get_ngrams(ref_tokens, n)
+    cand_ngrams = get_ngrams(cand_tokens, n)
+    
+    if not ref_ngrams or not cand_ngrams:
+        return {"precision": 0.0, "recall": 0.0, "f1": 0.0, "matches": 0}
+    
+    ref_counts = Counter(ref_ngrams)
+    cand_counts = Counter(cand_ngrams)
+    
+    # Count matches
+    matches = 0
+    for ngram in cand_counts:
+        matches += min(cand_counts[ngram], ref_counts.get(ngram, 0))
+    
+    # Calculate metrics
+    recall = matches / len(ref_ngrams) if ref_ngrams else 0.0
+    precision = matches / len(cand_ngrams) if cand_ngrams else 0.0
+    f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0.0
+    
+    return {
+        "precision": precision,
+        "recall": recall,
+        "f1": f1,
+        "matches": matches,
+        "ref_ngrams": len(ref_ngrams),
+        "cand_ngrams": len(cand_ngrams)
+    }
+
+
+def calculate_rogue_l(reference: str, candidate: str) -> Dict:
+    """Calculate ROGUE-L (Longest Common Subsequence based).
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        
+    Returns:
+        Dictionary with precision, recall, F1
+    """
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    lcs = longest_common_subsequence(ref_tokens, cand_tokens)
+    lcs_len = len(lcs)
+    
+    if lcs_len == 0:
+        return {"precision": 0.0, "recall": 0.0, "f1": 0.0, "lcs": []}
+    
+    recall = lcs_len / len(ref_tokens) if ref_tokens else 0.0
+    precision = lcs_len / len(cand_tokens) if cand_tokens else 0.0
+    f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0.0
+    
+    return {
+        "precision": precision,
+        "recall": recall,
+        "f1": f1,
+        "lcs": lcs,
+        "lcs_length": lcs_len,
+        "ref_length": len(ref_tokens),
+        "cand_length": len(cand_tokens)
+    }
+
+
+def calculate_rogue_s(reference: str, candidate: str, max_skip: int = 2) -> Dict:
+    """Calculate ROGUE-S (Skip-bigram based).
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        max_skip: Maximum number of words to skip
+        
+    Returns:
+        Dictionary with precision, recall, F1
+    """
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    # Get skip-bigrams
+    ref_skip_bigrams = get_skip_bigrams(ref_tokens, max_skip)
+    cand_skip_bigrams = get_skip_bigrams(cand_tokens, max_skip)
+    
+    if not ref_skip_bigrams or not cand_skip_bigrams:
+        return {"precision": 0.0, "recall": 0.0, "f1": 0.0, "matches": 0}
+    
+    ref_counts = Counter(ref_skip_bigrams)
+    cand_counts = Counter(cand_skip_bigrams)
+    
+    # Count matches
+    matches = 0
+    for bigram in cand_counts:
+        matches += min(cand_counts[bigram], ref_counts.get(bigram, 0))
+    
+    # Calculate metrics
+    recall = matches / len(ref_skip_bigrams) if ref_skip_bigrams else 0.0
+    precision = matches / len(cand_skip_bigrams) if cand_skip_bigrams else 0.0
+    f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0.0
+    
+    return {
+        "precision": precision,
+        "recall": recall,
+        "f1": f1,
+        "matches": matches,
+        "ref_skip_bigrams": len(ref_skip_bigrams),
+        "cand_skip_bigrams": len(cand_skip_bigrams)
+    }
+
+
+def calculate_rogue_su(reference: str, candidate: str, max_skip: int = 2) -> Dict:
+    """Calculate ROGUE-SU (Skip-bigram + Unigram combined).
+    
+    This combines unigrams with skip-bigrams to avoid the weakness of ROGUE-S
+    (which gives 0 when word order is completely reversed).
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        max_skip: Maximum number of words to skip
+        
+    Returns:
+        Dictionary with precision, recall, F1
+    """
+    # Get ROGUE-1 (unigram) and ROGUE-S
+    rogue1 = calculate_rogue_n(reference, candidate, 1)
+    rogue_s = calculate_rogue_s(reference, candidate, max_skip)
+    
+    # Combine: add unigram matches to skip-bigram matches
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    ref_unigrams = get_ngrams(ref_tokens, 1)
+    cand_unigrams = get_ngrams(cand_tokens, 1)
+    ref_skip_bigrams = get_skip_bigrams(ref_tokens, max_skip)
+    cand_skip_bigrams = get_skip_bigrams(cand_tokens, max_skip)
+    
+    # Total counts
+    total_ref = len(ref_unigrams) + len(ref_skip_bigrams)
+    total_cand = len(cand_unigrams) + len(cand_skip_bigrams)
+    
+    # Combined matches
+    combined_matches = rogue1["matches"] + rogue_s["matches"]
+    
+    # Calculate combined metrics
+    recall = combined_matches / total_ref if total_ref > 0 else 0.0
+    precision = combined_matches / total_cand if total_cand > 0 else 0.0
+    f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0.0
+    
+    return {
+        "precision": precision,
+        "recall": recall,
+        "f1": f1,
+        "rogue1": rogue1,
+        "rogue_s": rogue_s,
+        "combined_matches": combined_matches
+    }
+
+
+def calculate_rogue_w(reference: str, candidate: str, weight_exponent: float = 1.2) -> Dict:
+    """Calculate ROGUE-W (Weighted Longest Common Subsequence).
+    
+    Rewards consecutive matches more heavily than scattered matches.
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        weight_exponent: Exponent for weight function (default 1.2)
+        
+    Returns:
+        Dictionary with precision, recall, F1
+    """
+    ref_tokens = tokenize(reference)
+    cand_tokens = tokenize(candidate)
+    
+    weight_func = lambda x: x ** weight_exponent
+    lcs_len, wlcs = weighted_lcs(ref_tokens, cand_tokens, weight_func)
+    
+    if wlcs == 0:
+        return {"precision": 0.0, "recall": 0.0, "f1": 0.0, "wlcs": 0}
+    
+    # Calculate f^-1 for normalization
+    # For f(k) = k^p, f^-1(x) = x^(1/p)
+    f_inv = lambda x: x ** (1.0 / weight_exponent)
+    
+    # ROGUE-W recall and precision
+    recall_denom = f_inv(sum(weight_func(len(seq)) for seq in [[t] for t in ref_tokens]))
+    precision_denom = f_inv(sum(weight_func(len(seq)) for seq in [[t] for t in cand_tokens]))
+    
+    recall = f_inv(wlcs) / len(ref_tokens) if ref_tokens else 0.0
+    precision = f_inv(wlcs) / len(cand_tokens) if cand_tokens else 0.0
+    
+    # Alternative calculation as used in paper
+    recall_alt = wlcs / sum(weight_func(len(seq)) for seq in [[t] for t in ref_tokens]) if ref_tokens else 0.0
+    
+    f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0.0
+    
+    return {
+        "precision": precision,
+        "recall": recall,
+        "f1": f1,
+        "recall_alt": recall_alt,
+        "wlcs": wlcs,
+        "lcs_length": lcs_len,
+        "ref_length": len(ref_tokens),
+        "cand_length": len(cand_tokens)
+    }
+
+
+def calculate_all_rogue(reference: str, candidate: str) -> Dict:
+    """Calculate all ROGUE variants.
+    
+    Args:
+        reference: Ground truth text
+        candidate: Model prediction text
+        
+    Returns:
+        Dictionary with all ROGUE scores
+    """
+    return {
+        "rogue1": calculate_rogue_n(reference, candidate, 1),
+        "rogue2": calculate_rogue_n(reference, candidate, 2),
+        "rogueL": calculate_rogue_l(reference, candidate),
+        "rogueS": calculate_rogue_s(reference, candidate),
+        "rogueSU": calculate_rogue_su(reference, candidate),
+        "rogueW": calculate_rogue_w(reference, candidate)
+    }
+
+
+def interpret_rogue_score(f1: float) -> str:
+    """Interpret ROGUE F1 score quality.
+    
+    Args:
+        f1: ROGUE F1 score (0-1)
+        
+    Returns:
+        Quality description
+    """
+    if f1 >= 0.5:
+        return "Good (Captures most key points)"
+    elif f1 >= 0.3:
+        return "Fair (Captures some key points)"
+    elif f1 >= 0.1:
+        return "Poor (Misses most key points)"
+    else:
+        return "Very Poor (Little to no overlap)"

modules/utils/examples.py

@@ -0,0 +1,150 @@
+"""Preset examples for metric demonstrations."""
+
+from typing import List, Dict, Tuple
+
+
+class EvaluationExample:
+    """Represents a ground truth / prediction pair example."""
+    
+    def __init__(self, name: str, ground_truth: str, prediction: str, 
+                 description: str = "", tags: List[str] = None):
+        self.name = name
+        self.ground_truth = ground_truth
+        self.prediction = prediction
+        self.description = description
+        self.tags = tags or []
+
+
+# Text comparison examples
+TEXT_EXAMPLES = [
+    EvaluationExample(
+        name="Exact Match",
+        ground_truth="The cat sat on the mat",
+        prediction="The cat sat on the mat",
+        description="Perfect match - all metrics should be 1.0",
+        tags=["exact", "perfect"]
+    ),
+    EvaluationExample(
+        name="Paraphrase (Synonyms)",
+        ground_truth="The cat sat on the mat",
+        prediction="The cat was sitting on the mat",
+        description="Same meaning, different words - good BERT Score, lower BLEU/ROGUE",
+        tags=["paraphrase", "semantic"]
+    ),
+    EvaluationExample(
+        name="Partial Match",
+        ground_truth="The cat sat on the mat and looked outside",
+        prediction="The cat sat on the mat",
+        description="Incomplete prediction - brevity penalty applies",
+        tags=["partial", "incomplete"]
+    ),
+    EvaluationExample(
+        name="Wrong Answer",
+        ground_truth="Paris is the capital of France",
+        prediction="Berlin is the capital of France",
+        description="Completely wrong but similar structure",
+        tags=["wrong", "incorrect"]
+    ),
+    EvaluationExample(
+        name="Extra Content",
+        ground_truth="The cat sat on the mat",
+        prediction="The cat sat on the mat and then jumped off quickly",
+        description="Extra words added - recall will suffer",
+        tags=["extra", "verbose"]
+    ),
+    EvaluationExample(
+        name="Word Order Changed",
+        ground_truth="The cat sat on the mat",
+        prediction="On the mat sat the cat",
+        description="Same words, different order - ROGUE-L should handle this",
+        tags=["reorder", "scrambled"]
+    ),
+    EvaluationExample(
+        name="Long Text - Translation",
+        ground_truth="Machine translation has revolutionized how we communicate across languages, enabling instant understanding of foreign texts.",
+        prediction="Machine translation has changed how we communicate between languages, allowing instant comprehension of foreign texts.",
+        description="Realistic translation scenario",
+        tags=["translation", "long"]
+    ),
+    EvaluationExample(
+        name="Summarization - Key Points",
+        ground_truth="The research paper demonstrates that neural networks can effectively predict protein structures with high accuracy, potentially revolutionizing drug discovery and biological research.",
+        prediction="Neural networks can predict protein structures accurately, which could transform drug discovery.",
+        description="Abstractive summarization - ROGUE should capture key points",
+        tags=["summarization", "abstractive"]
+    ),
+]
+
+# MRR-specific examples (question-answering format)
+MRR_EXAMPLES = [
+    {
+        "name": "Correct at Position 1",
+        "question": "What is the capital of France?",
+        "ranked_answers": ["Paris", "London", "Berlin", "Madrid"],
+        "correct_answer": "Paris",
+        "description": "Perfect ranking - MRR = 1.0"
+    },
+    {
+        "name": "Correct at Position 2",
+        "question": "What is the capital of France?",
+        "ranked_answers": ["London", "Paris", "Berlin", "Madrid"],
+        "correct_answer": "Paris",
+        "description": "Good ranking - MRR = 0.5"
+    },
+    {
+        "name": "Correct at Position 3",
+        "question": "What is the capital of France?",
+        "ranked_answers": ["London", "Berlin", "Paris", "Madrid"],
+        "correct_answer": "Paris",
+        "description": "Average ranking - MRR = 0.33"
+    },
+    {
+        "name": "Not in Top 3",
+        "question": "What is the capital of France?",
+        "ranked_answers": ["London", "Berlin", "Madrid", "Paris"],
+        "correct_answer": "Paris",
+        "description": "Poor ranking - MRR = 0.25"
+    },
+    {
+        "name": "Multiple Questions Batch",
+        "questions": [
+            {"q": "Capital of France?", "ranked": ["Paris", "London", "Berlin"], "correct": "Paris"},
+            {"q": "Capital of Japan?", "ranked": ["Beijing", "Tokyo", "Seoul"], "correct": "Tokyo"},
+            {"q": "Capital of UK?", "ranked": ["London", "Paris", "Berlin"], "correct": "London"},
+        ],
+        "description": "Batch evaluation - calculates mean across multiple questions"
+    }
+]
+
+
+def get_text_example_names() -> List[str]:
+    """Get list of available text example names."""
+    return [ex.name for ex in TEXT_EXAMPLES]
+
+
+def get_text_example(name: str) -> EvaluationExample:
+    """Get a specific text example by name.
+    
+    Args:
+        name: Example name
+        
+    Returns:
+        EvaluationExample object
+    """
+    for ex in TEXT_EXAMPLES:
+        if ex.name == name:
+            return ex
+    return TEXT_EXAMPLES[0]
+
+
+def get_mrr_example_names() -> List[str]:
+    """Get list of available MRR example names."""
+    return [ex["name"] for ex in MRR_EXAMPLES]
+
+
+def get_mrr_example(name: str) -> Dict:
+    """Get a specific MRR example by name."""
+    for ex in MRR_EXAMPLES:
+        if ex["name"] == name:
+            return ex
+    return MRR_EXAMPLES[0]

modules/utils/text_processing.py

@@ -0,0 +1,151 @@
+"""Text processing utilities for tokenization and n-gram generation."""
+
+import re
+from typing import List, Tuple, Dict
+import nltk
+from collections import Counter
+
+# Download required NLTK data
+try:
+    nltk.data.find('tokenizers/punkt')
+except LookupError:
+    nltk.download('punkt', quiet=True)
+
+
+def tokenize(text: str, lowercase: bool = True) -> List[str]:
+    """Tokenize text into words.
+    
+    Args:
+        text: Input text string
+        lowercase: Whether to convert to lowercase
+        
+    Returns:
+        List of tokens
+    """
+    if lowercase:
+        text = text.lower()
+    # Simple word tokenization
+    tokens = re.findall(r'\b\w+\b', text)
+    return tokens
+
+
+def get_ngrams(tokens: List[str], n: int) -> List[Tuple[str, ...]]:
+    """Generate n-grams from token list.
+    
+    Args:
+        tokens: List of tokens
+        n: N-gram size
+        
+    Returns:
+        List of n-gram tuples
+    """
+    if n > len(tokens):
+        return []
+    return [tuple(tokens[i:i+n]) for i in range(len(tokens) - n + 1)]
+
+
+def get_all_ngrams(tokens: List[str], max_n: int = 4) -> Dict[int, List[Tuple[str, ...]]]:
+    """Generate all n-grams up to max_n.
+    
+    Args:
+        tokens: List of tokens
+        max_n: Maximum n-gram size
+        
+    Returns:
+        Dictionary mapping n to list of n-grams
+    """
+    return {n: get_ngrams(tokens, n) for n in range(1, max_n + 1)}
+
+
+def count_ngrams(tokens: List[str], n: int) -> Counter:
+    """Count n-gram occurrences.
+    
+    Args:
+        tokens: List of tokens
+        n: N-gram size
+        
+    Returns:
+        Counter of n-gram frequencies
+    """
+    ngrams = get_ngrams(tokens, n)
+    return Counter(ngrams)
+
+
+def find_matching_ngrams(ref_tokens: List[str], cand_tokens: List[str], n: int) -> List[Tuple[Tuple[str, ...], int, int]]:
+    """Find matching n-grams between reference and candidate.
+    
+    Args:
+        ref_tokens: Reference tokens
+        cand_tokens: Candidate tokens
+        n: N-gram size
+        
+    Returns:
+        List of (ngram, ref_pos, cand_pos) tuples
+    """
+    ref_ngrams = get_ngrams(ref_tokens, n)
+    cand_ngrams = get_ngrams(cand_tokens, n)
+    
+    matches = []
+    for i, ref_ngram in enumerate(ref_ngrams):
+        for j, cand_ngram in enumerate(cand_ngrams):
+            if ref_ngram == cand_ngram:
+                matches.append((ref_ngram, i, j))
+    
+    return matches
+
+
+def get_skip_bigrams(tokens: List[str], max_skip: int = 2) -> List[Tuple[str, str]]:
+    """Generate skip-bigrams (pairs with gaps).
+    
+    Args:
+        tokens: List of tokens
+        max_skip: Maximum number of tokens to skip
+        
+    Returns:
+        List of skip-bigram tuples
+    """
+    skip_bigrams = []
+    for i in range(len(tokens)):
+        for j in range(i + 1, min(i + max_skip + 2, len(tokens))):
+            skip_bigrams.append((tokens[i], tokens[j]))
+    return skip_bigrams
+
+
+def highlight_matching_ngrams(text: str, matches: List[Tuple[Tuple[str, ...], int, int]], 
+                               color: str = "#90EE90") -> str:
+    """Highlight matching n-grams in text with HTML.
+    
+    Args:
+        text: Original text
+        matches: List of (ngram, start_pos, end_pos) - end_pos is length in tokens
+        color: Highlight color
+        
+    Returns:
+        HTML string with highlights
+    """
+    tokens = tokenize(text, lowercase=False)
+    if not matches:
+        return text
+    
+    # Sort matches by position
+    matches = sorted(matches, key=lambda x: x[1])
+    
+    # Build highlighted text
+    result = []
+    last_end = 0
+    
+    for ngram, start, _ in matches:
+        # Add text before match
+        if start > last_end:
+            result.append(" ".join(tokens[last_end:start]))
+        
+        # Add highlighted match
+        ngram_text = " ".join(ngram)
+        result.append(f'<span style="background-color: {color}; padding: 2px; border-radius: 3px;">{ngram_text}</span>')
+        last_end = start + len(ngram)
+    
+    # Add remaining text
+    if last_end < len(tokens):
+        result.append(" ".join(tokens[last_end:]))
+    
+    return " ".join(result)

modules/visualizations/charts.py

@@ -0,0 +1,317 @@
+"""Chart visualization utilities for metrics."""
+
+import plotly.graph_objects as go
+import plotly.express as px
+from plotly.subplots import make_subplots
+import numpy as np
+from typing import List, Dict, Any
+
+
+def create_radar_chart(metric_scores: Dict[str, float], 
+                       title: str = "Metric Comparison") -> go.Figure:
+    """Create a radar chart comparing multiple metrics.
+    
+    Args:
+        metric_scores: Dictionary of metric name -> score (0-1)
+        title: Chart title
+        
+    Returns:
+        Plotly figure object
+    """
+    categories = list(metric_scores.keys())
+    values = list(metric_scores.values())
+    
+    fig = go.Figure(data=go.Scatterpolar(
+        r=values + [values[0]],  # Close the polygon
+        theta=categories + [categories[0]],
+        fill='toself',
+        fillcolor='rgba(100, 149, 237, 0.3)',
+        line=dict(color='rgb(100, 149, 237)', width=2),
+        name='Scores'
+    ))
+    
+    fig.update_layout(
+        polar=dict(
+            radialaxis=dict(
+                visible=True,
+                range=[0, 1],
+                tickformat='.2f'
+            )
+        ),
+        showlegend=False,
+        title=title,
+        height=500
+    )
+    
+    return fig
+
+
+def create_bar_chart(data: Dict[str, float], 
+                     title: str = "Scores",
+                     color_scale: str = "Blues") -> go.Figure:
+    """Create a bar chart for metric scores.
+    
+    Args:
+        data: Dictionary of label -> value
+        title: Chart title
+        color_scale: Plotly color scale name
+        
+    Returns:
+        Plotly figure object
+    """
+    labels = list(data.keys())
+    values = list(data.values())
+    
+    colors = px.colors.sequential.Blues[2:2+len(labels)]
+    
+    fig = go.Figure(data=[go.Bar(
+        x=labels,
+        y=values,
+        marker_color=colors,
+        text=[f'{v:.3f}' for v in values],
+        textposition='auto'
+    )])
+    
+    fig.update_layout(
+        title=title,
+        yaxis=dict(range=[0, 1], title="Score"),
+        xaxis_title="Metric",
+        height=400,
+        showlegend=False
+    )
+    
+    return fig
+
+
+def create_ngram_precision_chart(precisions: List[float], 
+                                  clipped_counts: List[int],
+                                  total_counts: List[int]) -> go.Figure:
+    """Create chart showing n-gram precision breakdown.
+    
+    Args:
+        precisions: List of precision values for n=1,2,3,4
+        clipped_counts: List of clipped n-gram counts
+        total_counts: List of total n-gram counts
+        
+    Returns:
+        Plotly figure object
+    """
+    n_values = [f"{i+1}-gram" for i in range(len(precisions))]
+    
+    fig = make_subplots(
+        rows=1, cols=2,
+        subplot_titles=("N-gram Precision", "Match Counts"),
+        specs=[[{"type": "bar"}, {"type": "bar"}]]
+    )
+    
+    # Precision bars
+    fig.add_trace(
+        go.Bar(x=n_values, y=precisions, 
+               text=[f'{p:.3f}' for p in precisions],
+               textposition='auto',
+               marker_color='lightblue',
+               name="Precision"),
+        row=1, col=1
+    )
+    
+    # Match counts
+    fig.add_trace(
+        go.Bar(x=n_values, y=clipped_counts, 
+               text=clipped_counts,
+               textposition='auto',
+               marker_color='lightgreen',
+               name="Clipped"),
+        row=1, col=2
+    )
+    
+    fig.add_trace(
+        go.Bar(x=n_values, y=[t - c for t, c in zip(total_counts, clipped_counts)], 
+               text=[t - c for t, c in zip(total_counts, clipped_counts)],
+               textposition='auto',
+               marker_color='lightcoral',
+               name="Non-matching"),
+        row=1, col=2
+    )
+    
+    fig.update_layout(
+        barmode='stack',
+        height=400,
+        showlegend=True,
+        title_text="BLEU N-gram Analysis"
+    )
+    
+    fig.update_yaxes(title_text="Precision", range=[0, 1], row=1, col=1)
+    fig.update_yaxes(title_text="Count", row=1, col=2)
+    
+    return fig
+
+
+def create_heatmap(similarity_matrix: List[List[float]],
+                   x_labels: List[str],
+                   y_labels: List[str],
+                   title: str = "Similarity Matrix") -> go.Figure:
+    """Create a heatmap for similarity visualization.
+    
+    Args:
+        similarity_matrix: 2D array of similarity values
+        x_labels: Labels for x-axis (candidate tokens)
+        y_labels: Labels for y-axis (reference tokens)
+        title: Chart title
+        
+    Returns:
+        Plotly figure object
+    """
+    fig = go.Figure(data=go.Heatmap(
+        z=similarity_matrix,
+        x=x_labels,
+        y=y_labels,
+        colorscale='Blues',
+        text=[[f'{v:.2f}' for v in row] for row in similarity_matrix],
+        texttemplate='%{text}',
+        textfont={"size": 10},
+        hoverongaps=False
+    ))
+    
+    fig.update_layout(
+        title=title,
+        xaxis_title="Candidate Tokens",
+        yaxis_title="Reference Tokens",
+        height=500,
+        width=600
+    )
+    
+    return fig
+
+
+def create_ranking_visualization(ranked_items: List[Dict],
+                                  correct_answer: str) -> go.Figure:
+    """Create visualization for MRR ranking.
+    
+    Args:
+        ranked_items: List of dicts with 'answer', 'rank', 'is_correct'
+        correct_answer: The correct answer string
+        
+    Returns:
+        Plotly figure object
+    """
+    ranks = [item['rank'] for item in ranked_items]
+    answers = [item['answer'] for item in ranked_items]
+    is_correct = [item['is_correct'] for item in ranked_items]
+    
+    colors = ['green' if c else 'gray' for c in is_correct]
+    
+    fig = go.Figure(data=[go.Bar(
+        x=[f"#{r}" for r in ranks],
+        y=[1.0 / r for r in ranks],
+        text=answers,
+        textposition='auto',
+        marker_color=colors
+    )])
+    
+    # Add correct answer highlight
+    for i, correct in enumerate(is_correct):
+        if correct:
+            fig.add_annotation(
+                x=i,
+                y=1.0 / ranks[i] + 0.1,
+                text="✓ CORRECT",
+                showarrow=False,
+                font=dict(color="green", size=12)
+            )
+    
+    fig.update_layout(
+        title="Answer Ranking (Reciprocal Rank Score)",
+        yaxis=dict(title="Reciprocal Rank", range=[0, 1.2]),
+        xaxis=dict(title="Rank Position"),
+        height=400,
+        showlegend=False
+    )
+    
+    return fig
+
+
+def create_token_probability_chart(token_details: List[Dict]) -> go.Figure:
+    """Create chart showing per-token perplexity contribution.
+    
+    Args:
+        token_details: List of dicts with 'token', 'probability', 'perplexity_contrib'
+        
+    Returns:
+        Plotly figure object
+    """
+    tokens = [detail.get('token', f'token_{i}') for i, detail in enumerate(token_details)]
+    probs = [detail['probability'] for detail in token_details]
+    perps = [detail['perplexity_contrib'] for detail in token_details]
+    
+    fig = make_subplots(
+        rows=2, cols=1,
+        subplot_titles=("Token Probabilities", "Perplexity Contribution"),
+        vertical_spacing=0.15
+    )
+    
+    # Probability bars
+    colors = ['lightgreen' if p > 0.7 else 'orange' if p > 0.4 else 'lightcoral' for p in probs]
+    fig.add_trace(
+        go.Bar(x=tokens, y=probs, marker_color=colors, name="Probability"),
+        row=1, col=1
+    )
+    
+    # Perplexity bars
+    fig.add_trace(
+        go.Bar(x=tokens, y=perps, marker_color='lightblue', name="Perplexity"),
+        row=2, col=1
+    )
+    
+    fig.update_layout(height=600, showlegend=False)
+    fig.update_yaxes(title_text="Probability", range=[0, 1], row=1, col=1)
+    fig.update_yaxes(title_text="Perplexity", row=2, col=1)
+    
+    return fig
+
+
+def create_gauge_chart(value: float, 
+                      title: str,
+                      min_val: float = 0,
+                      max_val: float = 1) -> go.Figure:
+    """Create a gauge chart for single metric display.
+    
+    Args:
+        value: Value to display
+        title: Chart title
+        min_val: Minimum value
+        max_val: Maximum value
+        
+    Returns:
+        Plotly figure object
+    """
+    # Determine color based on value
+    if value >= 0.7:
+        color = "green"
+    elif value >= 0.4:
+        color = "orange"
+    else:
+        color = "red"
+    
+    fig = go.Figure(go.Indicator(
+        mode="gauge+number",
+        value=value,
+        title={'text': title},
+        gauge={
+            'axis': {'range': [min_val, max_val]},
+            'bar': {'color': color},
+            'steps': [
+                {'range': [min_val, max_val*0.33], 'color': 'lightcoral'},
+                {'range': [max_val*0.33, max_val*0.67], 'color': 'lightyellow'},
+                {'range': [max_val*0.67, max_val], 'color': 'lightgreen'}
+            ],
+            'threshold': {
+                'line': {'color': "black", 'width': 4},
+                'thickness': 0.75,
+                'value': value
+            }
+        }
+    ))
+    
+    fig.update_layout(height=300)
+    
+    return fig

modules/visualizations/explanations.py

@@ -0,0 +1,159 @@
+"""Mathematical formula and explanation utilities."""
+
+import streamlit as st
+
+
+def show_bleu_formula():
+    """Display BLEU score formula with explanation."""
+    st.latex(r"""
+    \\text{BLEU} = \\text{BP} \\times \\exp\\left(\\sum_{n=1}^{N} w_n \\log p_n\\right)
+    """)
+    
+    st.markdown("""
+    **Where:**
+    - **BP** = Brevity Penalty (penalizes short candidates)
+    - **p_n** = Modified precision for n-grams
+    - **w_n** = Weight for n-gram precision (usually uniform)
+    - **N** = Maximum n-gram size (typically 4)
+    """)
+    
+    with st.expander("Brevity Penalty Formula"):
+        st.latex(r"""
+        \\text{BP} = \\begin{cases}
+        1 & \\text{if } c > r \\\\
+        e^{(1-r/c)} & \\text{if } c \\leq r
+        \\end{cases}
+        """)
+        st.markdown("- **c** = candidate length, **r** = reference length")
+    
+    with st.expander("Modified N-gram Precision"):
+        st.latex(r"""
+        p_n = \\frac{\\sum_{\\text{n-gram} \\in \\text{Cand}} \\text{Count}_{\\text{clip}}(\\text{n-gram})}{\\sum_{\\text{n-gram} \\in \\text{Cand}} \\text{Count}(\\text{n-gram})}
+        """)
+        st.markdown("Count_clip = min(candidate count, reference count)")
+
+
+def show_rogue_formula():
+    """Display ROGUE score formula with explanation."""
+    st.subheader("ROGUE-N (N-gram Based)")
+    st.latex(r"""
+    \\text{ROGUE-N} = \\frac{\\sum_{S \\in \\{\\text{References}\\}} \\sum_{\\text{gram}_n \\in S} \\text{Count}_{\\text{match}}(\\text{gram}_n)}{\\sum_{S \\in \\{\\text{References}\\}} \\sum_{\\text{gram}_n \\in S} \\text{Count}(\\text{gram}_n)}
+    """)
+    st.markdown("**Focus: Recall** — how many reference n-grams were captured")
+    
+    st.subheader("ROGUE-L (Longest Common Subsequence)")
+    st.latex(r"""
+    \\text{R}_{\\text{lcs}} = \\frac{LCS(X, Y)}{|X|}, \\quad \\text{P}_{\\text{lcs}} = \\frac{LCS(X, Y)}{|Y|}
+    """)
+    st.latex(r"""
+    \\text{F}_{\\text{lcs}} = \\frac{(1 + \\beta^2) \\text{R}_{\\text{lcs}} \\text{P}_{\\text{lcs}}}{\\text{R}_{\\text{lcs}} + \\beta^2 \\text{P}_{\\text{lcs}}}
+    """)
+    st.markdown("**LCS** finds longest sequence appearing in both (not necessarily consecutive)")
+
+
+def show_perplexity_formula():
+    """Display Perplexity formula with explanation."""
+    st.latex(r"""
+    \\text{Perplexity} = \\exp\\left(-\\frac{1}{N} \\sum_{i=1}^{N} \\log P(w_i | w_1 \\ldots w_{i-1})\\right)
+    """)
+    
+    st.markdown("""
+    **Interpretation:**
+    - Perplexity = $2^{H}$ where $H$ is the cross-entropy
+    - Can be thought of as "weighted average branching factor"
+    - Lower is better (model is less "confused")
+    """)
+    
+    with st.expander("Example Interpretation"):
+        st.markdown("""
+        | Perplexity | Meaning |
+        |------------|---------|
+        | 1 | Perfect prediction |
+        | 10 | Model has ~10 choices at each step |
+        | 100 | Model is very confused |
+        | 1000 | Near random guessing |
+        """)
+
+
+def show_mrr_formula():
+    """Display MRR formula with explanation."""
+    st.latex(r"""
+    \\text{MRR} = \\frac{1}{|Q|} \\sum_{i=1}^{|Q|} \\frac{1}{\\text{rank}_i}
+    """)
+    
+    st.markdown("""
+    **Where:**
+    - **|Q|** = Number of queries
+    - **rank_i** = Position of correct answer for query i
+    - If correct answer not in list: $\frac{1}{\text{rank}} = 0$
+    """)
+    
+    with st.expander("Reciprocal Rank Examples"):
+        st.markdown("""
+        | Position | Reciprocal Rank |
+        |------------|-----------------|
+        | 1st | 1.0 |
+        | 2nd | 0.5 |
+        | 3rd | 0.33 |
+        | 4th | 0.25 |
+        | Not found | 0 |
+        """)
+
+
+def show_bert_score_formula():
+    """Display BERT Score formula with explanation."""
+    st.markdown("""
+    BERT Score uses contextual embeddings from pre-trained BERT to compute similarity:
+    """)
+    
+    st.latex(r"""
+    \\text{Similarity}(x_i, y_j) = \\frac{\\mathbf{x}_i^T \\mathbf{y}_j}{||\\mathbf{x}_i|| ||\\mathbf{y}_j||}
+    """)
+    
+    st.subheader("Greedy Matching for Precision/Recall")
+    st.latex(r"""
+    \\text{P}_{\\text{BERT}} = \\frac{1}{|x|} \\sum_{x_i \\in x} \\max_{y_j \\in y} \\mathbf{x}_i^T \\mathbf{y}_j
+    """)
+    st.latex(r"""
+    \\text{R}_{\\text{BERT}} = \\frac{1}{|y|} \\sum_{y_j \\in y} \\max_{x_i \\in x} \\mathbf{x}_i^T \\mathbf{y}_j
+    """)
+    
+    st.markdown("""
+    **Key Idea:** Each token in one text is matched to the most similar token in the other text.
+    - **Precision:** Average of best matches from candidate to reference
+    - **Recall:** Average of best matches from reference to candidate
+    """)
+
+
+def show_metric_comparison_table():
+    """Display comparison table of all metrics."""
+    st.markdown("""
+    | Metric | Type | Needs Reference | Best For | Range |
+    |--------|------|-----------------|----------|-------|
+    | **BLEU** | Lexical (Precision) | Yes | Machine Translation | 0-1 |
+    | **ROGUE** | Lexical (Recall) | Yes | Summarization | 0-1 |
+    | **Perplexity** | Model Confidence | No | Language Modeling | 1-∞ |
+    | **MRR** | Ranking | Yes (answer) | QA/Retrieval | 0-1 |
+    | **BERT Score** | Semantic | Yes | Paraphrase Detection | 0-1 |
+    """)
+
+
+def create_formula_expander(metric_name: str):
+    """Create an expander with formula for a given metric.
+    
+    Args:
+        metric_name: Name of the metric ('bleu', 'rogue', etc.)
+    """
+    with st.expander(f"📐 {metric_name.upper()} Formula & Explanation"):
+        if metric_name.lower() == 'bleu':
+            show_bleu_formula()
+        elif metric_name.lower() == 'rogue':
+            show_rogue_formula()
+        elif metric_name.lower() == 'perplexity':
+            show_perplexity_formula()
+        elif metric_name.lower() == 'mrr':
+            show_mrr_formula()
+        elif metric_name.lower() == 'bert_score':
+            show_bert_score_formula()
+        else:
+            st.write("Formula not available for this metric.")

pages/01_overview.py

@@ -0,0 +1,209 @@
+"""Overview page - Compare all metrics."""
+
+import streamlit as st
+import sys
+sys.path.append('/Users/mymac/Documents/applyjob/supportProjects/llm-evaluation-dashboard')
+
+from modules.metrics.bleu import calculate_bleu, interpret_bleu_score
+from modules.metrics.rogue import calculate_all_rogue, interpret_rogue_score
+from modules.metrics.perplexity import calculate_perplexity_approximation, interpret_perplexity
+from modules.metrics.bert_score import calculate_bert_score, interpret_bert_score
+from modules.visualizations.charts import create_radar_chart, create_bar_chart
+from modules.visualizations.explanations import show_metric_comparison_table
+from modules.utils.examples import get_text_example_names, get_text_example
+
+st.set_page_config(page_title="Overview", page_icon="📊", layout="wide")
+
+st.title("📊 Metrics Overview & Comparison")
+
+st.markdown("""
+Compare all 5 evaluation metrics side-by-side on the same text pair.
+See how different metrics capture different aspects of quality.
+""")
+
+# Input section
+col1, col2 = st.columns(2)
+
+with col1:
+    st.subheader("📄 Ground Truth (Reference)")
+    example_name = st.selectbox("Choose example:", ["Custom"] + get_text_example_names())
+    
+    if example_name != "Custom":
+        example = get_text_example(example_name)
+        ground_truth = st.text_area("Reference:", value=example.ground_truth, height=100)
+        st.caption(example.description)
+    else:
+        ground_truth = st.text_area("Reference:", 
+                                    value="The cat sat on the mat and looked outside at the birds.",
+                                    height=100)
+
+with col2:
+    st.subheader("🤖 Model Prediction (Candidate)")
+    if example_name != "Custom":
+        prediction = st.text_area("Candidate:", value=example.prediction, height=100)
+    else:
+        prediction = st.text_area("Candidate:", 
+                                  value="The cat was sitting on the mat and gazing at the birds outside.",
+                                  height=100)
+
+# Calculate all metrics
+if st.button("🧮 Compare All Metrics", type="primary"):
+    
+    # Calculate each metric
+    bleu_result = calculate_bleu(ground_truth, prediction)
+    rogue_result = calculate_all_rogue(ground_truth, prediction)
+    perplexity_result = calculate_perplexity_approximation(prediction, "medium")
+    bert_result = calculate_bert_score(ground_truth, prediction)
+    
+    st.divider()
+    
+    # Summary cards
+    st.subheader("📈 Metric Scores Summary")
+    
+    cols = st.columns(5)
+    
+    with cols[0]:
+        st.metric("BLEU", f"{bleu_result['bleu']:.3f}")
+        st.caption(interpret_bleu_score(bleu_result['bleu']))
+    
+    with cols[1]:
+        st.metric("ROGUE-L", f"{rogue_result['rogueL']['f1']:.3f}")
+        st.caption(interpret_rogue_score(rogue_result['rogueL']['f1']))
+    
+    with cols[2]:
+        ppl = perplexity_result['perplexity']
+        st.metric("Perplexity", f"{ppl:.1f}")
+        st.caption(interpret_perplexity(ppl))
+    
+    with cols[3]:
+        # MRR placeholder for comparison (would need QA setup)
+        st.metric("MRR", "N/A")
+        st.caption("Needs QA format")
+    
+    with cols[4]:
+        st.metric("BERT Score", f"{bert_result['f1']:.3f}")
+        st.caption(interpret_bert_score(bert_result['f1']))
+    
+    # Radar chart
+    st.subheader("🎯 Metric Comparison Radar")
+    
+    # Normalize all to 0-1 scale
+    radar_data = {
+        "BLEU": bleu_result['bleu'],
+        "ROGUE-L": rogue_result['rogueL']['f1'],
+        "BERT Score": bert_result['f1'],
+        # Normalize perplexity (inverse, lower is better, cap at 100)
+        "Perplexity\n(inv)": max(0, 1 - perplexity_result['perplexity'] / 100)
+    }
+    
+    fig = create_radar_chart(radar_data, "All Metrics Comparison")
+    st.plotly_chart(fig, use_container_width=True)
+    
+    # Bar chart comparison
+    st.subheader("📊 Side-by-Side Comparison")
+    
+    bar_data = {
+        "BLEU": bleu_result['bleu'],
+        "ROGUE-1": rogue_result['rogue1']['f1'],
+        "ROGUE-L": rogue_result['rogueL']['f1'],
+        "ROGUE-2": rogue_result['rogue2']['f1'],
+        "BERT Score": bert_result['f1']
+    }
+    
+    fig_bar = create_bar_chart(bar_data, "Lexical & Semantic Metrics")
+    st.plotly_chart(fig_bar, use_container_width=True)
+    
+    # Detailed breakdown
+    st.subheader("📋 Detailed Metric Analysis")
+    
+    tab1, tab2, tab3, tab4 = st.tabs(["BLEU Details", "ROGUE Details", "Perplexity", "BERT Score"])
+    
+    with tab1:
+        st.markdown(f"**BLEU Score:** {bleu_result['bleu']:.4f}")
+        st.markdown(f"- Brevity Penalty: {bleu_result['brevity_penalty']:.4f}")
+        st.markdown(f"- Geo-Mean Precision: {bleu_result['geo_mean_precision']:.4f}")
+        st.markdown("**N-gram Precisions:**")
+        for i, p in enumerate(bleu_result['precisions'], 1):
+            st.markdown(f"- {i}-gram: {p:.4f}")
+    
+    with tab2:
+        st.markdown("**ROGUE Scores:**")
+        for name, result in rogue_result.items():
+            st.markdown(f"- {name}: F1={result['f1']:.4f}, P={result['precision']:.4f}, R={result['recall']:.4f}")
+    
+    with tab3:
+        ppl = perplexity_result['perplexity']
+        st.markdown(f"**Perplexity:** {ppl:.2f}")
+        st.markdown(f"- Cross-Entropy: {perplexity_result['cross_entropy']:.4f}")
+        st.markdown(f"- Tokens: {perplexity_result['num_tokens']}")
+        st.info(interpret_perplexity(ppl))
+    
+    with tab4:
+        st.markdown(f"**BERT Score F1:** {bert_result['f1']:.4f}")
+        st.markdown(f"- Cosine Similarity: {bert_result['cosine_similarity']:.4f}")
+        st.info(interpret_bert_score(bert_result['f1']))
+    
+    # Export section
+    st.subheader("💾 Export Results")
+    
+    import json
+    export_data = {
+        "ground_truth": ground_truth,
+        "prediction": prediction,
+        "metrics": {
+            "bleu": bleu_result['bleu'],
+            "rogue1": rogue_result['rogue1']['f1'],
+            "rogueL": rogue_result['rogueL']['f1'],
+            "perplexity": perplexity_result['perplexity'],
+            "bert_score": bert_result['f1']
+        }
+    }
+    
+    col_exp1, col_exp2 = st.columns(2)
+    
+    with col_exp1:
+        st.download_button(
+            "📥 Download JSON",
+            json.dumps(export_data, indent=2),
+            file_name="evaluation_results.json",
+            mime="application/json"
+        )
+    
+    with col_exp2:
+        # CSV export
+        import csv
+        import io
+        csv_buffer = io.StringIO()
+        writer = csv.writer(csv_buffer)
+        writer.writerow(["Metric", "Score"])
+        for metric, score in export_data["metrics"].items():
+            writer.writerow([metric, f"{score:.6f}"])
+        
+        st.download_button(
+            "📥 Download CSV",
+            csv_buffer.getvalue(),
+            file_name="evaluation_results.csv",
+            mime="text/csv"
+        )
+
+# Metric comparison table
+st.divider()
+show_metric_comparison_table()
+
+# Guide
+with st.expander("💡 How to Choose the Right Metric"):
+    st.markdown("""
+    **Quick Decision Guide:**
+    
+    | Task | Recommended Metric | Why |
+    |------|---------------------|-----|
+    | Machine Translation | **BLEU** | Industry standard, checks word-for-word accuracy |
+    | Summarization | **ROGUE** | Focuses on recall (covering key points) |
+    | Language Model | **Perplexity** | No reference needed, measures confidence |
+    | Question Answering | **MRR** | Evaluates ranking quality |
+    | Paraphrase Detection | **BERT Score** | Captures semantic similarity |
+    | General Generation | **All 3 (BLEU+ROGUE+BERT)** | Covers lexical + semantic |
+    
+    **Pro Tip:** Use multiple metrics! A high BLEU but low BERT Score suggests 
+    the model is copying words without understanding meaning.
+    """)

pages/02_bleu_score.py

@@ -0,0 +1,140 @@
+"""BLEU Score evaluation page."""
+
+import streamlit as st
+import sys
+sys.path.append('/Users/mymac/Documents/applyjob/supportProjects/llm-evaluation-dashboard')
+
+from modules.metrics.bleu import calculate_bleu, get_matching_ngrams_detailed, interpret_bleu_score
+from modules.visualizations.charts import create_ngram_precision_chart, create_gauge_chart
+from modules.visualizations.explanations import create_formula_expander
+from modules.utils.examples import get_text_example_names, get_text_example
+from modules.utils.text_processing import tokenize, get_ngrams
+
+st.set_page_config(page_title="BLEU Score", page_icon="🔵", layout="wide")
+
+st.title("🔵 BLEU Score Evaluation")
+
+st.markdown("""
+**Bilingual Evaluation Understudy** — Measures n-gram precision with brevity penalty.
+Best for: **Machine Translation** evaluation.
+""")
+
+# Input section
+col1, col2 = st.columns(2)
+
+with col1:
+    st.subheader("📄 Ground Truth (Reference)")
+    example_name = st.selectbox("Choose example:", ["Custom"] + get_text_example_names())
+    
+    if example_name != "Custom":
+        example = get_text_example(example_name)
+        ground_truth = st.text_area("Reference text:", value=example.ground_truth, height=100)
+        st.caption(f"Example: {example.description}")
+    else:
+        ground_truth = st.text_area("Reference text:", 
+                                    value="The cat sat on the mat and looked outside",
+                                    height=100)
+
+with col2:
+    st.subheader("🤖 Model Prediction (Candidate)")
+    if example_name != "Custom":
+        prediction = st.text_area("Candidate text:", value=example.prediction, height=100)
+    else:
+        prediction = st.text_area("Candidate text:", 
+                                  value="The cat sat on the mat",
+                                  height=100)
+
+# Calculate button
+if st.button("🧮 Calculate BLEU Score", type="primary"):
+    result = calculate_bleu(ground_truth, prediction)
+    
+    # Display main score
+    st.divider()
+    
+    score_col, interp_col = st.columns([1, 2])
+    
+    with score_col:
+        st.plotly_chart(create_gauge_chart(result['bleu'], "BLEU Score"), use_container_width=True)
+    
+    with interp_col:
+        st.subheader("📊 Score Interpretation")
+        st.markdown(f"**Score: {result['bleu']:.4f}**")
+        st.markdown(f"**Quality: {interpret_bleu_score(result['bleu'])}**")
+        
+        # Components
+        st.markdown(f"- **Brevity Penalty:** {result['brevity_penalty']:.4f}")
+        st.markdown(f"- **Geo-Mean Precision:** {result['geo_mean_precision']:.4f}")
+        st.markdown(f"- **Reference Length:** {result['ref_length']} tokens")
+        st.markdown(f"- **Candidate Length:** {result['cand_length']} tokens")
+    
+    # N-gram precision breakdown
+    st.subheader("📈 N-gram Precision Breakdown")
+    
+    chart_col, detail_col = st.columns([2, 1])
+    
+    with chart_col:
+        fig = create_ngram_precision_chart(
+            result['precisions'],
+            result['clipped_counts'],
+            result['total_counts']
+        )
+        st.plotly_chart(fig, use_container_width=True)
+    
+    with detail_col:
+        st.markdown("**Precision Details:**")
+        for i, (p, clipped, total) in enumerate(zip(
+            result['precisions'], 
+            result['clipped_counts'], 
+            result['total_counts']
+        ), 1):
+            st.markdown(f"**{i}-gram:** {p:.4f}")
+            st.caption(f"Matches: {clipped}/{total}")
+    
+    # Detailed matching
+    st.subheader("🔍 Detailed N-gram Matching")
+    
+    tab1, tab2, tab3, tab4 = st.tabs(["1-gram", "2-gram", "3-gram", "4-gram"])
+    
+    tabs = [tab1, tab2, tab3, tab4]
+    for n, tab in enumerate(tabs, 1):
+        with tab:
+            details = get_matching_ngrams_detailed(ground_truth, prediction, n)
+            
+            col_a, col_b = st.columns(2)
+            
+            with col_a:
+                st.markdown(f"**{n}-grams in Reference:**")
+                for gram in details['ref_ngrams'][:10]:
+                    st.markdown(f"- {' '.join(gram)}")
+                if len(details['ref_ngrams']) > 10:
+                    st.caption(f"... and {len(details['ref_ngrams']) - 10} more")
+            
+            with col_b:
+                st.markdown(f"**Matched {n}-grams:**")
+                for match in details['matches'][:10]:
+                    st.markdown(f"- {' '.join(match['ngram'])} " +
+                              f"(ref: {match['reference_count']}, cand: {match['candidate_count']})")
+                
+                if details['over_matches']:
+                    st.markdown("**Over-generated:**")
+                    for over in details['over_matches'][:5]:
+                        st.markdown(f"- {' '.join(over['ngram'])} " +
+                                  f"(excess: {over['excess']})")
+
+# Formula section
+create_formula_expander('bleu')
+
+# Additional info
+st.divider()
+with st.expander("💡 Understanding BLEU Score"):
+    st.markdown("""
+    **Why BLEU works for translation:**
+    1. **N-gram precision** ensures word choice accuracy
+    2. **Brevity penalty** prevents overly short outputs
+    3. **Multiple n-gram sizes** capture fluency (1-gram = content, 4-gram = fluency)
+    
+    **Limitations:**
+    - Doesn't capture semantic meaning (synonyms score low)
+    - Sensitive to word order changes
+    - Requires reference text
+    """)

pages/03_rogue_score.py

@@ -0,0 +1,195 @@
+"""ROGUE Score evaluation page."""
+
+import streamlit as st
+import sys
+sys.path.append('/Users/mymac/Documents/applyjob/supportProjects/llm-evaluation-dashboard')
+
+from modules.metrics.rogue import calculate_all_rogue, calculate_rogue_l, interpret_rogue_score
+from modules.visualizations.charts import create_bar_chart, create_gauge_chart
+from modules.visualizations.explanations import create_formula_expander
+from modules.utils.examples import get_text_example_names, get_text_example
+
+st.set_page_config(page_title="ROGUE Score", page_icon="🔴", layout="wide")
+
+st.title("🔴 ROGUE Score Evaluation")
+
+st.markdown("""
+**Recall-Oriented Understudy for Gisting Evaluation** — Focuses on recall, not precision.
+Best for: **Text Summarization** evaluation.
+""")
+
+# Variant selector
+variant = st.selectbox(
+    "Select ROGUE Variant:",
+    ["All Variants", "ROGUE-1 (Unigram)", "ROGUE-2 (Bigram)", "ROGUE-L (LCS)", 
+     "ROGUE-S (Skip-bigram)", "ROGUE-SU (Skip + Unigram)", "ROGUE-W (Weighted LCS)"]
+)
+
+# Input section
+col1, col2 = st.columns(2)
+
+with col1:
+    st.subheader("📄 Ground Truth (Reference)")
+    example_name = st.selectbox("Choose example:", ["Custom"] + get_text_example_names(), key="rogue_example")
+    
+    if example_name != "Custom":
+        example = get_text_example(example_name)
+        ground_truth = st.text_area("Reference text:", value=example.ground_truth, height=150, key="rogue_ref")
+        st.caption(f"Example: {example.description}")
+    else:
+        ground_truth = st.text_area("Reference text:", 
+                                    value="The cat sat on the mat and looked outside at the birds.",
+                                    height=150, key="rogue_ref")
+
+with col2:
+    st.subheader("🤖 Model Prediction (Candidate)")
+    if example_name != "Custom":
+        prediction = st.text_area("Candidate text:", value=example.prediction, height=150, key="rogue_cand")
+    else:
+        prediction = st.text_area("Candidate text:", 
+                                  value="The cat sat on the mat and looked outside.",
+                                  height=150, key="rogue_cand")
+
+# Calculate button
+if st.button("🧮 Calculate ROGUE Score", type="primary"):
+    results = calculate_all_rogue(ground_truth, prediction)
+    
+    st.divider()
+    
+    # Display based on selected variant
+    if variant == "All Variants":
+        st.subheader("📊 All ROGUE Variants Comparison")
+        
+        # Create comparison data
+        comparison_data = {
+            "ROGUE-1": results['rogue1']['f1'],
+            "ROGUE-2": results['rogue2']['f1'],
+            "ROGUE-L": results['rogueL']['f1'],
+            "ROGUE-S": results['rogueS']['f1'],
+            "ROGUE-SU": results['rogueSU']['f1'],
+            "ROGUE-W": results['rogueW']['f1']
+        }
+        
+        col_chart, col_table = st.columns([2, 1])
+        
+        with col_chart:
+            fig = create_bar_chart(comparison_data, "ROGUE F1 Scores Comparison")
+            st.plotly_chart(fig, use_container_width=True)
+        
+        with col_table:
+            st.markdown("**F1 Scores:**")
+            for name, score in comparison_data.items():
+                st.markdown(f"**{name}:** {score:.4f}")
+            
+            st.markdown("---")
+            st.caption("ROGUE-N: N-gram recall")
+            st.caption("ROGUE-L: LCS-based (word order)")
+            st.caption("ROGUE-S: Skip-bigrams")
+            st.caption("ROGUE-SU: S + Unigrams")
+            st.caption("ROGUE-W: Weighted consecutive matches")
+    
+    else:
+        # Display single variant
+        variant_map = {
+            "ROGUE-1 (Unigram)": ('rogue1', results['rogue1']),
+            "ROGUE-2 (Bigram)": ('rogue2', results['rogue2']),
+            "ROGUE-L (LCS)": ('rogueL', results['rogueL']),
+            "ROGUE-S (Skip-bigram)": ('rogueS', results['rogueS']),
+            "ROGUE-SU (Skip + Unigram)": ('rogueSU', results['rogueSU']),
+            "ROGUE-W (Weighted LCS)": ('rogueW', results['rogueW'])
+        }
+        
+        key, result = variant_map[variant]
+        
+        col_gauge, col_details = st.columns([1, 2])
+        
+        with col_gauge:
+            st.plotly_chart(create_gauge_chart(result['f1'], f"{variant} F1"), use_container_width=True)
+        
+        with col_details:
+            st.subheader(f"📊 {variant} Details")
+            st.markdown(f"**F1 Score:** {result['f1']:.4f}")
+            st.markdown(f"**Quality:** {interpret_rogue_score(result['f1'])}")
+            st.markdown(f"- **Precision:** {result['precision']:.4f}")
+            st.markdown(f"- **Recall:** {result['recall']:.4f}")
+            
+            # Variant-specific details
+            if key == 'rogueL' and 'lcs' in result:
+                st.markdown(f"- **LCS Length:** {result['lcs_length']} tokens")
+                st.markdown(f"- **LCS:** {' '.join(result['lcs'][:10])}")
+            elif key in ['rogue1', 'rogue2', 'rogueS'] and 'matches' in result:
+                st.markdown(f"- **Matches:** {result['matches']} n-grams")
+    
+    # ROGUE-L LCS Visualization (special case)
+    if variant in ["All Variants", "ROGUE-L (LCS)"]:
+        st.subheader("🔍 ROGUE-L: Longest Common Subsequence Visualization")
+        
+        rogue_l = results['rogueL']
+        
+        if 'lcs' in rogue_l and rogue_l['lcs']:
+            st.markdown("**LCS (Longest Common Subsequence):**")
+            st.markdown(f"### {' → '.join(rogue_l['lcs'])}")
+            
+            st.caption(f"""
+            This sequence appears in both texts in the same order (but not necessarily consecutively).
+            Length: {rogue_l['lcs_length']} tokens out of {rogue_l['ref_length']} reference tokens.
+            Recall = {rogue_l['lcs_length']}/{rogue_l['ref_length']} = {rogue_l['recall']:.4f}
+            """)
+            
+            # Visual alignment
+            st.markdown("**Visual Alignment:**")
+            
+            ref_tokens = ground_truth.split()
+            cand_tokens = prediction.split()
+            lcs_tokens = rogue_l['lcs']
+            
+            # Mark matching tokens
+            ref_highlighted = []
+            cand_highlighted = []
+            
+            lcs_idx = 0
+            for token in ref_tokens:
+                if lcs_idx < len(lcs_tokens) and token.lower() == lcs_tokens[lcs_idx].lower():
+                    ref_highlighted.append(f"**{token}**")
+                    lcs_idx += 1
+                else:
+                    ref_highlighted.append(token)
+            
+            lcs_idx = 0
+            for token in cand_tokens:
+                if lcs_idx < len(lcs_tokens) and token.lower() == lcs_tokens[lcs_idx].lower():
+                    cand_highlighted.append(f"**{token}**")
+                    lcs_idx += 1
+                else:
+                    cand_highlighted.append(token)
+            
+            col_ref, col_cand = st.columns(2)
+            with col_ref:
+                st.markdown("**Reference:**")
+                st.markdown(" ".join(ref_highlighted))
+            with col_cand:
+                st.markdown("**Candidate:**")
+                st.markdown(" ".join(cand_highlighted))
+            
+            st.caption("**Bold** = part of LCS")
+
+# Formula section
+create_formula_expander('rogue')
+
+# Additional info
+st.divider()
+with st.expander("💡 Understanding ROGUE vs BLEU"):
+    st.markdown("""
+    | Aspect | BLEU | ROGUE |
+    |--------|------|-------|
+    | **Focus** | Precision | Recall |
+    | **Penalizes** | Over-generation | Under-generation |
+    | **Best for** | Translation | Summarization |
+    | **N-grams** | Multiple (1-4) | Usually 1-2 |
+    | **Word Order** | Strict | Flexible (ROGUE-L) |
+    
+    **When to use ROGUE:**
+    - Summarization: You want to ensure all key points are covered (recall)
+    - Allow some flexibility in phrasing
+    - Don't want to penalize synonyms heavily
+    """)

pages/04_perplexity.py

@@ -0,0 +1,160 @@
+"""Perplexity evaluation page."""
+
+import streamlit as st
+import sys
+sys.path.append('/Users/mymac/Documents/applyjob/supportProjects/llm-evaluation-dashboard')
+
+from modules.metrics.perplexity import calculate_perplexity_approximation, interpret_perplexity, get_perplexity_grade
+from modules.visualizations.charts import create_token_probability_chart, create_gauge_chart
+from modules.visualizations.explanations import create_formula_expander
+
+st.set_page_config(page_title="Perplexity", page_icon="🤔", layout="wide")
+
+st.title("🤔 Perplexity Evaluation")
+
+st.markdown("""
+**Model Confidence Metric** — Measures how "confused" the model is when generating text.
+Lower is better. No ground truth needed!
+
+Best for: **Language Model Quality** assessment.
+""")
+
+# Input section
+st.subheader("📝 Input Text for Perplexity Calculation")
+
+# Model confidence selector
+confidence_level = st.select_slider(
+    "Simulate Model Confidence Level:",
+    options=["Low (Confused)", "Medium", "High (Confident)"],
+    value="Medium"
+)
+
+confidence_map = {
+    "Low (Confused)": "low",
+    "Medium": "medium", 
+    "High (Confident)": "high"
+}
+
+# Text input
+text_input = st.text_area(
+    "Enter text to analyze:",
+    value="The cat sat on the mat and looked outside at the birds flying in the sky.",
+    height=100
+)
+
+# Example presets
+col1, col2, col3 = st.columns(3)
+with col1:
+    if st.button("📖 Fluent Text"):
+        text_input = "The quick brown fox jumps over the lazy dog in the garden."
+        confidence_level = "High (Confident)"
+        st.rerun()
+
+with col2:
+    if st.button("🔀 Mixed Quality"):
+        text_input = "The cat sat on mat and looked birds flying sky."
+        confidence_level = "Medium"
+        st.rerun()
+
+with col3:
+    if st.button("🌀 Nonsensical"):
+        text_input = "Zxq sat mat looked birds quantum flying sky purple."
+        confidence_level = "Low (Confused)"
+        st.rerun()
+
+# Calculate button
+if st.button("🧮 Calculate Perplexity", type="primary"):
+    result = calculate_perplexity_approximation(text_input, confidence_map[confidence_level])
+    
+    st.divider()
+    
+    # Main display
+    col_gauge, col_info = st.columns([1, 2])
+    
+    with col_gauge:
+        # Normalize for gauge (perplexity can be > 1)
+        ppl = result['perplexity']
+        gauge_value = min(ppl / 100, 1.0)  # Cap at 100 for display
+        st.plotly_chart(create_gauge_chart(gauge_value, f"Perplexity: {ppl:.2f}", 0, 1), use_container_width=True)
+    
+    with col_info:
+        st.subheader("📊 Perplexity Analysis")
+        
+        # Grade and interpretation
+        grade = get_perplexity_grade(ppl)
+        interpretation = interpret_perplexity(ppl)
+        
+        col_a, col_b = st.columns(2)
+        with col_a:
+            st.metric("Perplexity", f"{ppl:.2f}")
+            st.metric("Grade", grade)
+        with col_b:
+            st.metric("Cross-Entropy", f"{result['cross_entropy']:.3f}")
+            st.metric("Avg Log-Prob", f"{result['avg_log_prob']:.3f}")
+        
+        st.info(f"**Interpretation:** {interpretation}")
+    
+    # Token-level breakdown
+    st.subheader("📈 Token-Level Perplexity Breakdown")
+    
+    if result['token_details']:
+        fig = create_token_probability_chart(result['token_details'])
+        st.plotly_chart(fig, use_container_width=True)
+        
+        # Token table
+        with st.expander("📋 Token Details Table"):
+            token_data = []
+            for detail in result['token_details']:
+                token_data.append({
+                    'Token': detail.get('token', 'N/A'),
+                    'Probability': f"{detail['probability']:.4f}",
+                    'Log-Prob': f"{detail['log_probability']:.4f}",
+                    'Perplexity': f"{detail['perplexity_contrib']:.2f}"
+                })
+            
+            st.table(token_data)
+    
+    # Educational section
+    st.subheader("🎓 Understanding the Calculation")
+    
+    col_calc, col_interpret = st.columns(2)
+    
+    with col_calc:
+        st.markdown("**Step-by-Step:**")
+        st.markdown(f"""
+        1. **Tokenize:** {result['num_tokens']} tokens
+        2. **Get Probabilities:** P(token_i | previous tokens)
+        3. **Log Transform:** log(P) for numerical stability
+        4. **Average:** Mean of log probabilities
+        5. **Exponentiate:** exp(-mean) = **{ppl:.2f}**
+        """)
+    
+    with col_interpret:
+        st.markdown("**What this means:**")
+        st.markdown(f"""
+        - At each step, the model had ~**{ppl:.0f}** choices
+        - Lower = more confident predictions
+        - Ideal: 1 (perfect prediction)
+        - Typical good LM: 10-50
+        - Random guessing: ~vocab_size (10k-100k)
+        """)
+
+# Formula section
+create_formula_expander('perplexity')
+
+# Additional info
+st.divider()
+with st.expander("💡 Perplexity vs Other Metrics"):
+    st.markdown("""
+    | Feature | Perplexity | BLEU/ROGUE |
+    |---------|------------|------------|
+    | **Needs Reference** | ❌ No | ✅ Yes |
+    | **Measures** | Model confidence | Text similarity |
+    | **Best for** | LM evaluation | Generation quality |
+    | **Direction** | Lower is better | Higher is better |
+    | **Range** | [1, ∞) | [0, 1] |
+    
+    **Key Insight:**
+    Perplexity measures how well the model **predicts** the text, not how similar it is to a reference.
+    A fluent, grammatical text can have low perplexity even if it says something completely different!
+    """)

pages/05_mrr.py

@@ -0,0 +1,204 @@
+"""Mean Reciprocal Rank (MRR) evaluation page."""
+
+import streamlit as st
+import sys
+sys.path.append('/Users/mymac/Documents/applyjob/supportProjects/llm-evaluation-dashboard')
+
+from modules.metrics.mrr import calculate_mrr, calculate_reciprocal_rank, interpret_mrr, get_mrr_grade
+from modules.visualizations.charts import create_ranking_visualization, create_gauge_chart
+from modules.visualizations.explanations import create_formula_expander
+from modules.utils.examples import get_mrr_example_names, get_mrr_example
+
+st.set_page_config(page_title="MRR", page_icon="📊", layout="wide")
+
+st.title("📊 Mean Reciprocal Rank (MRR)")
+
+st.markdown("""
+**Ranking Quality Metric** — Measures how well a model ranks the correct answer.
+Best for: **Question Answering** and **Information Retrieval** systems.
+""")
+
+# Mode selector
+mode = st.radio("Evaluation Mode:", ["Single Query", "Multiple Queries (Batch)"])
+
+if mode == "Single Query":
+    # Single query input
+    st.subheader("📝 Single Query Evaluation")
+    
+    # Example selector
+    example_name = st.selectbox("Choose example:", ["Custom"] + get_mrr_example_names())
+    
+    if example_name != "Custom":
+        example = get_mrr_example(example_name)
+        question = st.text_input("Question:", value=example.get("question", ""))
+        correct_answer = st.text_input("Correct Answer:", value=example.get("correct_answer", ""))
+        default_ranked = "\n".join(example.get("ranked_answers", []))
+        st.caption(f"Example: {example.get('description', '')}")
+    else:
+        question = st.text_input("Question:", value="What is the capital of France?")
+        correct_answer = st.text_input("Correct Answer:", value="Paris")
+        default_ranked = "London\nParis\nBerlin\nMadrid"
+    
+    # Ranked answers input
+    st.markdown("**Ranked Answers (one per line, best first):**")
+    ranked_input = st.text_area("", value=default_ranked, height=150)
+    ranked_answers = [line.strip() for line in ranked_input.split("\n") if line.strip()]
+    
+    if st.button("🧮 Calculate RR", type="primary"):
+        result = calculate_reciprocal_rank(ranked_answers, correct_answer)
+        
+        st.divider()
+        
+        col_gauge, col_details = st.columns([1, 2])
+        
+        with col_gauge:
+            rr = result['reciprocal_rank']
+            st.plotly_chart(create_gauge_chart(rr, "Reciprocal Rank"), use_container_width=True)
+        
+        with col_details:
+            st.subheader("📊 Query Results")
+            
+            if result['found']:
+                st.success(f"✅ Correct answer found at position **#{result['rank']}**")
+                st.markdown(f"**Reciprocal Rank:** {rr:.4f}")
+                grade = get_mrr_grade(rr)
+                st.markdown(f"**Grade:** {grade}")
+                st.markdown(f"**Quality:** {interpret_mrr(rr)}")
+            else:
+                st.error(f"❌ Correct answer '{correct_answer}' not found in top {len(ranked_answers)}")
+                st.markdown("**Reciprocal Rank:** 0.0")
+        
+        # Ranking visualization
+        st.subheader("🔍 Answer Ranking Visualization")
+        
+        ranked_items = [
+            {"rank": i+1, "answer": ans, "is_correct": ans.lower() == correct_answer.lower()}
+            for i, ans in enumerate(ranked_answers)
+        ]
+        
+        if ranked_items:
+            fig = create_ranking_visualization(ranked_items, correct_answer)
+            st.plotly_chart(fig, use_container_width=True)
+        
+        # Show the list
+        st.markdown("**Ranked List:**")
+        for i, answer in enumerate(ranked_answers, 1):
+            is_correct = answer.lower() == correct_answer.lower()
+            icon = "✅" if is_correct else f"{i}."
+            score = f"(RR: {1.0/i:.4f})" if is_correct else ""
+            st.markdown(f"{icon} **{answer}** {score}")
+
+else:
+    # Batch mode
+    st.subheader("📝 Batch Query Evaluation")
+    
+    st.markdown("Enter multiple queries as JSON or use preset:")
+    
+    preset = st.selectbox("Preset batch:", ["Custom", "Mixed Quality", "All Perfect", "All Poor"])
+    
+    if preset == "Mixed Quality":
+        default_json = '''[
+  {"question": "Capital of France?", "ranked_answers": ["Paris", "London", "Berlin"], "correct_answer": "Paris"},
+  {"question": "Capital of Japan?", "ranked_answers": ["Beijing", "Tokyo", "Seoul"], "correct_answer": "Tokyo"},
+  {"question": "Capital of UK?", "ranked_answers": ["London", "Paris", "Berlin"], "correct_answer": "London"},
+  {"question": "Capital of Italy?", "ranked_answers": ["Madrid", "Rome", "Paris"], "correct_answer": "Rome"}
+]'''
+    elif preset == "All Perfect":
+        default_json = '''[
+  {"question": "Q1", "ranked_answers": ["A", "B", "C"], "correct_answer": "A"},
+  {"question": "Q2", "ranked_answers": ["X", "Y", "Z"], "correct_answer": "X"},
+  {"question": "Q3", "ranked_answers": ["Yes", "No", "Maybe"], "correct_answer": "Yes"}
+]'''
+    elif preset == "All Poor":
+        default_json = '''[
+  {"question": "Q1", "ranked_answers": ["A", "B", "C"], "correct_answer": "D"},
+  {"question": "Q2", "ranked_answers": ["X", "Y", "Z"], "correct_answer": "W"}
+]'''
+    else:
+        default_json = '[\n  {"question": "Q1", "ranked_answers": ["A", "B"], "correct_answer": "A"}\n]'
+    
+    json_input = st.text_area("Queries (JSON array):", value=default_json, height=200)
+    
+    if st.button("🧮 Calculate MRR", type="primary"):
+        try:
+            import json
+            queries = json.loads(json_input)
+            result = calculate_mrr(queries)
+            
+            st.divider()
+            
+            # Summary metrics
+            col1, col2, col3, col4 = st.columns(4)
+            with col1:
+                st.metric("MRR", f"{result['mrr']:.4f}")
+            with col2:
+                st.metric("Top-1 Accuracy", f"{result['top1_accuracy']:.1%}")
+            with col3:
+                st.metric("Top-3 Accuracy", f"{result['top3_accuracy']:.1%}")
+            with col4:
+                st.metric("Found Rate", f"{result['found_rate']:.1%}")
+            
+            # Interpretation
+            st.info(f"**Overall Quality:** {interpret_mrr(result['mrr'])}")
+            
+            # Query details
+            st.subheader("📋 Query Details")
+            
+            for detail in result['query_details']:
+                with st.expander(f"Q: {detail['question'][:50]}... (RR: {detail['reciprocal_rank']:.4f})"):
+                    st.markdown(f"**Question:** {detail['question']}")
+                    st.markdown(f"**Correct Answer:** {detail['correct_answer']}")
+                    
+                    if detail['found']:
+                        st.markdown(f"**Rank:** #{detail['rank']}")
+                        st.markdown(f"**Reciprocal Rank:** {detail['reciprocal_rank']:.4f}")
+                    else:
+                        st.markdown("**Status:** Not found in ranked list")
+                    
+                    st.markdown("**Top Rankings:**")
+                    for i, ans in enumerate(detail['ranked_answers'][:5], 1):
+                        is_correct = ans.lower() == detail['correct_answer'].lower()
+                        icon = "✅" if is_correct else f"{i}."
+                        st.markdown(f"{icon} {ans}")
+            
+            # Bar chart of RR scores
+            st.subheader("📊 Reciprocal Rank Distribution")
+            
+            import plotly.graph_objects as go
+            fig = go.Figure(data=[go.Bar(
+                x=[f"Q{i+1}" for i in range(len(result['reciprocal_ranks']))],
+                y=result['reciprocal_ranks'],
+                text=[f'{rr:.3f}' for rr in result['reciprocal_ranks']],
+                textposition='auto',
+                marker_color=['green' if rr > 0 else 'red' for rr in result['reciprocal_ranks']]
+            )])
+            fig.update_layout(
+                title="Reciprocal Rank per Query",
+                yaxis=dict(title="Reciprocal Rank", range=[0, 1.1]),
+                xaxis_title="Query"
+            )
+            st.plotly_chart(fig, use_container_width=True)
+            
+        except Exception as e:
+            st.error(f"Error parsing JSON: {e}")
+
+# Formula section
+create_formula_expander('mrr')
+
+# Additional info
+st.divider()
+with st.expander("💡 When to Use MRR"):
+    st.markdown("""
+    **MRR is ideal for:**
+    - **Question Answering**: Does the system rank the correct answer highly?
+    - **Search Engines**: Are relevant results in the top positions?
+    - **Recommendation Systems**: Is the relevant item recommended early?
+    
+    **vs Accuracy:**
+    - Accuracy: "Is the first answer correct?" (harsh)
+    - MRR: "How high is the correct answer ranked?" (nuanced)
+    
+    **Example:**
+    - Top-1 Accuracy of 60% means 60% of queries have correct answer at #1
+    - MRR of 0.6 means on average, correct answer is at position ~1.67
+    """)

pages/06_bert_score.py

@@ -0,0 +1,161 @@
+"""BERT Score evaluation page."""
+
+import streamlit as st
+import sys
+sys.path.append('/Users/mymac/Documents/applyjob/supportProjects/llm-evaluation-dashboard')
+
+from modules.metrics.bert_score import calculate_bert_score, calculate_token_level_similarity, interpret_bert_score, get_bert_score_grade
+from modules.visualizations.charts import create_heatmap, create_gauge_chart
+from modules.visualizations.explanations import create_formula_expander
+from modules.utils.examples import get_text_example_names, get_text_example
+
+st.set_page_config(page_title="BERT Score", page_icon="🤖", layout="wide")
+
+st.title("🤖 BERT Score Evaluation")
+
+st.markdown("""
+**Semantic Similarity via Embeddings** — Uses contextual embeddings to measure meaning similarity.
+Best for: **Paraphrase Detection** and **Semantic Quality** assessment.
+""")
+
+# Input section
+col1, col2 = st.columns(2)
+
+with col1:
+    st.subheader("📄 Ground Truth (Reference)")
+    example_name = st.selectbox("Choose example:", ["Custom"] + get_text_example_names(), key="bert_example")
+    
+    if example_name != "Custom":
+        example = get_text_example(example_name)
+        ground_truth = st.text_area("Reference text:", value=example.ground_truth, height=150, key="bert_ref")
+        st.caption(f"Example: {example.description}")
+    else:
+        ground_truth = st.text_area("Reference text:", 
+                                    value="The cat sat on the mat and looked outside.",
+                                    height=150, key="bert_ref")
+
+with col2:
+    st.subheader("🤖 Model Prediction (Candidate)")
+    if example_name != "Custom":
+        prediction = st.text_area("Candidate text:", value=example.prediction, height=150, key="bert_cand")
+    else:
+        prediction = st.text_area("Candidate text:", 
+                                  value="The cat was sitting on the mat and gazing outdoors.",
+                                  height=150, key="bert_cand")
+
+# Calculate button
+if st.button("🧮 Calculate BERT Score", type="primary"):
+    result = calculate_bert_score(ground_truth, prediction)
+    
+    st.divider()
+    
+    # Main score display
+    col_gauge, col_info = st.columns([1, 2])
+    
+    with col_gauge:
+        st.plotly_chart(create_gauge_chart(result['f1'], "BERT Score F1"), use_container_width=True)
+    
+    with col_info:
+        st.subheader("📊 Semantic Similarity Analysis")
+        
+        f1 = result['f1']
+        grade = get_bert_score_grade(f1)
+        interpretation = interpret_bert_score(f1)
+        
+        st.markdown(f"**F1 Score:** {f1:.4f}")
+        st.markdown(f"**Grade:** {grade}")
+        st.markdown(f"**Quality:** {interpretation}")
+        st.markdown(f"**Cosine Similarity:** {result['cosine_similarity']:.4f}")
+        
+        if not result.get('is_real_model', False):
+            st.caption(result.get('note', ''))
+    
+    # Token-level analysis
+    st.subheader("🔍 Token-Level Semantic Alignment")
+    
+    token_result = calculate_token_level_similarity(ground_truth, prediction)
+    
+    if token_result['ref_tokens'] and token_result['cand_tokens']:
+        # Heatmap
+        st.markdown("**Similarity Matrix (Token-to-Token):**")
+        
+        # Limit size for readability
+        max_display = min(15, len(token_result['ref_tokens']), len(token_result['cand_tokens']))
+        
+        matrix_subset = [row[:max_display] for row in token_result['similarity_matrix'][:max_display]]
+        ref_labels = token_result['ref_tokens'][:max_display]
+        cand_labels = token_result['cand_tokens'][:max_display]
+        
+        fig = create_heatmap(matrix_subset, cand_labels, ref_labels, "Token Similarity Matrix")
+        st.plotly_chart(fig, use_container_width=True)
+        
+        # Best matches
+        st.markdown("**Best Token Matches:**")
+        
+        matches = token_result['matches']
+        if matches:
+            for match in matches[:10]:
+                sim_pct = match['similarity'] * 100
+                st.markdown(f"- **{match['ref_token']}** ↔ **{match['cand_token']}**: {sim_pct:.1f}% similar")
+        else:
+            st.warning("No significant token matches found (threshold: 30%)")
+        
+        # Precision/Recall breakdown
+        st.subheader("📈 Precision vs Recall Breakdown")
+        
+        col_p, col_r = st.columns(2)
+        with col_p:
+            st.metric("Precision", f"{token_result['precision']:.4f}")
+            st.caption("Avg best match from candidate → reference")
+        with col_r:
+            st.metric("Recall", f"{token_result['recall']:.4f}")
+            st.caption("Avg best match from reference → candidate")
+    
+    # Comparison with lexical metrics
+    st.subheader("🔄 Why BERT Score is Different")
+    
+    col_lex, col_sem = st.columns(2)
+    
+    with col_lex:
+        st.markdown("**Lexical Metrics (BLEU/ROGUE):**")
+        st.markdown("""
+        - "sat" ≠ "was sitting" ❌
+        - "looked" ≠ "gazing" ❌
+        - "outside" ≠ "outdoors" ❌
+        - **Score: Low** (different words)
+        """)
+    
+    with col_sem:
+        st.markdown("**BERT Score (Semantic):**")
+        st.markdown("""
+        - "sat" ≈ "was sitting" ✅
+        - "looked" ≈ "gazing" ✅
+        - "outside" ≈ "outdoors" ✅
+        - **Score: High** (same meaning)
+        """)
+
+# Formula section
+create_formula_expander('bert_score')
+
+# Additional info
+st.divider()
+with st.expander("💡 BERT Score Advantages"):
+    st.markdown("""
+    **Why use BERT Score over BLEU/ROGUE?**
+    
+    | Scenario | BLEU/ROGUE | BERT Score |
+    |----------|------------|------------|
+    | "happy" vs "joyful" | Low | **High** ✅ |
+    | "car" vs "automobile" | Low | **High** ✅ |
+    | "run fast" vs "sprint" | Low | **High** ✅ |
+    | Paraphrases | Low | **High** ✅ |
+    | Word-for-word match | High | High |
+    
+    **How it works:**
+    1. Convert each token to contextual embedding (768-dim vector)
+    2. Calculate cosine similarity between all token pairs
+    3. Greedy matching: each token matches to most similar counterpart
+    4. Average similarities = Precision/Recall
+    
+    **Note:** This demo uses simplified embeddings. Real BERT Score uses pre-trained BERT.
+    """)

plan.md

@@ -0,0 +1,160 @@
+# LLM Evaluation Metrics Dashboard
+
+A comprehensive Streamlit-based educational dashboard demonstrating 5 key LLM evaluation metrics (BLEU, ROGUE, Perplexity, MRR, BERT Score) with interactive visualizations and mathematical explanations.
+
+## Project Structure
+
+```
+llm-evaluation-dashboard/
+├── app.py                          # Main entry point with page routing
+├── pages/
+│   ├── 01_overview.py              # Comparison dashboard (all metrics)
+│   ├── 02_bleu_score.py            # BLEU detailed page
+│   ├── 03_rogue_score.py           # ROGUE detailed page
+│   ├── 04_perplexity.py            # Perplexity detailed page
+│   ├── 05_mrr.py                   # MRR detailed page
+│   └── 06_bert_score.py            # BERT Score detailed page
+├── modules/
+│   ├── metrics/
+│   │   ├── __init__.py
+│   │   ├── bleu.py                 # BLEU implementation with n-gram precision
+│   │   ├── rogue.py                # ROGUE variants (N, L, S, SU, W)
+│   │   ├── perplexity.py           # Perplexity calculation
+│   │   ├── mrr.py                  # Mean Reciprocal Rank
+│   │   └── bert_score.py           # BERT-based similarity
+│   ├── visualizations/
+│   │   ├── __init__.py
+│   │   ├── charts.py               # Plotly charts for metrics
+│   │   └── explanations.py         # Mathematical formula displays
+│   └── utils/
+│       ├── __init__.py
+│       ├── text_processing.py      # Tokenization helpers
+│       └── examples.py             # Sample ground truth/prediction pairs
+├── data/
+│   └── sample_evaluations.json     # Pre-loaded test cases
+├── requirements.txt
+└── README.md
+```
+
+## Key Features
+
+### 1. Overview Page (Comparison Dashboard)
+- Side-by-side input for Ground Truth vs Predicted text
+- Radar chart showing all 5 metrics simultaneously
+- Metric cards with scores and grade interpretation
+- Export results to JSON/CSV
+
+### 2. Individual Metric Pages (Educational Focus)
+Each page includes:
+- **Interactive Calculator**: Input custom text, see real-time score
+- **Step-by-Step Breakdown**: Visual walkthrough of calculation
+- **Mathematical Formula**: LaTeX-rendered equations
+- **Visual Explanations**: Color-coded n-gram matching, alignment matrices
+- **Preset Examples**: 3-4 curated examples demonstrating edge cases
+
+## Metric Implementations
+
+### BLEU Score
+- **Features**: N-gram precision (1-4), brevity penalty visualization
+- **UI**: Highlight matching n-grams, show precision@N breakdown
+- **Formula**: `BP × exp(Σ w_n × log(p_n))`
+
+### ROGUE Score (5 Variants)
+- **ROGUE-N**: Unigram/bigram overlap (precision/recall/F1)
+- **ROGUE-L**: Longest Common Subsequence visualization
+- **ROGUE-S**: Skip-bigram matching
+- **ROGUE-SU**: Unigram + Skip-bigram combined
+- **ROGUE-W**: Weighted LCS with consecutive bonus
+- **UI**: Alignment view showing matched sequences
+
+### Perplexity
+- **Features**: Next-token probability visualization
+- **Note**: Simulated with API-based approximation (no model weights required)
+- **UI**: Token-by-token probability breakdown
+
+### MRR (Mean Reciprocal Rank)
+- **Features**: Multi-query ranking evaluation
+- **UI**: Ranked list visualization with position highlighting
+- **Use case**: QA/retrieval system evaluation
+
+### BERT Score
+- **Features**: Embedding-based semantic similarity
+- **Implementation**: Using `bert-score` library or sentence-transformers
+- **UI**: Token alignment heatmap with cosine similarity matrix
+
+## Tech Stack
+
+| Component | Library |
+|-----------|---------|
+| UI Framework | Streamlit |
+| Math Rendering | `st.latex()` + custom CSS |
+| Visualizations | Plotly (interactive), Matplotlib (static) |
+| NLP/Metrics | NLTK, rouge-score, bert-score, evaluate |
+| Embeddings | sentence-transformers (all-MiniLM-L6-v2) |
+| Utils | Pandas, NumPy |
+
+## Implementation Phases
+
+### Phase 1: Core Structure (Day 1)
+- Project scaffolding
+- Page routing system
+- Shared sidebar navigation
+- Common utilities (tokenization, text processing)
+
+### Phase 2: BLEU + ROGUE (Day 2)
+- BLEU with n-gram visualization
+- ROGUE-N and ROGUE-L implementations
+- Step-by-step calculation displays
+- Educational content with examples
+
+### Phase 3: Perplexity + MRR (Day 3)
+- Perplexity calculator (approximation)
+- MRR ranking visualization
+- Interactive test case builder
+
+### Phase 4: BERT Score + Polish (Day 4)
+- BERT embedding similarity
+- Token alignment visualization
+- Overview comparison page
+- Export functionality
+
+### Phase 5: Documentation (Day 5)
+- README with screenshots
+- Docstrings for all functions
+- Deployment to HuggingFace Spaces
+- CV integration
+
+## CV Integration
+
+Add to Technical Projects section:
+
+```
+\projectHeading
+  {LLM Evaluation Metrics Dashboard}{\href{https://huggingface.co/spaces/...}{Live Demo}}{Python, Streamlit, NLTK, Plotly}
+\begin{itemize}[leftmargin=0.15in, label={--}, nosep]
+    \small{\resumeItem{Built interactive educational dashboard demonstrating 5 key NLP evaluation metrics: BLEU, ROGUE, Perplexity, MRR, BERT Score.}}
+    \small{\resumeItem{Implemented step-by-step visualizations showing n-gram matching, longest common subsequences, and embedding similarity alignment.}}
+    \small{\resumeItem{Created comparison framework for evaluating text generation quality across lexical and semantic dimensions.}}
+\end{itemize}
+```
+
+## Key Learning Outcomes (for interviews)
+
+1. **BLEU**: Understanding precision vs recall trade-offs, brevity penalty importance
+2. **ROGUE**: Why recall matters for summarization, LCS vs n-gram approaches
+3. **Perplexity**: Model confidence interpretation, relationship to cross-entropy
+4. **MRR**: Ranking evaluation for retrieval systems
+5. **BERT Score**: Semantic similarity beyond lexical overlap
+
+## Deployment
+
+- Primary: HuggingFace Spaces (free, quick setup)
+- Fallback: Streamlit Community Cloud
+- README badges: Live Demo | MIT License
+
+## Notes
+
+- All metrics use established libraries (don't reinvent, wrap and visualize)
+- Focus on educational value: "show the math, not just the score"
+- Mobile-responsive design (Streamlit handles most of this)
+- No API keys required for core functionality

requirements.txt

@@ -0,0 +1,10 @@
+streamlit>=1.28.0
+nltk>=3.8.1
+rouge-score>=0.1.2
+bert-score>=0.3.13
+sentence-transformers>=2.2.2
+plotly>=5.18.0
+numpy>=1.24.0
+pandas>=2.0.0
+transformers>=4.35.0
+torch>=2.1.0