Upload folder using huggingface_hub

README.md

@@ -1,10 +1,10 @@
 ---
-title: Spam Email Classifier with XAI (Gradio)
+title: Spam Email Classifier with XAI
 emoji: 📧
 colorFrom: blue
 colorTo: red
 sdk: gradio
-sdk_version: "4.19.2"
+sdk_version: "4.44.0"
 app_file: app.py
 pinned: false
 license: mit
@@ -13,39 +13,51 @@ tags:
   - xai
   - lime
   - shap
+  - eli5
   - scikit-learn
   - nlp
+  - explainable-ai
 ---
 
 # Spam Email Classifier with XAI Explanations
 
-**ENGT 375 — Applied Machine Learning | Spring 2026 | ODU**
+> **Disclaimer:** This model was created as a university course project. It is intended for **educational and research purposes only** and should not be used as a sole spam/phishing filter in production. Classification accuracy may vary. Always use established email security tools for real-world spam filtering.
 
-> **Disclaimer:** This model was created as a student project for Applied Machine Learning at Old Dominion University. It is intended for **educational and research purposes only** and should not be used as a sole spam/phishing filter in production. Classification accuracy may vary, and the model may produce incorrect or misleading results. Always use established email security tools for real-world spam filtering.
-
-A Gradio web app that classifies emails as spam or ham and provides explainable AI (XAI) insights using LIME and SHAP.
+A Gradio web app that classifies emails as spam or ham and provides explainable AI (XAI) insights using three different methods.
 
 ## Features
 
 - Paste any email and get an instant spam/ham prediction
-- LIME explanations showing which words pushed the decision
-- SHAP feature importance visualizations
-- Built on a voting ensemble of scikit-learn classifiers
+- **LIME** explanations — which words pushed the decision
+- **SHAP** feature importance — game-theoretic attribution
+- **ELI5** — model internal feature weights
+- **Side-by-side comparison** of all three XAI methods
+- **Plain English summary** of why the model made its decision
+- **User feedback** — thumbs up/down to log corrections for batch retraining
+- Adjustable classification threshold
 
 ## How to Run Locally
 
 ```bash
 pip install -r requirements.txt
-python app.py
+python train.py       # train the models (first time only)
+python app.py         # launch the Gradio app
+```
+
+## Retraining with Feedback
+
+```bash
+python retrain.py             # retrain with accumulated feedback corrections
+python retrain.py --no-feedback  # retrain with original data only
 ```
 
 ## Model
 
-Voting ensemble classifier trained on the SpamAssassin + Enron email datasets using TF-IDF features.
+Voting ensemble (Random Forest + Logistic Regression + SVM) trained on SpamAssassin + Enron email datasets using TF-IDF + 24 metadata features.
 
 ## Tech Stack
 
-- scikit-learn (model training)
-- LIME + SHAP (explainability)
+- scikit-learn (ensemble classifier)
+- LIME + SHAP + ELI5 (explainability)
 - Gradio (web interface)
 - NLTK (text preprocessing)

app.py

@@ -1,29 +1,36 @@
 # Gradio web app for the Spam Email Classifier with XAI explanations
-# ENGT 375 Project - Spring 2026 - ODU
-# This app lets users paste an email and see if it's spam or ham,
-# plus LIME and SHAP explanations of why the model made that decision.
+# University course project — Explainable AI for spam detection
+# Features: LIME, SHAP, ELI5, side-by-side comparison, plain English summary,
+# user feedback logging, and batch retrain support.
 
-import numpy as np
-import joblib
-import matplotlib
-matplotlib.use('Agg')  # non-interactive backend so plots work on servers
-import matplotlib.pyplot as plt
+import csv
+import os
+from datetime import datetime
+from pathlib import Path
+
+import eli5
 import gradio as gr
 import lime
 import lime.lime_tabular
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+import numpy as np
 import shap
-from pathlib import Path
+import joblib
 from scipy.sparse import hstack, csr_matrix
+
 from utils import (preprocess_text, compute_metadata_features,
                    META_FEATURE_NAMES, FEATURE_DESCRIPTIONS)
 
 # ---------------------------------------------------------------------------
 # 1. Model Loading
 # ---------------------------------------------------------------------------
-# All trained artifacts live in the models/ folder.
-# If any file is missing, we set it to None and show an error later.
 
 models_dir = Path(__file__).parent / 'models'
+feedback_dir = Path(__file__).parent / 'feedback'
+feedback_dir.mkdir(exist_ok=True)
+FEEDBACK_CSV = feedback_dir / 'feedback_log.csv'
 
 try:
     voting_model = joblib.load(models_dir / 'voting_model.joblib')
@@ -32,7 +39,8 @@ try:
     feature_names = joblib.load(models_dir / 'feature_names.joblib')
     optimal_threshold = joblib.load(models_dir / 'optimal_threshold.joblib')
     training_sample = joblib.load(models_dir / 'training_sample.joblib')
-    print(f"All models loaded successfully. Threshold = {optimal_threshold:.4f}")
+    raw_rf = voting_model.named_estimators_['rf']
+    print(f"All models loaded. Threshold = {optimal_threshold:.4f}")
 except FileNotFoundError as e:
     print(f"Model file not found: {e}")
     voting_model = None
@@ -41,12 +49,11 @@ except FileNotFoundError as e:
     feature_names = None
     optimal_threshold = None
     training_sample = None
+    raw_rf = None
 
 # ---------------------------------------------------------------------------
 # 2. LIME Explainer Setup
 # ---------------------------------------------------------------------------
-# LIME needs a sample of training data to understand feature distributions.
-# We set this up once at startup so we don't recreate it every prediction.
 
 lime_explainer = None
 if training_sample is not None and feature_names is not None:
@@ -59,264 +66,387 @@ if training_sample is not None and feature_names is not None:
     print("LIME explainer ready.")
 
 # ---------------------------------------------------------------------------
-# 3. classify_email Function
+# 3. classify_email
 # ---------------------------------------------------------------------------
-# Takes raw email text, runs it through the full pipeline, returns the
-# prediction label, confidence score, and the combined feature matrix.
 
-def classify_email(email_text):
-    """Classify a single email and return (label, confidence, combined_features)."""
-    # Step 1: Preprocess the text (remove HTML, URLs, stopwords, stem)
+def classify_email(email_text, threshold):
+    """Classify a single email. Returns (label, confidence, spam_proba, combined_features)."""
     cleaned_text = preprocess_text(email_text)
-
-    # Step 2: Convert to TF-IDF features (sparse matrix)
     tfidf_features = tfidf_vectorizer.transform([cleaned_text])
-
-    # Step 3: Compute the 24 metadata features from the RAW text
-    # (metadata uses things like exclamation marks that preprocessing removes)
     meta_raw = compute_metadata_features([email_text])
-
-    # Step 4: Scale the metadata features
     meta_scaled = meta_scaler.transform(meta_raw)
-
-    # Step 5: Combine TF-IDF + metadata into one feature matrix
     combined = hstack([tfidf_features, csr_matrix(meta_scaled)])
-
-    # Step 6: Get the spam probability from the model
     spam_proba = voting_model.predict_proba(combined)[0][1]
 
-    # Step 7: Apply our optimized threshold (not just 0.5)
-    if spam_proba >= optimal_threshold:
+    if spam_proba >= threshold:
         label = "SPAM"
         confidence = spam_proba
     else:
         label = "HAM (Not Spam)"
         confidence = 1.0 - spam_proba
 
-    return label, confidence, combined
-
+    return label, confidence, spam_proba, combined
 
 # ---------------------------------------------------------------------------
-# 4. generate_summary Function
+# 4. LIME explanation
 # ---------------------------------------------------------------------------
-# Creates a human-readable markdown summary of the classification result.
-# Uses LIME feature importance if available, otherwise falls back to
-# showing notable metadata values.
-
-def generate_summary(label, confidence, email_text, lime_explanation=None):
-    """Generate a markdown summary of the classification result."""
-    # Start with the main result
-    summary = f"This email was classified as **{label}** ({confidence:.0%} confidence).\n\n"
-
-    # If we have a LIME explanation, show the top 5 features
-    if lime_explanation is not None:
-        summary += "**Key factors:**\n"
-        # Get the feature importance list from LIME
-        # Each item is (feature_name, weight) - positive = spam, negative = ham
-        feature_list = lime_explanation.as_list()
-        top_features = feature_list[:5]  # take top 5
-
-        for feature_rule, weight in top_features:
-            if weight > 0:
-                direction = "pushes toward spam"
-            else:
-                direction = "pushes toward ham"
-            summary += f"- **{feature_rule}** {direction}\n"
-    else:
-        # Fallback: show notable metadata values when LIME isn't available
-        summary += "**Notable features:**\n"
-        meta_raw = compute_metadata_features([email_text])
-        meta_values = meta_raw[0]
-
-        for i, feat_name in enumerate(META_FEATURE_NAMES):
-            value = meta_values[i]
-            # Only show features with non-zero values (they're more interesting)
-            if value != 0:
-                description = FEATURE_DESCRIPTIONS.get(feat_name, feat_name)
-                summary += f"- **{feat_name}** = {value:.2f} ({description})\n"
-
-    return summary
 
-
-# ---------------------------------------------------------------------------
-# 5. generate_lime_plot Function
-# ---------------------------------------------------------------------------
-# Creates a LIME explanation plot for a single email.
-# LIME shows which features pushed the prediction toward spam vs ham.
-
-def generate_lime_plot(combined_features):
-    """Generate a LIME explanation plot. Returns (figure, explanation) or (None, None)."""
+def generate_lime_explanation(combined_features):
+    """Generate LIME explanation. Returns (figure, explanation) or (None, None)."""
     if lime_explainer is None:
         return None, None
-
-    # Convert sparse matrix to dense array (fine for a single email)
     instance = combined_features.toarray()[0]
-
-    # Ask LIME to explain this prediction
-    # num_features=10 means show the 10 most important features
     explanation = lime_explainer.explain_instance(
         instance,
         voting_model.predict_proba,
         num_features=10,
     )
-
-    # Get the matplotlib figure from LIME
     fig = explanation.as_pyplot_figure()
     fig.tight_layout()
-
     return fig, explanation
 
-
 # ---------------------------------------------------------------------------
-# 6. generate_shap_plot Function
+# 5. SHAP explanation (metadata features only — fast)
 # ---------------------------------------------------------------------------
-# Creates a SHAP explanation plot using ONLY the 24 metadata features.
-# We skip the TF-IDF features because SHAP KernelExplainer is slow on
-# thousands of features - metadata-only is fast and still informative.
 
-def generate_shap_plot(email_text):
-    """Generate a SHAP bar chart for the metadata features. Returns a figure or None."""
+def generate_shap_explanation(email_text):
+    """Generate SHAP bar chart for metadata features. Returns (figure, shap_values, top_indices) or (None, None, None)."""
     if training_sample is None or voting_model is None:
-        return None
+        return None, None, None
 
-    # Get the last 24 columns from the training sample (those are the metadata features)
-    num_meta = len(META_FEATURE_NAMES)  # 24
+    num_meta = len(META_FEATURE_NAMES)
     background_meta = training_sample[:50, -num_meta:]
-
-    # Compute metadata features for this email
     meta_raw = compute_metadata_features([email_text])
     meta_scaled = meta_scaler.transform(meta_raw)
-
-    # We need a wrapper function that takes ONLY metadata features
-    # and pads zeros for the TF-IDF columns so the model can still predict
     num_tfidf = training_sample.shape[1] - num_meta
 
     def predict_with_meta_only(meta_features):
-        """Pad zeros for TF-IDF columns, then predict with the full model."""
         n_samples = meta_features.shape[0]
-        # Create a zero matrix for the TF-IDF part
         tfidf_zeros = csr_matrix((n_samples, num_tfidf))
-        # Combine: TF-IDF zeros + metadata features
         combined = hstack([tfidf_zeros, csr_matrix(meta_features)])
         return voting_model.predict_proba(combined)
 
