Initial clean commit for Hugging Face

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1 @@
+data/

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.9-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy files
+COPY requirements.txt .
+COPY app.py .
+COPY resnet18_cat.pth .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Expose Streamlit default port
+EXPOSE 7860
+
+# Healthcheck (optional)
+HEALTHCHECK CMD curl --fail http://localhost:7860/_stcore/health || exit 1
+
+# Run the Streamlit app using app.py
+CMD ["streamlit", "run", "app.py", "--server.port=7860", "--server.address=0.0.0.0"]

app.py

@@ -0,0 +1,239 @@
+import sys, types, os
+sys.modules['torch.classes'] = types.SimpleNamespace()
+os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"
+os.environ["STREAMLIT_WATCH_SYSTEM_FOLDERS"] = "false"
+
+import streamlit as st
+import torch
+import numpy as np
+import pickle
+from torchvision import models, transforms
+from torchcam.methods import GradCAM
+from torchcam.utils import overlay_mask
+from torchvision.transforms.functional import to_pil_image
+from sklearn.metrics.pairwise import cosine_distances
+import matplotlib.pyplot as plt
+import gzip
+from huggingface_hub import hf_hub_download
+
+st.set_page_config(layout="wide")
+
+st.markdown("""
+<style>
+/* Widen content area */
+.block-container {
+    padding: 3rem 5rem;
+    max-width: 95%;
+}
+
+/* Headings */
+h1 {
+    font-size: 2.5rem !important;
+    margin-bottom: 0.75rem;
+}
+h2 {
+    font-size: 2rem !important;
+    margin-top: 2rem;
+    margin-bottom: 0.5rem;
+}
+h3 {
+    font-size: 1.5rem !important;
+    margin-bottom: 0.5rem;
+}
+
+/* Paragraphs */
+p, li {
+    font-size: 1.15rem !important;
+    line-height: 1.7;
+    margin-bottom: 1rem;
+    text-align: left;
+}
+
+/* Sidebar tweaks */
+section[data-testid="stSidebar"] {
+    font-size: 1rem !important;
+}
+
+/* Metric values */
+[data-testid="stMetricValue"] {
+    font-size: 1.8rem !important;
+    color: #21c6b6;
+}
+</style>
+""", unsafe_allow_html=True)
+
+
+
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+CLASS_NAMES = ["fake", "real"]
+
+@st.cache_resource
+def load_model():
+    model = models.resnet18(weights=None)
+    model.fc = torch.nn.Linear(model.fc.in_features, 2)
+    model.load_state_dict(torch.load("resnet18_cat.pth", map_location=device))
+    model.to(device).eval()
+    return model
+
+
+@st.cache_data
+def load_embeddings():
+    # Download the file from your dataset repo
+    path = hf_hub_download(
+        repo_id="aryanj10/cat-xai-embeddings",
+        filename="embeddings.pkl.gz",
+        repo_type="dataset"
+    )
+
+    # Load gzip-compressed pickle file
+    with gzip.open(path, "rb") as f:
+        return pickle.load(f)
+
+
+model = load_model()
+
+# 🔌 Register hook for feature extraction
+feature_extractor = {}
+def hook_fn(module, input, output):
+    feature_extractor['features'] = output.flatten(1).detach()
+model.avgpool.register_forward_hook(hook_fn)
+
+cam_extractor = GradCAM(model, target_layer="layer4")
+data = load_embeddings()
+
+# ⛩ Sidebar
+st.sidebar.title("🔧 Options")
+st.sidebar.markdown("---")
+st.sidebar.markdown("📌 **Try These Indices**")
+st.sidebar.markdown("""
+- Fake ➡ Real: `13`, `18`, `34`, `40`  
+- Real ➡ Fake: `57`, `77`, `80`  
+Use them to explore how the model makes errors, and how XAI helps analyze them.
+""")
+test_idx = st.sidebar.number_input("Select Test Index", min_value=0, max_value=len(data["test_images"])-1, value=57)
+k_twins = st.sidebar.slider("Number of Twin Matches", 1, 10, value=3)
+
+# 🎯 Load and predict
+query_tensor = data["test_images"][test_idx]
+true_label = data["test_labels"][test_idx]
+query_input = query_tensor.unsqueeze(0).to(device)
+pred_label = model(query_input).argmax(1).item()
+
+important_cases = {
+    "Real ➡ Fake": [57, 77, 80],
+    "Fake ➡ Real": [13, 18, 34, 40]
+}
+for label, indices in important_cases.items():
+    if test_idx in indices:
+        st.info(f"📍 You're viewing a **{label}** misclassification test case.")
+
+
+# 🔥 Grad-CAM
+cam = cam_extractor(pred_label, model(query_input))[0].detach().cpu()
+img_display = query_tensor.cpu() * 0.5 + 0.5
+img_display = torch.clamp(img_display, 0, 1)
+orig_img = to_pil_image(img_display)
+cam_overlay = overlay_mask(orig_img, to_pil_image(cam.squeeze(0), mode='F'), alpha=0.5)
+
+# 🖼 Grad-CAM visual
+st.markdown("# 🐱 Fake-vs-Real Cat Classifier Explanation")
+
+st.markdown("""
+## 🧠 What This App Does
+
+This demo uses **Explainable AI (XAI)** techniques to classify cat images as either **Real** or **Fake** (AI-generated).  
+It reveals not only the **prediction**, but also the **reasoning** behind the decision using two complementary explainability tools:
+
+### 🔥 Grad-CAM  
+Shows **where** the model is "looking" by highlighting important image regions (like eyes, ears, fur).
+
+### 🧬 Twin System  
+Explains **why** a decision was made by comparing the test image's internal embedding with similar training examples.  
+Think: _“This image is close to these — and the model predicted them like this.”_
+
+---
+
+### 🧩 Setup Summary
+
+- **Model**: Fine-tuned `ResNet-18`
+- **Classes**: `real` = 1 `fake` = 0  
+- **Dataset**: 300 images (150 real + 150 fake)
+- **Validation Accuracy**: 91%
+""")
+
+
+
+st.markdown("## 🎯 Grad-CAM Explanation")
+
+st.markdown("""
+Grad-CAM (**Gradient-weighted Class Activation Mapping**) visualizes **where** the model focuses when making a prediction.  
+It uses backpropagation through the final convolutional layer to produce a **heatmap** of important regions.
+
+📌 In the images below:
+- **Left**: Original test image  
+- **Right**: Grad-CAM overlay — bright areas = higher model attention
+
+This helps you answer:
+
+> _“What part of the image led the model to this decision?”_
+""")
+st.subheader("🔥 Grad-CAM Visualization")
+
+cols = st.columns(2)
+cols[0].image(orig_img, caption="Original Image", use_container_width=True)
+cols[1].image(cam_overlay, caption=f"Grad-CAM (Pred: {CLASS_NAMES[pred_label]})", use_container_width=True)
+
+# 🧬 Twin System
+st.markdown("## 🧬 Twin System Explanation")
+
+st.markdown("""
+The **Twin System** provides an example-based explanation by retrieving **visually similar training images**.
+
+### 🔎 How it Works:
+- Embeddings from the `avgpool` layer are compared using **cosine similarity**
+- The top `k` most similar training images are shown
+- We display both the **true label** and **model prediction** for each
+
+This helps you answer:
+
+> _“What similar examples in the training set justify the model’s current prediction?”_
+""")
+st.subheader("🔎 Twin System Visualization")
+query_emb = data["test_embeddings"][test_idx].reshape(1, -1)
+distances = cosine_distances(query_emb, data["train_embeddings"])[0]
+same_class_idxs = np.where(data["train_labels"] == pred_label)[0]
+nearest_same = same_class_idxs[np.argsort(distances[same_class_idxs])[:k_twins]]
+
+twin_panel = [("Query", query_tensor, true_label)] + [
+    ("Twin", data["train_images"][i], data["train_labels"][i]) for i in nearest_same
+]
+
+row1, row2 = st.columns(len(twin_panel)), st.columns(len(twin_panel))
+for i, (title, img_tensor, label) in enumerate(twin_panel):
+    img_tensor_input = img_tensor.unsqueeze(0).to(device).requires_grad_()
+    pred = model(img_tensor_input).argmax(1).item()
+
+    cam = cam_extractor(pred, model(img_tensor_input))[0].detach().cpu()
+    img_display = img_tensor.cpu() * 0.5 + 0.5
+    img_display = torch.clamp(img_display, 0, 1)
+    orig = to_pil_image(img_display)
+    cam_overlay = overlay_mask(orig, to_pil_image(cam.squeeze(0), mode='F'), alpha=0.5)
+
+    row1[i].image(orig, caption=f"{title}\nLabel: {CLASS_NAMES[label]}", use_container_width=True)
+    row2[i].image(cam_overlay, caption=f"Grad-CAM\nPred: {CLASS_NAMES[pred]}", use_container_width=True)
+
+cam_extractor._hooks_enabled = False
+
+st.markdown("---")
+st.markdown("### 📊 Model Performance")
+col1, col2 = st.columns(2)
+with col1:
+    st.metric("Accuracy", "91%")
+    st.metric("F1 Score", "0.91")
+with col2:
+    st.metric("Precision (Real)", "0.94")
+    st.metric("Recall (Real)", "0.88")
+    st.metric("Precision (Fake)", "0.89")
+    st.metric("Recall (Fake)", "0.94")
+
+