-    # Create the SHAP explainer with our wrapper function
     explainer = shap.KernelExplainer(predict_with_meta_only, background_meta)
-
-    # Compute SHAP values for this email's metadata
     shap_values = explainer.shap_values(meta_scaled, nsamples=100)
 
-    # SHAP returns different formats depending on the version:
-    # - Older versions: a list of arrays [ham_values, spam_values]
-    # - Newer versions: a single 2D or 3D array
-    # We want a flat 1D array of shape (24,) for the spam class
     if isinstance(shap_values, list):
-        # List format: index 1 is the spam class
         sv = np.array(shap_values[1]).flatten()
     else:
         sv = np.array(shap_values).flatten()
-
-    # If flatten gave us more values than features (e.g. both classes),
-    # take just the last 24 (spam class values)
     if len(sv) > num_meta:
         sv = sv[-num_meta:]
 
-    # Build a horizontal bar chart showing each feature's SHAP value
-    fig, ax = plt.subplots(figsize=(8, 6))
+    top_idx = np.argsort(np.abs(sv))[::-1][:10]
 
-    # Sort features by absolute SHAP value (most important on top)
     sorted_indices = np.argsort(np.abs(sv))
     sorted_names = [META_FEATURE_NAMES[idx] for idx in sorted_indices.tolist()]
     sorted_values = sv[sorted_indices]
 
-    # Color bars: red = pushes toward spam, blue = pushes toward ham
-    colors = []
-    for val in sorted_values:
-        if val > 0:
-            colors.append('#d62728')  # red for spam
-        else:
-            colors.append('#1f77b4')  # blue for ham
-
+    fig, ax = plt.subplots(figsize=(8, 6))
+    colors = ['#d62728' if val > 0 else '#1f77b4' for val in sorted_values]
     ax.barh(sorted_names, sorted_values, color=colors)
     ax.set_xlabel('SHAP Value (impact on spam probability)')
     ax.set_title('SHAP Feature Importance (Metadata Features)')
     ax.axvline(x=0, color='black', linewidth=0.5)
     fig.tight_layout()
 
-    return fig
+    return fig, sv, top_idx
+
+# ---------------------------------------------------------------------------
+# 6. ELI5 explanation
+# ---------------------------------------------------------------------------
+
+def generate_eli5_explanation(combined_features):
+    """Generate ELI5 HTML and top feature names. Returns (html_string, feature_names_list) or (None, None)."""
+    if raw_rf is None or feature_names is None:
+        return None, None
+
+    instance = combined_features.toarray()[0]
+
+    eli5_exp = eli5.explain_prediction(raw_rf, instance, feature_names=feature_names, top=10)
+    html = eli5.format_as_html(eli5_exp)
+
+    eli5_top5 = eli5.explain_prediction(raw_rf, instance, feature_names=feature_names, top=5)
+    top_names = []
+    if hasattr(eli5_top5, 'targets') and eli5_top5.targets:
+        for fw in eli5_top5.targets[0].feature_weights.pos[:5]:
+            top_names.append(fw.feature)
+        for fw in eli5_top5.targets[0].feature_weights.neg[:5]:
+            top_names.append(fw.feature)
 
+    return html, top_names
 
 # ---------------------------------------------------------------------------
-# 7. Example Emails
+# 7. Plain English summary (replaces Ollama LLM)
+# ---------------------------------------------------------------------------
+
+def generate_plain_summary(label, confidence, spam_proba, lime_explanation,
+                           shap_sv, shap_top_idx):
+    """Build a rule-based plain English summary from XAI results."""
+    summary = f"### Classification: **{label}** ({confidence:.0%} confidence)\n\n"
+
+    if lime_explanation is not None:
+        feature_list = lime_explanation.as_list()
+        summary += "**Key words driving this decision (LIME):**\n"
+        for feat_rule, weight in feature_list[:3]:
+            direction = "pushes toward spam" if weight > 0 else "pushes toward ham"
+            summary += f"- **{feat_rule}** — {direction}\n"
+        summary += "\n"
+
+    if shap_sv is not None and shap_top_idx is not None:
+        summary += "**Important email characteristics (SHAP):**\n"
+        for i in shap_top_idx[:2]:
+            feat_name = META_FEATURE_NAMES[i]
+            description = FEATURE_DESCRIPTIONS.get(feat_name, feat_name)
+            direction = "spam signal" if shap_sv[i] > 0 else "ham signal"
+            summary += f"- **{feat_name}** ({description}) — {direction}\n"
+        summary += "\n"
+
+    if lime_explanation is not None and shap_top_idx is not None:
+        lime_top = set(f[0] for f in lime_explanation.as_list()[:10])
+        shap_top = set(META_FEATURE_NAMES[i] for i in shap_top_idx[:10])
+        overlap = lime_top & shap_top
+        if overlap:
+            summary += f"**Method agreement:** LIME and SHAP both flag: {', '.join(sorted(overlap))}\n\n"
+
+    if "SPAM" in label:
+        if confidence > 0.9:
+            summary += "The model is highly confident this email contains patterns commonly seen in spam or phishing attempts."
+        elif confidence > 0.7:
+            summary += "The model found several spam-like patterns in this email."
+        else:
+            summary += "The model leans toward spam, but the evidence is not overwhelming. Use your judgment."
+    else:
+        if confidence > 0.9:
+            summary += "The model is highly confident this is a legitimate email."
+        elif confidence > 0.7:
+            summary += "The model found this email to be mostly consistent with legitimate messages."
+        else:
+            summary += "The model leans toward legitimate, but there are some spam-like features. Review carefully."
+
+    return summary
+
+# ---------------------------------------------------------------------------
+# 8. Side-by-side comparison
+# ---------------------------------------------------------------------------
+
+def generate_comparison(lime_explanation, shap_sv, shap_top_idx, eli5_names):
+    """Build a markdown comparison of top features from each XAI method."""
+    md = "### Side-by-Side: Top Features by Method\n\n"
+    md += "| Rank | LIME | SHAP (metadata) | ELI5 |\n"
+    md += "|------|------|-----------------|------|\n"
+
+    lime_top5 = []
+    if lime_explanation is not None:
+        for feat, w in lime_explanation.as_list()[:5]:
+            direction = "spam" if w > 0 else "ham"
+            lime_top5.append(f"{feat} ({direction}, {w:+.3f})")
+
+    shap_top5 = []
+    if shap_sv is not None and shap_top_idx is not None:
+        for i in shap_top_idx[:5]:
+            direction = "spam" if shap_sv[i] > 0 else "ham"
+            shap_top5.append(f"{META_FEATURE_NAMES[i]} ({direction}, {shap_sv[i]:+.3f})")
+
+    eli5_top5 = (eli5_names or [])[:5]
+
+    for rank in range(5):
+        lime_cell = lime_top5[rank] if rank < len(lime_top5) else "—"
+        shap_cell = shap_top5[rank] if rank < len(shap_top5) else "—"
+        eli5_cell = eli5_top5[rank] if rank < len(eli5_top5) else "—"
+        md += f"| {rank+1} | {lime_cell} | {shap_cell} | {eli5_cell} |\n"
+
+    if lime_explanation is not None and shap_top_idx is not None:
+        lime_set = set(f[0] for f in lime_explanation.as_list()[:10])
+        shap_set = set(META_FEATURE_NAMES[i] for i in shap_top_idx[:10])
+        overlap = lime_set & shap_set
+        md += f"\n**LIME-SHAP agreement** (top 10): **{len(overlap)}** shared features"
+        if overlap:
+            md += f"\nShared: {', '.join(sorted(overlap))}"
+
+    md += "\n\n*Note: LIME covers all features (words + metadata), SHAP covers only the 24 metadata features, "
+    md += "ELI5 uses the Random Forest sub-estimator's internal weights.*"
+
+    return md
+
+# ---------------------------------------------------------------------------
+# 9. Feedback logging
+# ---------------------------------------------------------------------------
+
+def log_feedback(email_text, predicted_label, predicted_confidence, threshold,
+                 feedback_type, correct_label=None):
+    """Append one feedback row to the CSV log."""
+    write_header = not FEEDBACK_CSV.exists()
+    with open(FEEDBACK_CSV, 'a', newline='', encoding='utf-8') as f:
+        writer = csv.writer(f)
+        if write_header:
+            writer.writerow(['timestamp', 'email_text', 'predicted_label',
+                             'predicted_confidence', 'feedback', 'correct_label',
+                             'threshold_used'])
+        writer.writerow([
+            datetime.now().isoformat(),
+            email_text[:500],
+            predicted_label,
+            f"{predicted_confidence:.4f}",
+            feedback_type,
+            correct_label or '',
+            f"{threshold:.4f}",
+        ])
+    return count_corrections()
+
+
+def count_corrections():
+    """Count the number of 'wrong' entries in the feedback log."""
+    if not FEEDBACK_CSV.exists():
+        return 0
+    count = 0
+    with open(FEEDBACK_CSV, 'r', encoding='utf-8') as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            if row.get('feedback') == 'wrong':
+                count += 1
+    return count
+
+# ---------------------------------------------------------------------------
+# 10. Example Emails
 # ---------------------------------------------------------------------------
-# These give users something to try right away without typing their own email.
 
 EXAMPLE_EMAILS = [
     ["Subject: URGENT - You Have Won $5,000,000!!!\n\nDear Friend,\n\nCONGRATULATIONS!!! You have been selected as the winner of our international lottery program!!!\nTo claim your $5,000,000 USD prize, click the link below IMMEDIATELY and provide your bank details.\n\nACT NOW - This offer expires in 24 hours!!!\n\nClick here: http://totally-legit-prize.com/claim\nSend $500 processing fee to unlock your winnings.\n\nBest regards,\nDr. Prince Mohammed"],
     ["Subject: Team sync Thursday 2pm\n\nHi everyone,\n\nJust a reminder that we have our weekly team sync this Thursday at 2pm in Conference Room B.\n\nAgenda:\n- Sprint review\n- Q2 planning discussion\n- New hire onboarding update\n\nPlease come prepared with your status updates.\n\nThanks,\nSarah"],
     ["Subject: Your account has been compromised!\n\nDear Customer,\n\nWe detected suspicious activity on your account. Click here immediately to verify your identity: http://secure-bank-login.com/verify\n\nIf you do not verify within 24 hours, your account will be permanently locked.\n\nSecurity Team"],
     ["Subject: Thanksgiving dinner plans\n\nHi everyone!\n\nI wanted to start planning for Thanksgiving dinner. I'm thinking we could do it at my place this year. What does everyone think about 4pm?\n\nLet me know if you have any dietary restrictions or if you want to bring a dish.\n\nLove,\nMom"],
+    ["Subject: Best prices on V1AGRA and C1ALIS!!!\n\n$$$ SAVE BIG $$$\nBuy now and get 80% OFF!!!\nNo prescription needed! Free shipping!\nOrder at http://cheap-pharma-deals.com\n\nLIMITED TIME OFFER - ACT NOW!"],
 ]
 
-
 # ---------------------------------------------------------------------------
-# 8. classify_and_explain (Main Function)
+# 11. Main orchestration function
 # ---------------------------------------------------------------------------
-# This is the function that Gradio calls when the user clicks "Classify".
-# It handles file uploads, input validation, and orchestrates everything.
 
-def classify_and_explain(email_text, uploaded_file):
-    """Main function called by Gradio. Returns (summary_markdown, lime_fig, shap_fig)."""
+def classify_and_explain(email_text, uploaded_file, threshold):
+    """Main function called by Gradio. Returns all outputs for all tabs + feedback state."""
 
-    # If user uploaded a file, read its contents
     if uploaded_file is not None:
         try:
             file_content = Path(uploaded_file).read_text(encoding='utf-8')
             email_text = file_content
         except Exception:
-            return "Could not read file. Please upload a .txt file.", None, None
+            empty = ("Could not read file.", None, None, "Error reading file.", "", "", "")
+            return empty
 
-    # Check for empty input
     if email_text is None or email_text.strip() == '':
-        return "Please enter email text or upload a file.", None, None
+        empty = ("Please enter email text or upload a file.", None, None, "", "", "", "")
+        return empty
 
-    # Check that models are loaded
     if voting_model is None:
-        return "Models not found. Run `python3 train.py` first.", None, None
+        empty = ("Models not found. Run `python3 train.py` first.", None, None, "", "", "", "")
+        return empty
 
-    # Step 1: Classify the email
-    label, confidence, combined_features = classify_email(email_text)
+    label, confidence, spam_proba, combined = classify_email(email_text, threshold)
 
-    # Step 2: Generate the LIME plot and explanation
-    lime_fig, lime_explanation = generate_lime_plot(combined_features)
+    lime_fig, lime_exp = generate_lime_explanation(combined)
 
-    # Step 3: Generate the SHAP plot (wrapped in try/except so SHAP errors
-    # don't prevent the Result and LIME tabs from showing)
     try:
-        shap_fig = generate_shap_plot(email_text)
+        shap_fig, shap_sv, shap_top_idx = generate_shap_explanation(email_text)
     except Exception as e:
-        print('SHAP error: %s' % str(e))
-        shap_fig = None
+        print(f"SHAP error: {e}")
+        shap_fig, shap_sv, shap_top_idx = None, None, None
 
-    # Step 4: Generate the human-readable summary
-    summary = generate_summary(label, confidence, email_text, lime_explanation)
+    try:
+        eli5_html, eli5_names = generate_eli5_explanation(combined)
+    except Exception as e:
+        print(f"ELI5 error: {e}")
+        eli5_html, eli5_names = None, None
+
+    result_md = f"## {'SPAM' if 'SPAM' in label else 'HAM (Not Spam)'}\n\n"
+    result_md += f"**Confidence:** {confidence:.1%}\n\n"
+    result_md += f"**Threshold:** {threshold:.0%}\n\n"
+    result_md += f"**Spam probability:** {spam_proba:.1%}\n\n"
+    if lime_exp is not None:
+        result_md += "**Key factors:**\n"
+        for feat_rule, weight in lime_exp.as_list()[:5]:
+            direction = "pushes toward spam" if weight > 0 else "pushes toward ham"
+            result_md += f"- **{feat_rule}** {direction}\n"
+
+    comparison_md = generate_comparison(lime_exp, shap_sv, shap_top_idx, eli5_names)
+    summary_md = generate_plain_summary(label, confidence, spam_proba, lime_exp, shap_sv, shap_top_idx)
+    eli5_display = eli5_html or "<p>ELI5 explanation not available.</p>"
+
+    return (result_md, lime_fig, shap_fig, eli5_display, comparison_md, summary_md,
+            f"{label}|||{confidence:.4f}|||{threshold:.4f}|||{email_text[:500]}")
 
-    return summary, lime_fig, shap_fig
+# ---------------------------------------------------------------------------
+# 12. Feedback handlers
+# ---------------------------------------------------------------------------
 
+def handle_correct(hidden_state):
+    """Log positive feedback."""
+    if not hidden_state:
+        return "No classification to give feedback on."
+    parts = hidden_state.split('|||')
+    if len(parts) < 4:
+        return "No classification to give feedback on."
+    label, conf, thresh, email = parts[0], float(parts[1]), float(parts[2]), parts[3]
+    corrections = log_feedback(email, label, float(conf), float(thresh), 'correct')
+    return f"Thanks for the feedback! ({corrections} corrections collected so far)"
+
+
+def handle_wrong(hidden_state, correct_label):
+    """Log negative feedback with the user's correction."""
+    if not hidden_state:
+        return "No classification to give feedback on."
+    parts = hidden_state.split('|||')
+    if len(parts) < 4:
+        return "No classification to give feedback on."
+    label, conf, thresh, email = parts[0], float(parts[1]), float(parts[2]), parts[3]
+    corrections = log_feedback(email, label, float(conf), float(thresh), 'wrong', correct_label)
+    return f"Correction logged! ({corrections} corrections collected so far)"
 
 # ---------------------------------------------------------------------------
-# 9. Gradio Interface
+# 13. Gradio Blocks UI
 # ---------------------------------------------------------------------------
-# Three tabs: Result (text summary), LIME (feature importance plot),
-# and SHAP (metadata feature importance plot).
+
+HOW_IT_WORKS_MD = """
+## How This App Works
+
+### What is spam classification?
+Spam classification automatically identifies unwanted or malicious emails (spam) vs. legitimate messages (ham). This helps protect users from phishing scams, fraudulent offers, and unwanted advertising.
+
+### The Model
+This app uses a **Voting Ensemble** — three different machine learning models that each "vote" on whether an email is spam:
+- **Random Forest** — builds many decision trees and takes the majority vote
+- **Logistic Regression** — finds a mathematical boundary between spam and ham
+- **Support Vector Machine (SVM)** — finds the widest possible margin between classes
+
+By combining all three, the ensemble is more accurate than any single model alone.
+
+### Feature Extraction
+The model looks at two types of features:
+- **TF-IDF (Term Frequency-Inverse Document Frequency)** — measures how important each word is. Common spam words like "prize" or "click" get high scores.
+- **24 Metadata Features** — structural patterns like exclamation mark density, dollar sign count, ALL CAPS ratio, URL count, and more.
+
+### Explainable AI (XAI) Methods
+This app doesn't just classify — it explains **why**:
+
+- **LIME** — Removes words one at a time and watches how the prediction changes. Shows which words matter most.
+- **SHAP** — Uses game theory to calculate each feature's "fair share" of the prediction. Based on Nobel Prize-winning mathematics.
+- **ELI5** — Looks directly at the model's internal weights to show which features it relies on most.
+
+### Feedback & Retraining
+When you click "Correct" or "Wrong", your feedback is saved. After enough corrections accumulate, the model can be retrained with the new examples to improve over time. This is called **human-in-the-loop machine learning**.
+
+### Disclaimer
+This model was created as a university course project. It is intended for **educational and research purposes only** and should not be used as a sole spam filter in production. Always use established email security tools for real-world spam filtering.
+"""
 
 with gr.Blocks(title="Spam Email Classifier with XAI") as demo:
     gr.Markdown("# Spam Email Classifier with XAI Explanations")
-    gr.Markdown("Paste an email below (or upload a .txt file) and click **Classify** "
-                "to see if it's spam, plus explanations of why.")
+    gr.Markdown("Classify emails and understand **why** using LIME, SHAP, ELI5, "
+                "and plain English summaries. Created as a university course project.")
+
+    hidden_state = gr.State("")
 
     with gr.Row():
-        # Left column: inputs
         with gr.Column(scale=1):
             email_input = gr.Textbox(
                 label="Email Text",
@@ -328,6 +458,12 @@ with gr.Blocks(title="Spam Email Classifier with XAI") as demo:
                 label="Or upload a .txt file",
                 file_types=['.txt'],
             )
+            threshold_slider = gr.Slider(
+                minimum=0.0, maximum=1.0, step=0.05,
+                value=optimal_threshold if optimal_threshold else 0.5,
+                label="Classification Threshold",
+                info="Emails with spam probability above this are classified as spam.",
+            )
             classify_btn = gr.Button("Classify", variant="primary")
             gr.Examples(
                 examples=EXAMPLE_EMAILS,
@@ -336,26 +472,61 @@ with gr.Blocks(title="Spam Email Classifier with XAI") as demo:
                 cache_examples=False,
             )
 
-        # Right column: outputs in tabs
         with gr.Column(scale=1):
             with gr.Tabs():
                 with gr.Tab("Result"):
                     result_output = gr.Markdown(label="Classification Result")
                 with gr.Tab("LIME"):
+                    gr.Markdown("*LIME perturbs the input and fits a local model "
+                                "to see which features matter most.*")
                     lime_output = gr.Plot(label="LIME Explanation")
                 with gr.Tab("SHAP"):
+                    gr.Markdown("*SHAP uses game theory to assign each feature "
+                                "a contribution value.*")
                     shap_output = gr.Plot(label="SHAP Explanation")
+                with gr.Tab("ELI5"):
+                    gr.Markdown("*ELI5 shows feature weights directly from the "
+                                "model's internals.*")
+                    eli5_output = gr.HTML(label="ELI5 Explanation")
+                with gr.Tab("Compare"):
+                    compare_output = gr.Markdown(label="Method Comparison")
+                with gr.Tab("Summary"):
+                    summary_output = gr.Markdown(label="Plain English Summary")
+                with gr.Tab("How It Works"):
+                    gr.Markdown(HOW_IT_WORKS_MD)
+
+            gr.Markdown("---")
+            gr.Markdown("**Was this classification correct?**")
+            feedback_msg = gr.Markdown("")
+            with gr.Row():
+                correct_btn = gr.Button("Correct", variant="secondary")
+                wrong_btn = gr.Button("Wrong", variant="stop")
+                correction_dropdown = gr.Dropdown(
+                    choices=["Spam", "Ham"],
+                    label="What should it be?",
+                    visible=True,
+                )
 
-    # Wire up the button click to our main function
     classify_btn.click(
         fn=classify_and_explain,
-        inputs=[email_input, file_input],
-        outputs=[result_output, lime_output, shap_output],
-        scroll_to_output=False,
+        inputs=[email_input, file_input, threshold_slider],
+        outputs=[result_output, lime_output, shap_output, eli5_output,
+                 compare_output, summary_output, hidden_state],
+    )
+
+    correct_btn.click(
+        fn=handle_correct,
+        inputs=[hidden_state],
+        outputs=[feedback_msg],
+    )
+    wrong_btn.click(
+        fn=handle_wrong,
+        inputs=[hidden_state, correction_dropdown],
+        outputs=[feedback_msg],
     )
 
 # ---------------------------------------------------------------------------
-# 10. Launch
+# 14. Launch
 # ---------------------------------------------------------------------------
 
 if __name__ == '__main__':

docs/superpowers/plans/2026-03-28-gradio-xai-merge.md

@@ -0,0 +1,1231 @@
+# Gradio XAI Merge Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Merge ELI5, comparison, plain English summary, How It Works, and feedback/retrain features into the existing Gradio spam classifier Space.
+
+**Architecture:** Extend the existing `app.py` (Gradio Blocks layout) by adding 4 new tabs, a feedback row, and a retrain script. The VotingClassifier's RF sub-estimator is extracted at startup for ELI5 and TreeExplainer. Feedback logs to CSV; retrain reads it offline.
+
+**Tech Stack:** Python, Gradio 4.44+, scikit-learn, LIME, SHAP, ELI5, matplotlib, NLTK
+
+**Spec:** `docs/superpowers/specs/2026-03-28-gradio-xai-merge-design.md`
+
+---
+
+## File Structure
+
+| File | Action | Responsibility |
+|------|--------|---------------|
+| `requirements.txt` | Modify | Add eli5, bump gradio |
+| `app.py` | Major rewrite | All 7 tabs, feedback UI, threshold slider, classification orchestration |
+| `retrain.py` | Create | Batch retrain script that reads feedback CSV and augments training data |
+| `feedback/.gitkeep` | Create | Empty directory for feedback log accumulation |
+| `README.md` | Modify | Updated frontmatter + feature description |
+| `utils.py` | No changes | Shared preprocessing (stays as-is) |
+| `test_utils.py` | No changes | Existing tests (stays as-is) |
+
+---
+
+### Task 1: Update dependencies
+
+**Files:**
+- Modify: `requirements.txt`
+
+- [ ] **Step 1: Update requirements.txt**
+
+Replace the full contents of `requirements.txt` with:
+
+```
+numpy>=1.24.0
+pandas>=2.0.0
+matplotlib>=3.7.0
+scikit-learn>=1.3.0
+scipy>=1.11.0
+nltk>=3.8.0
+lime>=0.2.0
+shap>=0.44.0
+eli5>=0.13.0
+gradio>=4.44.0
+joblib>=1.3.0
+tqdm>=4.65.0
+```
+
+- [ ] **Step 2: Create feedback directory**
+
+```bash
+mkdir -p feedback
+touch feedback/.gitkeep
+```
+
+- [ ] **Step 3: Install new dependency locally**
+
+```bash
+cd spam-classifier-gradio
+source venv/bin/activate
+pip install eli5>=0.13.0 "gradio>=4.44.0"
+```
+
+- [ ] **Step 4: Verify eli5 imports**
+
+```bash
+python3 -c "import eli5; print('eli5', eli5.__version__)"
+```
+
+Expected: prints eli5 version without error.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add requirements.txt feedback/.gitkeep
+git commit -m "Add eli5 dependency, bump gradio, create feedback directory"
+```
+
+---
+
+### Task 2: Rewrite app.py — model loading and classification core
+
+This task replaces the existing `app.py` with the new version. We build it in stages. This task covers the imports, model loading, and the `classify_email` function (unchanged logic, but we also extract the RF sub-estimator for ELI5).
+
+**Files:**
+- Modify: `app.py` (rewrite from line 1)
+
+- [ ] **Step 1: Write the new imports and model loading section**
+
+Replace everything in `app.py` from line 1 through the end of the model loading section (lines 1-59) with:
+
+```python
+# Gradio web app for the Spam Email Classifier with XAI explanations
+# University course project — Explainable AI for spam detection
+# Features: LIME, SHAP, ELI5, side-by-side comparison, plain English summary,
+# user feedback logging, and batch retrain support.
+
+import csv
+import os
+from datetime import datetime
+from pathlib import Path
+
+import eli5
+import gradio as gr
+import lime
+import lime.lime_tabular
+import matplotlib
+matplotlib.use('Agg')  # non-interactive backend so plots work on servers
+import matplotlib.pyplot as plt
+import numpy as np
+import shap
+import joblib
+from scipy.sparse import hstack, csr_matrix
+
+from utils import (preprocess_text, compute_metadata_features,
+                   META_FEATURE_NAMES, FEATURE_DESCRIPTIONS)
+
+# ---------------------------------------------------------------------------
+# 1. Model Loading
+# ---------------------------------------------------------------------------
+
+models_dir = Path(__file__).parent / 'models'
+feedback_dir = Path(__file__).parent / 'feedback'
+feedback_dir.mkdir(exist_ok=True)
+FEEDBACK_CSV = feedback_dir / 'feedback_log.csv'
+
+try:
+    voting_model = joblib.load(models_dir / 'voting_model.joblib')
+    tfidf_vectorizer = joblib.load(models_dir / 'tfidf_vectorizer.joblib')
+    meta_scaler = joblib.load(models_dir / 'meta_scaler.joblib')
+    feature_names = joblib.load(models_dir / 'feature_names.joblib')
+    optimal_threshold = joblib.load(models_dir / 'optimal_threshold.joblib')
+    training_sample = joblib.load(models_dir / 'training_sample.joblib')
+    # Extract the Random Forest from the voting ensemble for ELI5 and SHAP TreeExplainer
+    raw_rf = voting_model.named_estimators_['rf']
+    print(f"All models loaded. Threshold = {optimal_threshold:.4f}")
+except FileNotFoundError as e:
+    print(f"Model file not found: {e}")
+    voting_model = None
+    tfidf_vectorizer = None
+    meta_scaler = None
+    feature_names = None
+    optimal_threshold = None
+    training_sample = None
+    raw_rf = None
+```
+
+- [ ] **Step 2: Write the LIME explainer setup and classify_email function**
+
+Append after the model loading section:
+
+```python
+# ---------------------------------------------------------------------------
+# 2. LIME Explainer Setup
+# ---------------------------------------------------------------------------
+
+lime_explainer = None
+if training_sample is not None and feature_names is not None:
+    lime_explainer = lime.lime_tabular.LimeTabularExplainer(
+        training_data=training_sample,
+        feature_names=feature_names,
+        class_names=['Ham', 'Spam'],
+        mode='classification',
+    )
+    print("LIME explainer ready.")
+
+# ---------------------------------------------------------------------------
+# 3. classify_email — core prediction logic
+# ---------------------------------------------------------------------------
+
+def classify_email(email_text, threshold):
+    """Classify a single email. Returns (label, confidence, spam_proba, combined_features)."""
+    cleaned_text = preprocess_text(email_text)
+    tfidf_features = tfidf_vectorizer.transform([cleaned_text])
+    meta_raw = compute_metadata_features([email_text])
+    meta_scaled = meta_scaler.transform(meta_raw)
+    combined = hstack([tfidf_features, csr_matrix(meta_scaled)])
+    spam_proba = voting_model.predict_proba(combined)[0][1]
+
+    if spam_proba >= threshold:
+        label = "SPAM"
+        confidence = spam_proba
+    else:
+        label = "HAM (Not Spam)"
+        confidence = 1.0 - spam_proba
+
+    return label, confidence, spam_proba, combined
+```
+
+- [ ] **Step 3: Verify the module loads without errors**
+
+```bash
+python3 -c "
+import app
+print('voting_model:', type(app.voting_model))
+print('raw_rf:', type(app.raw_rf))
+print('classify_email:', callable(app.classify_email))
+"
+```
+
+Expected: prints types without errors. `raw_rf` should be `RandomForestClassifier`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add app.py
+git commit -m "Rewrite app.py core: imports, model loading with RF extraction, classify function"
+```
+
+---
+
+### Task 3: Add XAI explanation functions (LIME, SHAP, ELI5)
+
+**Files:**
+- Modify: `app.py` (append after classify_email)
+
+- [ ] **Step 1: Add LIME plot function**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 4. LIME explanation
+# ---------------------------------------------------------------------------
+
+def generate_lime_explanation(combined_features):
+    """Generate LIME explanation. Returns (figure, explanation) or (None, None)."""
+    if lime_explainer is None:
+        return None, None
+    instance = combined_features.toarray()[0]
+    explanation = lime_explainer.explain_instance(
+        instance,
+        voting_model.predict_proba,
+        num_features=10,
+    )
+    fig = explanation.as_pyplot_figure()
+    fig.tight_layout()
+    return fig, explanation
+```
+
+- [ ] **Step 2: Add SHAP plot function**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 5. SHAP explanation (metadata features only — fast)
+# ---------------------------------------------------------------------------
+
+def generate_shap_explanation(email_text):
+    """Generate SHAP bar chart for metadata features. Returns (figure, shap_values, top_indices) or (None, None, None)."""
+    if training_sample is None or voting_model is None:
+        return None, None, None
+
+    num_meta = len(META_FEATURE_NAMES)  # 24
+    background_meta = training_sample[:50, -num_meta:]
+
+    meta_raw = compute_metadata_features([email_text])
+    meta_scaled = meta_scaler.transform(meta_raw)
+
+    num_tfidf = training_sample.shape[1] - num_meta
+
+    def predict_with_meta_only(meta_features):
+        n_samples = meta_features.shape[0]
+        tfidf_zeros = csr_matrix((n_samples, num_tfidf))
+        combined = hstack([tfidf_zeros, csr_matrix(meta_features)])
+        return voting_model.predict_proba(combined)
+
+    explainer = shap.KernelExplainer(predict_with_meta_only, background_meta)
+    shap_values = explainer.shap_values(meta_scaled, nsamples=100)
+
+    if isinstance(shap_values, list):
+        sv = np.array(shap_values[1]).flatten()
+    else:
+        sv = np.array(shap_values).flatten()
+
+    if len(sv) > num_meta:
+        sv = sv[-num_meta:]
+
+    # Top indices by absolute value
+    top_idx = np.argsort(np.abs(sv))[::-1][:10]
+
+    # Build bar chart
+    sorted_indices = np.argsort(np.abs(sv))
+    sorted_names = [META_FEATURE_NAMES[idx] for idx in sorted_indices.tolist()]
+    sorted_values = sv[sorted_indices]
+
+    fig, ax = plt.subplots(figsize=(8, 6))
+    colors = ['#d62728' if val > 0 else '#1f77b4' for val in sorted_values]
+    ax.barh(sorted_names, sorted_values, color=colors)
+    ax.set_xlabel('SHAP Value (impact on spam probability)')
+    ax.set_title('SHAP Feature Importance (Metadata Features)')
+    ax.axvline(x=0, color='black', linewidth=0.5)
+    fig.tight_layout()
+
+    return fig, sv, top_idx
+```
+
+- [ ] **Step 3: Add ELI5 explanation function**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 6. ELI5 explanation
+# ---------------------------------------------------------------------------
+
+def generate_eli5_explanation(combined_features):
+    """Generate ELI5 HTML and top feature names. Returns (html_string, feature_names_list) or (None, None)."""
+    if raw_rf is None or feature_names is None:
+        return None, None
+
+    instance = combined_features.toarray()[0]
+
+    # Full HTML rendering (10 features)
+    eli5_exp = eli5.explain_prediction(raw_rf, instance, feature_names=feature_names, top=10)
+    html = eli5.format_as_html(eli5_exp)
+
+    # Extract top 5 feature names for the Compare tab
+    eli5_top5 = eli5.explain_prediction(raw_rf, instance, feature_names=feature_names, top=5)
+    top_names = []
+    if hasattr(eli5_top5, 'targets') and eli5_top5.targets:
+        for fw in eli5_top5.targets[0].feature_weights.pos[:5]:
+            top_names.append(fw.feature)
+        for fw in eli5_top5.targets[0].feature_weights.neg[:5]:
+            top_names.append(fw.feature)
+
+    return html, top_names
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add app.py
+git commit -m "Add LIME, SHAP, and ELI5 explanation functions"
+```
+
+---
+
+### Task 4: Add summary, comparison, and feedback helper functions
+
+**Files:**
+- Modify: `app.py` (append after ELI5 function)
+
+- [ ] **Step 1: Add the rule-based plain English summary function**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 7. Plain English summary (replaces Ollama LLM)
+# ---------------------------------------------------------------------------
+
+def generate_plain_summary(label, confidence, spam_proba, lime_explanation,
+                           shap_sv, shap_top_idx):
+    """Build a rule-based plain English summary from XAI results."""
+    summary = f"### Classification: **{label}** ({confidence:.0%} confidence)\n\n"
+
+    # LIME top features
+    if lime_explanation is not None:
+        feature_list = lime_explanation.as_list()
+        summary += "**Key words driving this decision (LIME):**\n"
+        for feat_rule, weight in feature_list[:3]:
+            direction = "pushes toward spam" if weight > 0 else "pushes toward ham"
+            summary += f"- **{feat_rule}** — {direction}\n"
+        summary += "\n"
+
+    # SHAP top metadata features
+    if shap_sv is not None and shap_top_idx is not None:
+        summary += "**Important email characteristics (SHAP):**\n"
+        for i in shap_top_idx[:2]:
+            feat_name = META_FEATURE_NAMES[i]
+            description = FEATURE_DESCRIPTIONS.get(feat_name, feat_name)
+            direction = "spam signal" if shap_sv[i] > 0 else "ham signal"
+            summary += f"- **{feat_name}** ({description}) — {direction}\n"
+        summary += "\n"
+
+    # Agreement note
+    if lime_explanation is not None and shap_top_idx is not None:
+        lime_top = set(f[0] for f in lime_explanation.as_list()[:10])
+        shap_top = set(META_FEATURE_NAMES[i] for i in shap_top_idx[:10])
+        overlap = lime_top & shap_top
+        if overlap:
+            summary += f"**Method agreement:** LIME and SHAP both flag: {', '.join(sorted(overlap))}\n\n"
+
+    # Closing sentence
+    if "SPAM" in label:
+        if confidence > 0.9:
+            summary += "The model is highly confident this email contains patterns commonly seen in spam or phishing attempts."
+        elif confidence > 0.7:
+            summary += "The model found several spam-like patterns in this email."
+        else:
+            summary += "The model leans toward spam, but the evidence is not overwhelming. Use your judgment."
+    else:
+        if confidence > 0.9:
+            summary += "The model is highly confident this is a legitimate email."
+        elif confidence > 0.7:
+            summary += "The model found this email to be mostly consistent with legitimate messages."
+        else:
+            summary += "The model leans toward legitimate, but there are some spam-like features. Review carefully."
+
+    return summary
+```
+
+- [ ] **Step 2: Add the comparison markdown generator**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 8. Side-by-side comparison
+# ---------------------------------------------------------------------------
+
+def generate_comparison(lime_explanation, shap_sv, shap_top_idx, eli5_names):
+    """Build a markdown comparison of top features from each XAI method."""
+    md = "### Side-by-Side: Top Features by Method\n\n"
+    md += "| Rank | LIME | SHAP (metadata) | ELI5 |\n"
+    md += "|------|------|-----------------|------|\n"
+
+    lime_top5 = []
+    if lime_explanation is not None:
+        for feat, w in lime_explanation.as_list()[:5]:
+            direction = "spam" if w > 0 else "ham"
+            lime_top5.append(f"{feat} ({direction}, {w:+.3f})")
+
+    shap_top5 = []
+    if shap_sv is not None and shap_top_idx is not None:
+        for i in shap_top_idx[:5]:
+            direction = "spam" if shap_sv[i] > 0 else "ham"
+            shap_top5.append(f"{META_FEATURE_NAMES[i]} ({direction}, {shap_sv[i]:+.3f})")
+
+    eli5_top5 = (eli5_names or [])[:5]
+
+    for rank in range(5):
+        lime_cell = lime_top5[rank] if rank < len(lime_top5) else "—"
+        shap_cell = shap_top5[rank] if rank < len(shap_top5) else "—"
+        eli5_cell = eli5_top5[rank] if rank < len(eli5_top5) else "—"
+        md += f"| {rank+1} | {lime_cell} | {shap_cell} | {eli5_cell} |\n"
+
+    # Agreement analysis
+    if lime_explanation is not None and shap_top_idx is not None:
+        lime_set = set(f[0] for f in lime_explanation.as_list()[:10])
+        shap_set = set(META_FEATURE_NAMES[i] for i in shap_top_idx[:10])
+        overlap = lime_set & shap_set
+        md += f"\n**LIME-SHAP agreement** (top 10): **{len(overlap)}** shared features"
+        if overlap:
+            md += f"\nShared: {', '.join(sorted(overlap))}"
+
+    md += "\n\n*Note: LIME covers all features (words + metadata), SHAP covers only the 24 metadata features, "
+    md += "ELI5 uses the Random Forest sub-estimator's internal weights.*"
+
+    return md
+```
+
+- [ ] **Step 3: Add feedback logging function**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 9. Feedback logging
+# ---------------------------------------------------------------------------
+
+def log_feedback(email_text, predicted_label, predicted_confidence, threshold,
+                 feedback_type, correct_label=None):
+    """Append one feedback row to the CSV log."""
+    # Write header if file doesn't exist yet
+    write_header = not FEEDBACK_CSV.exists()
+
+    with open(FEEDBACK_CSV, 'a', newline='', encoding='utf-8') as f:
+        writer = csv.writer(f)
+        if write_header:
+            writer.writerow(['timestamp', 'email_text', 'predicted_label',
+                             'predicted_confidence', 'feedback', 'correct_label',
+                             'threshold_used'])
+        writer.writerow([
+            datetime.now().isoformat(),
+            email_text[:500],  # truncate to 500 chars
+            predicted_label,
+            f"{predicted_confidence:.4f}",
+            feedback_type,
+            correct_label or '',
+            f"{threshold:.4f}",
+        ])
+
+    return count_corrections()
+
+
+def count_corrections():
+    """Count the number of 'wrong' entries in the feedback log."""
+    if not FEEDBACK_CSV.exists():
+        return 0
+    count = 0
+    with open(FEEDBACK_CSV, 'r', encoding='utf-8') as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            if row.get('feedback') == 'wrong':
+                count += 1
+    return count
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add app.py
+git commit -m "Add summary, comparison, and feedback helper functions"
+```
+
+---
+
+### Task 5: Build the Gradio UI (Blocks layout with 7 tabs + feedback)
+
+**Files:**
+- Modify: `app.py` (append the Gradio Blocks UI after all helper functions)
+
+- [ ] **Step 1: Add example emails and the main orchestration function**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 10. Example Emails
+# ---------------------------------------------------------------------------
+
+EXAMPLE_EMAILS = [
+    ["Subject: URGENT - You Have Won $5,000,000!!!\n\nDear Friend,\n\nCONGRATULATIONS!!! You have been selected as the winner of our international lottery program!!!\nTo claim your $5,000,000 USD prize, click the link below IMMEDIATELY and provide your bank details.\n\nACT NOW - This offer expires in 24 hours!!!\n\nClick here: http://totally-legit-prize.com/claim\nSend $500 processing fee to unlock your winnings.\n\nBest regards,\nDr. Prince Mohammed"],
+    ["Subject: Team sync Thursday 2pm\n\nHi everyone,\n\nJust a reminder that we have our weekly team sync this Thursday at 2pm in Conference Room B.\n\nAgenda:\n- Sprint review\n- Q2 planning discussion\n- New hire onboarding update\n\nPlease come prepared with your status updates.\n\nThanks,\nSarah"],
+    ["Subject: Your account has been compromised!\n\nDear Customer,\n\nWe detected suspicious activity on your account. Click here immediately to verify your identity: http://secure-bank-login.com/verify\n\nIf you do not verify within 24 hours, your account will be permanently locked.\n\nSecurity Team"],
+    ["Subject: Thanksgiving dinner plans\n\nHi everyone!\n\nI wanted to start planning for Thanksgiving dinner. I'm thinking we could do it at my place this year. What does everyone think about 4pm?\n\nLet me know if you have any dietary restrictions or if you want to bring a dish.\n\nLove,\nMom"],
+    ["Subject: Best prices on V1AGRA and C1ALIS!!!\n\n$$$ SAVE BIG $$$\nBuy now and get 80% OFF!!!\nNo prescription needed! Free shipping!\nOrder at http://cheap-pharma-deals.com\n\nLIMITED TIME OFFER - ACT NOW!"],
+]
+
+
+# ---------------------------------------------------------------------------
+# 11. Main orchestration function
+# ---------------------------------------------------------------------------
+
+def classify_and_explain(email_text, uploaded_file, threshold):
+    """Main function called by Gradio. Returns all outputs for all 7 tabs + feedback state."""
+
+    # Handle file upload
+    if uploaded_file is not None:
+        try:
+            file_content = Path(uploaded_file).read_text(encoding='utf-8')
+            email_text = file_content
+        except Exception:
+            empty = ("Could not read file.", None, None, "Error reading file.", "", "", "")
+            return empty
+
+    if email_text is None or email_text.strip() == '':
+        empty = ("Please enter email text or upload a file.", None, None, "", "", "", "")
+        return empty
+
+    if voting_model is None:
+        empty = ("Models not found. Run `python3 train.py` first.", None, None, "", "", "", "")
+        return empty
+
+    # Classify
+    label, confidence, spam_proba, combined = classify_email(email_text, threshold)
+
+    # LIME
+    lime_fig, lime_exp = generate_lime_explanation(combined)
+
+    # SHAP
+    try:
+        shap_fig, shap_sv, shap_top_idx = generate_shap_explanation(email_text)
+    except Exception as e:
+        print(f"SHAP error: {e}")
+        shap_fig, shap_sv, shap_top_idx = None, None, None
+
+    # ELI5
+    try:
+        eli5_html, eli5_names = generate_eli5_explanation(combined)
+    except Exception as e:
+        print(f"ELI5 error: {e}")
+        eli5_html, eli5_names = None, None
+
+    # Result summary (enhanced)
+    result_md = f"## {'SPAM' if 'SPAM' in label else 'HAM (Not Spam)'}\n\n"
+    result_md += f"**Confidence:** {confidence:.1%}\n\n"
+    result_md += f"**Threshold:** {threshold:.0%}\n\n"
+    result_md += f"**Spam probability:** {spam_proba:.1%}\n\n"
+    if lime_exp is not None:
+        result_md += "**Key factors:**\n"
+        for feat_rule, weight in lime_exp.as_list()[:5]:
+            direction = "pushes toward spam" if weight > 0 else "pushes toward ham"
+            result_md += f"- **{feat_rule}** {direction}\n"
+
+    # Comparison
+    comparison_md = generate_comparison(lime_exp, shap_sv, shap_top_idx, eli5_names)
+
+    # Plain English summary
+    summary_md = generate_plain_summary(label, confidence, spam_proba,
+                                         lime_exp, shap_sv, shap_top_idx)
+
+    # ELI5 HTML (wrap for display)
+    eli5_display = eli5_html or "<p>ELI5 explanation not available.</p>"
+
+    return (result_md, lime_fig, shap_fig, eli5_display, comparison_md, summary_md,
+            f"{label}|||{confidence:.4f}|||{threshold:.4f}|||{email_text[:500]}")
+```
+
+- [ ] **Step 2: Add feedback handler functions**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 12. Feedback handlers
+# ---------------------------------------------------------------------------
+
+def handle_correct(hidden_state):
+    """Log positive feedback."""
+    if not hidden_state:
+        return "No classification to give feedback on."
+    parts = hidden_state.split('|||')
+    if len(parts) < 4:
+        return "No classification to give feedback on."
+    label, conf, thresh, email = parts[0], float(parts[1]), float(parts[2]), parts[3]
+    corrections = log_feedback(email, label, float(conf), float(thresh), 'correct')
+    return f"Thanks for the feedback! ({corrections} corrections collected so far)"
+
+
+def handle_wrong(hidden_state, correct_label):
+    """Log negative feedback with the user's correction."""
+    if not hidden_state:
+        return "No classification to give feedback on."
+    parts = hidden_state.split('|||')
+    if len(parts) < 4:
+        return "No classification to give feedback on."
+    label, conf, thresh, email = parts[0], float(parts[1]), float(parts[2]), parts[3]
+    corrections = log_feedback(email, label, float(conf), float(thresh), 'wrong', correct_label)
+    return f"Correction logged! ({corrections} corrections collected so far)"
+```
+
+- [ ] **Step 3: Add the Gradio Blocks layout**
+
+Append to `app.py`:
+
+```python
+# ---------------------------------------------------------------------------
+# 13. Gradio Blocks UI
+# ---------------------------------------------------------------------------
+
+HOW_IT_WORKS_MD = """
+## How This App Works
+
+### What is spam classification?
+Spam classification automatically identifies unwanted or malicious emails (spam) vs. legitimate messages (ham). This helps protect users from phishing scams, fraudulent offers, and unwanted advertising.
+
+### The Model
+This app uses a **Voting Ensemble** — three different machine learning models that each "vote" on whether an email is spam:
+- **Random Forest** — builds many decision trees and takes the majority vote
+- **Logistic Regression** — finds a mathematical boundary between spam and ham
+- **Support Vector Machine (SVM)** — finds the widest possible margin between classes
+
+By combining all three, the ensemble is more accurate than any single model alone.
+
+### Feature Extraction
+The model looks at two types of features:
+- **TF-IDF (Term Frequency-Inverse Document Frequency)** — measures how important each word is. Common spam words like "prize" or "click" get high scores.
+- **24 Metadata Features** — structural patterns like exclamation mark density, dollar sign count, ALL CAPS ratio, URL count, and more.
+
+### Explainable AI (XAI) Methods
+This app doesn't just classify — it explains **why**:
+
+- **LIME** — Removes words one at a time and watches how the prediction changes. Shows which words matter most.
+- **SHAP** — Uses game theory to calculate each feature's "fair share" of the prediction. Based on Nobel Prize-winning mathematics.
+- **ELI5** — Looks directly at the model's internal weights to show which features it relies on most.
+
+### Feedback & Retraining
+When you click "Correct" or "Wrong", your feedback is saved. After enough corrections accumulate, the model can be retrained with the new examples to improve over time. This is called **human-in-the-loop machine learning**.
+
+### Disclaimer
+This model was created as a university course project. It is intended for **educational and research purposes only** and should not be used as a sole spam filter in production. Always use established email security tools for real-world spam filtering.
+"""
+
+with gr.Blocks(title="Spam Email Classifier with XAI") as demo:
+    gr.Markdown("# Spam Email Classifier with XAI Explanations")
+    gr.Markdown("Classify emails and understand **why** using LIME, SHAP, ELI5, "
+                "and plain English summaries. Created as a university course project.")
+
+    # Hidden state for feedback (stores last classification info)
+    hidden_state = gr.State("")
+
+    with gr.Row():
+        # Left column: inputs
+        with gr.Column(scale=1):
+            email_input = gr.Textbox(
+                label="Email Text",
+                placeholder="Paste your email here...",
+                lines=12,
+                autoscroll=False,
+            )
+            file_input = gr.File(
+                label="Or upload a .txt file",
+                file_types=['.txt'],
+            )
+            threshold_slider = gr.Slider(
+                minimum=0.0, maximum=1.0, step=0.05,
+                value=optimal_threshold if optimal_threshold else 0.5,
+                label="Classification Threshold",
+                info="Emails with spam probability above this are classified as spam.",
+            )
+            classify_btn = gr.Button("Classify", variant="primary")
+            gr.Examples(
+                examples=EXAMPLE_EMAILS,
+                inputs=[email_input],
+                label="Try an example email",
+                cache_examples=False,
+            )
+
+        # Right column: output tabs
+        with gr.Column(scale=1):
+            with gr.Tabs():
+                with gr.Tab("Result"):
+                    result_output = gr.Markdown(label="Classification Result")
+                with gr.Tab("LIME"):
+                    gr.Markdown("*LIME perturbs the input and fits a local model "
+                                "to see which features matter most.*")
+                    lime_output = gr.Plot(label="LIME Explanation")
+                with gr.Tab("SHAP"):
+                    gr.Markdown("*SHAP uses game theory to assign each feature "
+                                "a contribution value.*")
+                    shap_output = gr.Plot(label="SHAP Explanation")
+                with gr.Tab("ELI5"):
+                    gr.Markdown("*ELI5 shows feature weights directly from the "
+                                "model's internals.*")
+                    eli5_output = gr.HTML(label="ELI5 Explanation")
+                with gr.Tab("Compare"):
+                    compare_output = gr.Markdown(label="Method Comparison")
+                with gr.Tab("Summary"):
+                    summary_output = gr.Markdown(label="Plain English Summary")
+                with gr.Tab("How It Works"):
+                    gr.Markdown(HOW_IT_WORKS_MD)
+
+            # Feedback row
+            gr.Markdown("---")
+            gr.Markdown("**Was this classification correct?**")
+            feedback_msg = gr.Markdown("")
+            with gr.Row():
+                correct_btn = gr.Button("Correct", variant="secondary")
+                wrong_btn = gr.Button("Wrong", variant="stop")
+                correction_dropdown = gr.Dropdown(
+                    choices=["Spam", "Ham"],
+                    label="What should it be?",
+                    visible=True,
+                )
+
+    # Wire up classify button
+    classify_btn.click(
+        fn=classify_and_explain,
+        inputs=[email_input, file_input, threshold_slider],
+        outputs=[result_output, lime_output, shap_output, eli5_output,
+                 compare_output, summary_output, hidden_state],
+    )
+
+    # Wire up feedback buttons
+    correct_btn.click(
+        fn=handle_correct,
+        inputs=[hidden_state],
+        outputs=[feedback_msg],
+    )
+    wrong_btn.click(
+        fn=handle_wrong,
+        inputs=[hidden_state, correction_dropdown],
+        outputs=[feedback_msg],
+    )
+
+
+# ---------------------------------------------------------------------------
+# 14. Launch
+# ---------------------------------------------------------------------------
+
+if __name__ == '__main__':
+    demo.launch()
+```
+
+- [ ] **Step 4: Test the app launches locally**
+
+```bash
+cd spam-classifier-gradio
+source venv/bin/activate
+python3 app.py
+```
+
+Open `http://127.0.0.1:7860` in a browser. Verify:
+1. All 7 tabs are visible
+2. Pasting an example email and clicking Classify populates all tabs
+3. LIME and SHAP plots render
+4. ELI5 shows an HTML table
+5. Compare tab shows the side-by-side table
+6. Summary tab shows plain English text
+7. How It Works tab shows static content
+8. Feedback buttons log to `feedback/feedback_log.csv`
+
+Stop the server with Ctrl+C.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app.py
+git commit -m "Build complete Gradio UI with 7 tabs, feedback, and threshold slider"
+```
+
+---
+
+### Task 6: Create retrain.py with feedback CSV support
+
+**Files:**
+- Create: `retrain.py`
+
+- [ ] **Step 1: Write retrain.py**
+
+Create `retrain.py` in the project root:
+
+```python
+# Batch retrain script for the spam classifier
+# Reads feedback corrections from feedback/feedback_log.csv,
+# merges them into the original training data, and retrains
+# the VotingClassifier ensemble.
+#
+# Usage:
+#   python3 retrain.py           # retrain with feedback
+#   python3 retrain.py --no-feedback  # retrain without feedback (original data only)
+
+import sys
+import csv
+import warnings
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.ensemble import RandomForestClassifier, VotingClassifier
+from sklearn.linear_model import LogisticRegression
+from sklearn.svm import LinearSVC
+from sklearn.calibration import CalibratedClassifierCV
+from sklearn.preprocessing import MinMaxScaler
+from sklearn.metrics import classification_report, precision_recall_curve
+from scipy.sparse import hstack, csr_matrix
+import joblib
+
+from utils import preprocess_text, compute_metadata_features, META_FEATURE_NAMES
+
+warnings.filterwarnings('ignore', category=FutureWarning)
+warnings.filterwarnings('ignore', category=DeprecationWarning)
+
+project_dir = Path(__file__).parent
+data_dir = project_dir / 'data'
+models_dir = project_dir / 'models'
+feedback_csv = project_dir / 'feedback' / 'feedback_log.csv'
+random_state = 42
+KAGGLE_CAP = 100_000
+
+
+def load_feedback_corrections():
+    """Read feedback CSV and return a DataFrame of corrections."""
+    if not feedback_csv.exists():
+        print("No feedback file found.")
+        return pd.DataFrame(columns=['text', 'label'])
+
+    corrections = []
+    with open(feedback_csv, 'r', encoding='utf-8') as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            if row.get('feedback') == 'wrong' and row.get('correct_label'):
+                label = 1 if row['correct_label'].lower() == 'spam' else 0
+                corrections.append({
+                    'text': row['email_text'],
+                    'label': label,
+                })
+
+    df = pd.DataFrame(corrections)
+    print(f"Found {len(df)} corrections in feedback log.")
+    return df
+
+
+def main():
+    use_feedback = '--no-feedback' not in sys.argv
+
+    # --- Load original training data ---
+    print("Loading training data...")
+    kaggle_path = data_dir / 'spam_Emails_data.csv'
+    github_dir = data_dir / 'email-dataset-main' / 'email-dataset-main'
+
+    frames = []
+
+    if kaggle_path.exists():
+        kaggle_df = pd.read_csv(kaggle_path)
+        # Standardize column names
+        if 'label' in kaggle_df.columns and 'text' in kaggle_df.columns:
+            kaggle_df['label'] = kaggle_df['label'].map({'spam': 1, 'ham': 0})
+            kaggle_df = kaggle_df.dropna(subset=['label', 'text'])
+        elif 'v1' in kaggle_df.columns and 'v2' in kaggle_df.columns:
+            kaggle_df = kaggle_df.rename(columns={'v1': 'label_str', 'v2': 'text'})
+            kaggle_df['label'] = kaggle_df['label_str'].map({'spam': 1, 'ham': 0})
+            kaggle_df = kaggle_df[['text', 'label']].dropna()
+
+        if len(kaggle_df) > KAGGLE_CAP:
+            kaggle_df = kaggle_df.groupby('label', group_keys=False).apply(
+                lambda x: x.sample(min(len(x), KAGGLE_CAP // 2), random_state=random_state)
+            )
+        frames.append(kaggle_df[['text', 'label']])
+        print(f"  Kaggle: {len(kaggle_df)} emails")
+
+    if github_dir.exists():
+        for label_dir in github_dir.iterdir():
+            if label_dir.is_dir() and label_dir.name in ('spam', 'ham'):
+                lbl = 1 if label_dir.name == 'spam' else 0
+                for f in label_dir.iterdir():
+                    if f.is_file():
+                        try:
+                            text = f.read_text(encoding='utf-8', errors='ignore')
+                            frames.append(pd.DataFrame([{'text': text, 'label': lbl}]))
+                        except Exception:
+                            pass
+
+    if not frames:
+        print("ERROR: No training data found in data/ directory.")
+        sys.exit(1)
+
+    df = pd.concat(frames, ignore_index=True)
+    print(f"  Total original: {len(df)} emails")
+
+    # --- Merge feedback corrections ---
+    if use_feedback:
+        feedback_df = load_feedback_corrections()
+        if len(feedback_df) > 0:
+            df = pd.concat([df, feedback_df], ignore_index=True)
+            print(f"  After feedback merge: {len(df)} emails")
+
+    # --- Preprocess ---
+    print("Preprocessing...")
+    df['clean'] = df['text'].apply(preprocess_text)
+    df = df[df['clean'].str.len() > 0]
+
+    X_text = df['clean'].values
+    y = df['label'].values
+
+    # --- Split ---
+    X_train_text, X_test_text, y_train, y_test = train_test_split(
+        X_text, y, test_size=0.2, random_state=random_state, stratify=y
+    )
+
+    # --- TF-IDF ---
+    print("Fitting TF-IDF...")
+    tfidf = TfidfVectorizer(max_features=3000, ngram_range=(1, 3),
+                            min_df=2, max_df=0.95)
+    X_train_tfidf = tfidf.fit_transform(X_train_text)
+    X_test_tfidf = tfidf.transform(X_test_text)
+
+    # --- Metadata features ---
+    print("Computing metadata features...")
+    train_idx = df.index[df['clean'].isin(X_train_text)]
+    test_idx = df.index[df['clean'].isin(X_test_text)]
+
+    X_train_meta = compute_metadata_features(df.loc[train_idx, 'text'].tolist()[:len(X_train_text)])
+    X_test_meta = compute_metadata_features(df.loc[test_idx, 'text'].tolist()[:len(X_test_text)])
+
+    scaler = MinMaxScaler()
+    X_train_meta_scaled = scaler.fit_transform(X_train_meta)
+    X_test_meta_scaled = scaler.transform(X_test_meta)
+
+    # --- Combine ---
+    X_train = hstack([X_train_tfidf, csr_matrix(X_train_meta_scaled)])
+    X_test = hstack([X_test_tfidf, csr_matrix(X_test_meta_scaled)])
+
+    feature_names_list = tfidf.get_feature_names_out().tolist() + META_FEATURE_NAMES
+
+    # --- Train ensemble ---
+    print("Training VotingClassifier ensemble...")
+    ensemble = VotingClassifier(
+        estimators=[
+            ('rf', RandomForestClassifier(
+                n_estimators=200, n_jobs=-1,
+                class_weight='balanced', random_state=random_state)),
+            ('lr', LogisticRegression(
+                max_iter=1000, class_weight='balanced', random_state=random_state)),
+            ('svm', CalibratedClassifierCV(
+                LinearSVC(class_weight='balanced', max_iter=2000,
+                          random_state=random_state))),
+        ],
+        voting='soft',
+    )
+    ensemble.fit(X_train, y_train)
+
+    # --- Evaluate ---
+    y_pred = ensemble.predict(X_test)
+    print("\nClassification Report:")
+    print(classification_report(y_test, y_pred, target_names=['Ham', 'Spam']))
+
+    # --- Optimal threshold ---
+    y_scores = ensemble.predict_proba(X_test)[:, 1]
+    precisions, recalls, thresholds = precision_recall_curve(y_test, y_scores)
+    f1_scores = 2 * (precisions * recalls) / (precisions + recalls + 1e-8)
+    best_idx = np.argmax(f1_scores)
+    optimal_threshold = float(thresholds[best_idx])
+    print(f"Optimal threshold: {optimal_threshold:.4f}")
+
+    # --- Save ---
+    models_dir.mkdir(exist_ok=True)
+    joblib.dump(ensemble, models_dir / 'voting_model.joblib')
+    joblib.dump(tfidf, models_dir / 'tfidf_vectorizer.joblib')
+    joblib.dump(scaler, models_dir / 'meta_scaler.joblib')
+    joblib.dump(feature_names_list, models_dir / 'feature_names.joblib')
+    joblib.dump(optimal_threshold, models_dir / 'optimal_threshold.joblib')
+
+    # Training sample for LIME/SHAP background
+    sample_size = min(200, X_train.shape[0])
+    sample_idx = np.random.RandomState(random_state).choice(
+        X_train.shape[0], sample_size, replace=False)
+    training_sample = X_train[sample_idx].toarray()
+    joblib.dump(training_sample, models_dir / 'training_sample.joblib')
+
+    print(f"\nAll models saved to {models_dir}/")
+    if use_feedback:
+        corrections = load_feedback_corrections()
+        print(f"Feedback corrections incorporated: {len(corrections)}")
+
+
+if __name__ == '__main__':
+    main()
+```
+
+- [ ] **Step 2: Verify retrain.py runs with --no-feedback flag**
+
+```bash
+python3 retrain.py --no-feedback
+```
+
+Expected: Trains successfully, prints classification report, saves models.
+
+Note: This requires the `data/` directory to exist with training CSV. If data is symlinked, make sure the symlink works.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add retrain.py
+git commit -m "Add retrain.py with feedback CSV ingestion for batch retraining"
+```
+
+---
+
+### Task 7: Update README.md
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Update README.md frontmatter and description**
+
+Replace the entire contents of `README.md`:
+
+```markdown
+---
+title: Spam Email Classifier with XAI
+emoji: 📧
+colorFrom: blue
+colorTo: red
+sdk: gradio
+sdk_version: "4.44.0"
+app_file: app.py
+pinned: false
+license: mit
+tags:
+  - spam-detection
+  - xai
+  - lime
+  - shap
+  - eli5
+  - scikit-learn
+  - nlp
+  - explainable-ai
+---
+
+# Spam Email Classifier with XAI Explanations
+
+> **Disclaimer:** This model was created as a university course project. It is intended for **educational and research purposes only** and should not be used as a sole spam/phishing filter in production. Classification accuracy may vary. Always use established email security tools for real-world spam filtering.
+
+A Gradio web app that classifies emails as spam or ham and provides explainable AI (XAI) insights using three different methods.
+
+## Features
+
+- Paste any email and get an instant spam/ham prediction
+- **LIME** explanations — which words pushed the decision
+- **SHAP** feature importance — game-theoretic attribution
+- **ELI5** — model internal feature weights
+- **Side-by-side comparison** of all three XAI methods
+- **Plain English summary** of why the model made its decision
+- **User feedback** — thumbs up/down to log corrections for batch retraining
+- Adjustable classification threshold
+
+## How to Run Locally
+
+```bash
+pip install -r requirements.txt
+python train.py       # train the models (first time only)
+python app.py         # launch the Gradio app
+```
+
+## Retraining with Feedback
+
+```bash
+python retrain.py             # retrain with accumulated feedback corrections
+python retrain.py --no-feedback  # retrain with original data only
+```
+
+## Model
+
+Voting ensemble (Random Forest + Logistic Regression + SVM) trained on SpamAssassin + Enron email datasets using TF-IDF + 24 metadata features.
+
+## Tech Stack
+
+- scikit-learn (ensemble classifier)
+- LIME + SHAP + ELI5 (explainability)
+- Gradio (web interface)
+- NLTK (text preprocessing)
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "Update README with merged XAI features and feedback system"
+```
+
+---
+
+### Task 8: Update retrain.command wrapper
+
+**Files:**
+- Modify: `retrain.command`
+
+- [ ] **Step 1: Update the retrain shell wrapper**
+
+Replace `retrain.command` contents:
+
+```bash
+#!/bin/bash
+cd "$(dirname "$0")"
+source venv/bin/activate
+echo "============================================================"
+echo "  Spam Classifier — Retrain sklearn ensemble"
+echo "  Models: Random Forest + Logistic Regression + SVM"
+echo "  Includes: Feedback corrections from feedback/feedback_log.csv"
+echo "============================================================"
+echo ""
+echo "Options:"
+echo "  1) Retrain WITH feedback corrections (default)"
+echo "  2) Retrain WITHOUT feedback (original data only)"
+echo ""
+read -p "Choose [1/2]: " choice
+echo ""
+
+if [ "$choice" = "2" ]; then
+    python3 retrain.py --no-feedback
+else
+    python3 retrain.py
+fi
+
+echo ""
+echo "Done! Models saved to models/"
+echo ""
+echo "Press any key to close..."
+read -n 1
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add retrain.command
+git commit -m "Update retrain.command to support feedback-augmented retraining"
+```
+
+---
+
+### Task 9: End-to-end verification
+
+- [ ] **Step 1: Run existing tests to make sure utils.py still works**
+
+```bash
+cd spam-classifier-gradio
+source venv/bin/activate
+python3 -m pytest test_utils.py -v
+```
+
+Expected: All tests pass. We did not modify `utils.py` or `test_utils.py`.
+
+- [ ] **Step 2: Launch the app and test all features**
+
+```bash
+python3 app.py
+```
+
+Open `http://127.0.0.1:7860`. Test:
+
+1. Paste a spam example → verify Result tab shows SPAM with confidence
+2. Check LIME tab → bar chart renders
+3. Check SHAP tab → bar chart renders
+4. Check ELI5 tab → HTML table renders
+5. Check Compare tab → side-by-side table with agreement count
+6. Check Summary tab → plain English explanation
+7. Check How It Works tab → static educational content
+8. Click "Correct" → feedback message appears
+9. Click "Wrong" with "Ham" selected → correction logged
+10. Verify `feedback/feedback_log.csv` exists and has entries
+11. Adjust threshold slider → re-classify → label may change
+
+Stop the server.
+
+- [ ] **Step 3: Verify feedback CSV format**
+
+```bash
+cat feedback/feedback_log.csv
+```
+
+Expected: CSV with headers `timestamp,email_text,predicted_label,predicted_confidence,feedback,correct_label,threshold_used` and at least 2 rows from the tests above.
+
+- [ ] **Step 4: Final commit if any fixes were needed**
+
+```bash
+git add -A
+git commit -m "Fix any issues found during end-to-end testing"
+```
+
+Only run this if Step 2 or 3 revealed issues that required fixes.

docs/superpowers/specs/2026-03-28-gradio-xai-merge-design.md

@@ -0,0 +1,156 @@
+# Design: Merge XAI Features into Gradio Spam Classifier
+
+**Date:** 2026-03-28
+**Status:** Approved
+**Project:** spam-classifier-gradio (Hugging Face Space)
+
+## Goal
+
+Merge the best features from the Streamlit-based `spam-xai-project` into the existing `spam-classifier-gradio` Gradio app to create a single, unified spam classifier Space with full XAI explanations and a user feedback loop for batch retraining.
+
+## Decisions Made
+
+- **Primary model:** Voting Ensemble (RF + LR + SVM) from `spam-classifier-gradio`
+- **Drop Ollama/LLM features:** No Ollama on HF Spaces — replace with rule-based plain English summary
+- **Drop OCR:** No image upload — text paste only
+- **Drop Liquid AI Space:** Too large for free tier — remove from Spaces, keep as model repo
+- **Retire XAI Streamlit Space:** Single merged Gradio space replaces both
+- **Feedback:** Thumbs up/down logging to CSV + batch retrain script (not live retraining)
+- **Course context:** Generic "university course project" — no specific class number or semester
+
+## App Layout
+
+```
+┌─────────────────────────────────────────────────────┐
+│  # Spam Email Classifier with XAI Explanations      │
+│  Subtitle + educational disclaimer                  │
+├──────────────────────┬──────────────────────────────┤
+│  Email Text Input    │  Tabs:                       │
+│  (textarea, 12 rows) │  [Result] [LIME] [SHAP]     │
+│                      │  [ELI5] [Compare] [Summary]  │
+│  Upload .txt file    │  [How It Works]              │
+│                      │                              │
+│  Threshold slider    │  (content changes per tab)   │
+│  [0.0 ──●── 1.0]    │                              │
+│                      │  ┌──────────────────────┐    │
+│  [Classify] button   │  │  👍  👎  Feedback    │    │
+│                      │  │  (after classify)     │    │
+│  Example emails      │  └──────────────────────┘    │
+└──────────────────────┴──────────────────────────────┘
+```
+
+## 7 Tabs
+
+### 1. Result
+- Spam/ham label with confidence percentage
+- Threshold used for the classification
+- Key factors list (top 5 LIME features with direction)
+- Existing `generate_summary()` logic enhanced
+
+### 2. LIME
+- Horizontal bar chart (existing)
+- Caption: "LIME perturbs the input and fits a local model to see which features matter most"
+- 10 features shown, colored red (spam) / blue (ham)
+
+### 3. SHAP
+- Metadata feature bar chart (existing)
+- Caption: "SHAP uses game theory to assign each feature a contribution value"
+- Uses KernelExplainer on the 24 metadata features
+
+### 4. ELI5 (new)
+- HTML rendering of ELI5 feature weights via `eli5.format_as_html()`
+- Uses the RF sub-estimator extracted from VotingClassifier: `voting_model.named_estimators_['rf']`
+- Caption: "ELI5 shows feature weights directly from the model's internals"
+- Displayed in an HTML component within Gradio
+
+### 5. Compare (new)
+- Three columns showing top-5 features from LIME, SHAP, and ELI5
+- Each feature shows its direction (spam/ham) and weight
+- Note: LIME covers all features (TF-IDF + metadata), SHAP covers only the 24 metadata features, ELI5 covers all features via the RF sub-estimator. The comparison highlights where methods agree despite different feature scopes.
+- Feature agreement analysis: count of shared features between LIME and SHAP top-10
+- Lists the shared feature names
+
+### 6. Summary (new — replaces Ollama AI Explanation)
+- Rule-based plain English explanation built from XAI results
+- Template structure:
+  1. Classification statement with confidence
+  2. Top 3 LIME features with direction
+  3. Top 2 SHAP metadata features with human-readable descriptions
+  4. LIME-SHAP agreement note
+  5. Closing sentence based on spam/ham + confidence level
+- No LLM needed — string formatting from already-computed XAI data
+
+### 7. How It Works (new)
+- Static Markdown content explaining:
+  - What spam classification is and why it matters
+  - The model: Voting Ensemble (Random Forest + Logistic Regression + SVM)
+  - Feature extraction: TF-IDF (word importance) + 24 metadata features
+  - What each XAI method does in beginner-friendly language:
+    - LIME: "Tests what happens when words are removed"
+    - SHAP: "Calculates each feature's fair contribution using game theory"
+    - ELI5: "Shows the model's internal feature weights directly"
+  - What the feedback buttons do and how batch retraining works
+  - Educational disclaimer
+
+## Feedback System
+
+### User-facing UI
+- Appears below tabs after classification
+- Two buttons: "Correct" / "Wrong"
+- When "👎 Wrong" is clicked, a dropdown appears to select correct label ("Spam" / "Ham")
+- Counter shows: "X corrections collected"
+
+### Feedback storage
+- Logs to `feedback/feedback_log.csv`
+- Columns: `timestamp`, `email_text` (truncated 500 chars), `predicted_label`, `predicted_confidence`, `feedback` (correct/wrong), `correct_label` (if wrong), `threshold_used`
+- Directory created at app startup if missing
+- CSV appended to, never overwritten
+
+### Batch retrain
+- `retrain.py` script updated to:
+  1. Read `feedback/feedback_log.csv`
+  2. Filter for "wrong" entries
+  3. Convert corrections to training examples (email text + correct label)
+  4. Append to existing training data
+  5. Retrain VotingClassifier with augmented dataset
+  6. Save new model files to `models/`
+- Retrain runs locally, not live on the Space
+- Workflow: pull CSV from Space -> retrain locally -> push updated models back
+
+## Files Changed
+
+| File | Action | Details |
+|------|--------|---------|
+| `app.py` | Major update | Add ELI5, Compare, Summary, How It Works tabs + feedback UI + threshold slider |
+| `utils.py` | No changes | Shared preprocessing and feature engineering stays as-is |
+| `requirements.txt` | Update | Add `eli5>=0.13.0`, bump `gradio>=4.44.0` |
+| `retrain.py` | Update | Add feedback CSV ingestion for batch retraining |
+| `README.md` | Update | New frontmatter (tags, sdk_version) + updated feature description |
+| `feedback/.gitkeep` | New | Empty directory for feedback log accumulation |
+
+## Dependencies
+
+### Current (no changes)
+- numpy, pandas, matplotlib, scikit-learn, scipy, nltk, lime, shap, gradio, joblib, tqdm
+
+### New
+- `eli5>=0.13.0` — feature weight explanations from model internals
+
+### Removed (vs Streamlit app)
+- streamlit, pytesseract, PIL, requests, wordcloud, seaborn — none of these needed
+
+## ELI5 Integration Detail
+
+The VotingClassifier contains a RandomForestClassifier as `voting_model.named_estimators_['rf']`. ELI5's `explain_prediction()` works with sklearn tree-based models directly. We extract the RF sub-estimator at startup alongside the existing model loading, and pass it to ELI5 and SHAP TreeExplainer where needed.
+
+```python
+# Extract RF from voting ensemble for ELI5 and TreeExplainer
+raw_rf = voting_model.named_estimators_['rf']
+```
+
+## Deployment
+
+- Single Hugging Face Space: `VoltageVagabond/spam-classifier-gradio`
+- SDK: Gradio (free CPU tier — sklearn models are lightweight)
+- The `spam-xai-project` Space can be paused/deleted
+- The `spam-classifier-liquid-space` Space should be deleted (model stays as repo)

feedback/feedback_log.csv

@@ -0,0 +1,2 @@
+timestamp,email_text,predicted_label,predicted_confidence,feedback,correct_label,threshold_used
+2026-03-28T23:22:40.208203,test email,SPAM,0.9500,correct,,0.5000

requirements.txt

@@ -6,6 +6,7 @@ scipy>=1.11.0
 nltk>=3.8.0
 lime>=0.2.0
 shap>=0.44.0
-gradio==4.19.2
+eli5>=0.13.0
+gradio>=4.44.0
 joblib>=1.3.0
 tqdm>=4.65.0

retrain.py

@@ -0,0 +1,196 @@
+# Batch retrain script for the spam classifier
+# Reads feedback corrections from feedback/feedback_log.csv,
+# merges them into the original training data, and retrains
+# the VotingClassifier ensemble.
+#
+# Usage:
+#   python3 retrain.py              # retrain with feedback
+#   python3 retrain.py --no-feedback  # retrain with original data only
+
+import sys
+import csv
+import warnings
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.ensemble import RandomForestClassifier, VotingClassifier
+from sklearn.linear_model import LogisticRegression
+from sklearn.svm import LinearSVC
+from sklearn.calibration import CalibratedClassifierCV
+from sklearn.preprocessing import MinMaxScaler
+from sklearn.metrics import classification_report, precision_recall_curve
+from scipy.sparse import hstack, csr_matrix
+import joblib
+
+from utils import preprocess_text, compute_metadata_features, META_FEATURE_NAMES
+
+warnings.filterwarnings('ignore', category=FutureWarning)
+warnings.filterwarnings('ignore', category=DeprecationWarning)
+
+project_dir = Path(__file__).parent
+data_dir = project_dir / 'data'
+models_dir = project_dir / 'models'
+feedback_csv = project_dir / 'feedback' / 'feedback_log.csv'
+random_state = 42
+KAGGLE_CAP = 100_000
+
+
+def load_feedback_corrections():
+    """Read feedback CSV and return a DataFrame of corrections."""
+    if not feedback_csv.exists():
+        print("No feedback file found.")
+        return pd.DataFrame(columns=['text', 'label'])
+
+    corrections = []
+    with open(feedback_csv, 'r', encoding='utf-8') as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            if row.get('feedback') == 'wrong' and row.get('correct_label'):
+                label = 1 if row['correct_label'].lower() == 'spam' else 0
+                corrections.append({
+                    'text': row['email_text'],
+                    'label': label,
+                })
+
+    df = pd.DataFrame(corrections)
+    print(f"Found {len(df)} corrections in feedback log.")
+    return df
+
+
+def main():
+    use_feedback = '--no-feedback' not in sys.argv
+
+    print("Loading training data...")
+    kaggle_path = data_dir / 'spam_Emails_data.csv'
+    github_dir = data_dir / 'email-dataset-main' / 'email-dataset-main'
+
+    frames = []
+
+    if kaggle_path.exists():
+        kaggle_df = pd.read_csv(kaggle_path)
+        if 'label' in kaggle_df.columns and 'text' in kaggle_df.columns:
+            kaggle_df['label'] = kaggle_df['label'].map({'spam': 1, 'ham': 0})
+            kaggle_df = kaggle_df.dropna(subset=['label', 'text'])
+        elif 'v1' in kaggle_df.columns and 'v2' in kaggle_df.columns:
+            kaggle_df = kaggle_df.rename(columns={'v1': 'label_str', 'v2': 'text'})
+            kaggle_df['label'] = kaggle_df['label_str'].map({'spam': 1, 'ham': 0})
+            kaggle_df = kaggle_df[['text', 'label']].dropna()
+
+        if len(kaggle_df) > KAGGLE_CAP:
+            kaggle_df = kaggle_df.groupby('label', group_keys=False).apply(
+                lambda x: x.sample(min(len(x), KAGGLE_CAP // 2), random_state=random_state)
+            )
+        frames.append(kaggle_df[['text', 'label']])
+        print(f"  Kaggle: {len(kaggle_df)} emails")
+
+    if github_dir.exists():
+        for label_dir in github_dir.iterdir():
+            if label_dir.is_dir() and label_dir.name in ('spam', 'ham'):
+                lbl = 1 if label_dir.name == 'spam' else 0
+                for f in label_dir.iterdir():
+                    if f.is_file():
+                        try:
+                            text = f.read_text(encoding='utf-8', errors='ignore')
+                            frames.append(pd.DataFrame([{'text': text, 'label': lbl}]))
+                        except Exception:
+                            pass
+
+    if not frames:
+        print("ERROR: No training data found in data/ directory.")
+        sys.exit(1)
+
+    df = pd.concat(frames, ignore_index=True)
+    print(f"  Total original: {len(df)} emails")
+
+    if use_feedback:
+        feedback_df = load_feedback_corrections()
+        if len(feedback_df) > 0:
+            df = pd.concat([df, feedback_df], ignore_index=True)
+            print(f"  After feedback merge: {len(df)} emails")
+
+    print("Preprocessing...")
+    df['clean'] = df['text'].apply(preprocess_text)
+    df = df[df['clean'].str.len() > 0]
+
+    X_text = df['clean'].values
+    y = df['label'].values
+
+    X_train_text, X_test_text, y_train, y_test = train_test_split(
+        X_text, y, test_size=0.2, random_state=random_state, stratify=y
+    )
+
+    print("Fitting TF-IDF...")
+    tfidf = TfidfVectorizer(max_features=3000, ngram_range=(1, 3),
+                            min_df=2, max_df=0.95)
+    X_train_tfidf = tfidf.fit_transform(X_train_text)
+    X_test_tfidf = tfidf.transform(X_test_text)
+
+    print("Computing metadata features...")
+    # We need to get the original text (not cleaned) for metadata features
+    # Use index alignment with the split
+    train_orig = df.loc[df['clean'].isin(X_train_text), 'text'].values[:len(X_train_text)]
+    test_orig = df.loc[df['clean'].isin(X_test_text), 'text'].values[:len(X_test_text)]
+
+    X_train_meta = compute_metadata_features(train_orig.tolist())
+    X_test_meta = compute_metadata_features(test_orig.tolist())
+
+    scaler = MinMaxScaler()
+    X_train_meta_scaled = scaler.fit_transform(X_train_meta)
+    X_test_meta_scaled = scaler.transform(X_test_meta)
+
+    X_train = hstack([X_train_tfidf, csr_matrix(X_train_meta_scaled)])
+    X_test = hstack([X_test_tfidf, csr_matrix(X_test_meta_scaled)])
+
+    feature_names_list = tfidf.get_feature_names_out().tolist() + META_FEATURE_NAMES
+
+    print("Training VotingClassifier ensemble...")
+    ensemble = VotingClassifier(
+        estimators=[
+            ('rf', RandomForestClassifier(
+                n_estimators=200, n_jobs=-1,
+                class_weight='balanced', random_state=random_state)),
+            ('lr', LogisticRegression(
+                max_iter=1000, class_weight='balanced', random_state=random_state)),
+            ('svm', CalibratedClassifierCV(
+                LinearSVC(class_weight='balanced', max_iter=2000,
+                          random_state=random_state))),
+        ],
+        voting='soft',
+    )
+    ensemble.fit(X_train, y_train)
+
+    y_pred = ensemble.predict(X_test)
+    print("\nClassification Report:")
+    print(classification_report(y_test, y_pred, target_names=['Ham', 'Spam']))
+
+    y_scores = ensemble.predict_proba(X_test)[:, 1]
+    precisions, recalls, thresholds = precision_recall_curve(y_test, y_scores)
+    f1_scores = 2 * (precisions * recalls) / (precisions + recalls + 1e-8)
+    best_idx = np.argmax(f1_scores)
+    optimal_threshold = float(thresholds[best_idx])
+    print(f"Optimal threshold: {optimal_threshold:.4f}")
+
+    models_dir.mkdir(exist_ok=True)
+    joblib.dump(ensemble, models_dir / 'voting_model.joblib')
+    joblib.dump(tfidf, models_dir / 'tfidf_vectorizer.joblib')
+    joblib.dump(scaler, models_dir / 'meta_scaler.joblib')
+    joblib.dump(feature_names_list, models_dir / 'feature_names.joblib')
+    joblib.dump(optimal_threshold, models_dir / 'optimal_threshold.joblib')
+
+    sample_size = min(200, X_train.shape[0])
+    sample_idx = np.random.RandomState(random_state).choice(
+        X_train.shape[0], sample_size, replace=False)
+    training_sample = X_train[sample_idx].toarray()
+    joblib.dump(training_sample, models_dir / 'training_sample.joblib')
+
+    print(f"\nAll models saved to {models_dir}/")
+    if use_feedback:
+        corrections = load_feedback_corrections()
+        print(f"Feedback corrections incorporated: {len(corrections)}")
+
+
+if __name__ == '__main__':
+    main()