readme.md

@@ -0,0 +1,180 @@
+# Explainable AI for Image Classification using Twin System and Grad-CAM
+
+**Author:** Aryan Jain    
+**Date:** May 17, 2025
+
+---
+
+## 🧠 Introduction
+
+Explainable Artificial Intelligence (XAI) is crucial in making machine learning models interpretable and trustworthy, especially in high-stakes or opaque domains. In this project, I applied two complementary post-hoc XAI techniques to a binary image classification problem — distinguishing between **real** and **AI-generated** (fake) cat images.
+
+The objective was two-fold:
+
+1. Build a strong classifier using a fine-tuned ResNet-18 model.
+2. Reveal the "why" behind its predictions using visual and example-based explanations.
+
+---
+
+## 🧰 XAI Techniques Used
+
+### 🔥 Grad-CAM (Gradient-weighted Class Activation Mapping)
+
+Grad-CAM highlights which parts of an image are most influential for the model's prediction. It works by backpropagating gradients to the final convolutional layers to generate heatmaps. These maps help users verify whether the model is focusing on the correct regions (e.g., ears, eyes, textures) — or being misled.
+
+✅ **Why use it?**  
+To visualize the evidence used by the network for classification decisions.
+
+📄 [Grad-CAM Paper](https://arxiv.org/abs/1610.02391)
+
+---
+
+### 🧠 Twin System (Case-Based Reasoning with Embeddings)
+
+The Twin System explains model predictions by retrieving visually similar training samples with the same predicted class. It computes cosine similarity between embeddings from the penultimate layer (`avgpool`) and shows the "nearest neighbors" from the training set.
+
+✅ **Why use it?**  
+To provide intuitive, example-based justification — similar to how a radiologist compares a scan with past known cases.
+
+📄 Based on: [This Looks Like That (2018)](https://arxiv.org/abs/1806.10574)
+
+---
+
+## 📊 Dataset
+
+- **Total Images:** 300
+  - 150 Real cat images from public datasets
+  - 150 Fake images generated using [`google/ddpm-cat-256`](https://arxiv.org/abs/2006.11239)
+
+### Preprocessing
+
+- Resized to `224x224`
+- Normalized using mean and std = 0.5 (CIFAR-style)
+
+### Train/Validation Split
+
+- **Training:** 100 real + 100 fake
+- **Validation:** 50 real + 50 fake
+
+---
+
+## 🏗️ Model Architecture
+
+- **Backbone:** Pretrained ResNet-18
+- Final layer modified for 2-class output (real vs. fake)
+
+### Training Configuration
+
+- Optimizer: Adam (`lr=1e-4`)
+- Loss Function: CrossEntropyLoss
+- Epochs: 10
+- Batch Size: 32
+
+✅ **Final Validation Accuracy:** 91%
+
+---
+
+### 📈 Evaluation Metrics
+
+- **Accuracy:** 91%
+- **Precision (Real):** 0.94, **Recall (Real):** 0.88
+- **Precision (Fake):** 0.89, **Recall (Fake):** 0.94
+- **F1 Score (Both):** 0.91
+
+![Confusion Matrix](Project/img/confusion_matrix.png)
+
+---
+
+## 🔬 Experiments
+
+### 🔍 Grad-CAM Visualizations
+
+Visual saliency maps for real and fake image samples:
+
+- ![Fake Sample 0](Project/img/sample_fake_0.png)
+- ![Fake Sample 1](Project/img/sample_fake_1.png)
+- ![Fake Sample 2](Project/img/sample_fake_2.png)
+- ![Real Sample 0](Project/img/sample_real_0.png)
+- ![Real Sample 1](Project/img/sample_real_1.png)
+- ![Real Sample 2](Project/img/sample_real_2.png)
+
+These overlays revealed that the model often attended to fur patterns, eye shapes, and ear positions for its predictions.
+
+---
+
+### 🧠 Twin System Visualizations
+
+Twin explanations retrieved training examples similar to a test image **from the same predicted class**, validating the classifier's reasoning.
+
+- ![Twin Test 6](Project/img/twin_vis_test6.png)
+- ![Twin Test 17](Project/img/twin_vis_test17.png)
+- ![Twin Test 13](Project/img/twin_vis_test13.png)
+- ![Twin Test 18](Project/img/twin_vis_test18.png)
+- ![Twin Test 57](Project/img/twin_vis_test57.png)
+- ![Twin Test 77](Project/img/twin_vis_test77.png)
+
+---
+
+### ❌ Misclassification Analysis
+
+- **Real ➡ Fake (False Negatives):** `[13, 18, 22, 34, 40, 44]`
+- **Fake ➡ Real (False Positives):** `[57, 77, 80]`
+
+Grad-CAM and Twin System helped investigate these edge cases. In many cases, blur or unusual poses in real images confused the classifier.
+
+---
+
+## ✅ Conclusion
+
+By combining Grad-CAM with the Twin System, this project achieved a richer interpretability framework:
+
+| Technique | Purpose | Value |
+|----------|---------|-------|
+| **Grad-CAM** | Pixel-level explanation | Shows *where* the model is looking |
+| **Twin System** | Example-based reasoning | Shows *why* via similarity to past cases |
+
+This multi-view approach fosters transparency and trust in AI-powered image classifiers.
+
+---
+
+## 🚀 Future Work
+
+- Introduce **counterfactual explanations** (e.g., nearest neighbors from the opposite class)
+- Replace cosine similarity with **CLIP embeddings** for semantic similarity
+- Improve Twin System with a **ProtoPNet architecture**
+
+---
+
+### 🧪 ProtoPNet Attempt
+
+- Architecture: ResNet-18 backbone with 10 learned prototypes per class
+- Goal: Learn localized regions (patches) that support classification
+
+#### Results
+
+- **Validation Accuracy:** 50%
+- **Problem:** Overfitted to "real" class due to prototype imbalance
+
+![Proto Confusion Matrix](Project/img/protopnet_confmat.png)
+
+#### Learned Prototypes
+
+![ProtoPNet Prototypes](Project/img/protopnet_prototypes.png)
+
+Despite underperformance, I successfully:
+
+- Trained the ProtoPNet architecture
+- Projected prototypes to most activating image patches
+- Visualized top-activating examples for each prototype
+
+Future work will address class imbalance and refine prototype usefulness.
+
+---
+
+## 🧾 References
+
+- [Grad-CAM: Visual Explanations from Deep Networks](https://arxiv.org/abs/1610.02391) - Selvaraju et al., ICCV 2017  
+- [Denoising Diffusion Probabilistic Models](https://arxiv.org/abs/2006.11239) - Ho et al., NeurIPS 2020  
+- [TorchCAM Library](https://frgfm.github.io/torch-cam/)  
+- [This Looks Like That](https://arxiv.org/abs/1806.10574) - Chen et al., 2018  
+- [Case-Based Interpretable DL for Mammography](https://www.nature.com/articles/s42256-021-00400-0) - Barnett et al., Nature Machine Intelligence, 2021  

requirements.txt

@@ -0,0 +1,11 @@
+torch>=2.0.0
+torchvision>=0.15.0
+tqdm
+scikit-learn
+matplotlib
+seaborn
+torchcam
+Pillow
+numpy
+streamlit
+huggingface_hub

resnet18_cat.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8d751e04dbe62ec58b9559d5c35b2002b911b6b64814f3d0c8e522265efc332f
+size 44790027