Initial commit for XAI Space

README.md

@@ -0,0 +1,25 @@
+---
+title: DeepfakeDet-ViT XAI & Forensics Suite
+emoji: 🔬
+colorFrom: emerald
+colorTo: slate
+sdk: gradio
+sdk_version: "6.0.1"
+app_file: app.py
+pinned: false
+license: apache-2.0
+models:
+  - buildborderless/CommunityForensics-DeepfakeDet-ViT
+datasets:
+  - buildborderless/deepfake-explainability
+---
+
+# DeepfakeDet-ViT XAI & Digital Forensics Suite
+
+Interactive explainability dashboard and digital forensics suite for the **ViT-Small Deepfake Classifier** (`buildborderless/CommunityForensics-DeepfakeDet-ViT`).
+
+## Features
+- **7 ViT Attribution Methods**: Attention Rollout, Chefer Gradient-Rollout, GradCAM, Integrated Gradients, DeepLIFT, Occlusion Sensitivity, Per-Head Attention.
+- **5 Classic Digital Forensics Tools**: Error Level Analysis (ELA), Spatial Edge Gradient, Bit Plane Extractor, MinMax Deviation, Wavelet Noise Estimation.
+- **Forensic Report Generator**: Export multi-panel high-DPI infographic report PNGs.
+- **Dataset Integration**: Log predictions, user ground truth feedback (Real / Fake / FP / FN), and 7-method composite XAI heatmaps to `buildborderless/deepfake-explainability`.

app.py

@@ -0,0 +1,214 @@
+import os
+import base64
+from io import BytesIO
+from PIL import Image
+import gradio as gr
+from gradio import Server
+from gradio.data_classes import FileData
+from fastapi.responses import HTMLResponse
+
+from xai_engine.model import get_model
+from xai_engine.methods import run_all_methods, run_single_method, run_per_head_attention
+from forensics.runner import run_forensic_tool
+from report import generate_forensic_report
+from logger import log_run_dataset
+
+# Initialize Gradio Server app
+app = Server(title="DeepfakeDet-ViT XAI & Forensics Suite")
+
+
+def b64_to_pil(b64_str: str) -> Image.Image:
+    """Helper to convert base64 image data URL to PIL Image."""
+    if not b64_str or not isinstance(b64_str, str):
+        raise ValueError("Invalid base64 image string provided.")
+    if "," in b64_str:
+        _, data = b64_str.split(",", 1)
+    else:
+        data = b64_str
+    image_data = base64.b64decode(data)
+    return Image.open(BytesIO(image_data)).convert("RGB")
+
+
+@app.api(name="analyze")
+def analyze_api(image_b64: str, alpha: float = 0.6, cmap: str = "jet") -> dict:
+    """
+    Run complete ViT Deepfake analysis + 6 attribution methods.
+    Returns prediction summary and list of attribution map overlays.
+    """
+    try:
+        image = b64_to_pil(image_b64)
+    except Exception as e:
+        return {"status": "error", "message": f"Image decoding failed: {e}"}
+
+    model = get_model()
+    pred_data = model.predict(image)
+    results = run_all_methods(model, image, alpha=alpha, cmap=cmap)
+
+    res_dicts = [
+        {
+            "name": r.name,
+            "description": r.description,
+            "overlay_b64": r.overlay_b64,
+            "raw_heatmap_b64": r.raw_heatmap_b64,
+            "metadata": r.metadata,
+            "compute_time_ms": r.compute_time_ms,
+        }
+        for r in results
+    ]
+
+    return {
+        "status": "success",
+        "prediction": pred_data,
+        "results": res_dicts,
+    }
+
+
+@app.api(name="method_detail")
+def method_detail_api(
+    image_b64: str,
+    method_name: str,
+    steps: int = 20,
+    patch_size: int = 32,
+    stride: int = 16,
+    target_layer_idx: int = 11,
+    alpha: float = 0.6,
+    cmap: str = "jet",
+) -> dict:
+    """Deep-dive analysis for a single specified XAI method with custom parameters."""
+    try:
+        image = b64_to_pil(image_b64)
+    except Exception as e:
+        return {"status": "error", "message": f"Image decoding failed: {e}"}
+
+    model = get_model()
+    res = run_single_method(
+        model, image, method_name,
+        alpha=alpha, cmap=cmap, steps=steps,
+        patch_size=patch_size, stride=stride,
+        target_layer_idx=target_layer_idx,
+    )
+
+    return {
+        "status": "success",
+        "result": {
+            "name": res.name,
+            "description": res.description,
+            "overlay_b64": res.overlay_b64,
+            "raw_heatmap_b64": res.raw_heatmap_b64,
+            "metadata": res.metadata,
+            "compute_time_ms": res.compute_time_ms,
+        }
+    }
+
+
+@app.api(name="heads")
+def heads_api(image_b64: str, layer_idx: int = 11, cmap: str = "jet") -> dict:
+    """Extract and visualize all 6 attention heads for a selected transformer layer."""
+    try:
+        image = b64_to_pil(image_b64)
+    except Exception as e:
+        return {"status": "error", "message": f"Image decoding failed: {e}"}
+
+    model = get_model()
+    head_data = run_per_head_attention(model, image, layer_idx=layer_idx, cmap=cmap)
+    head_data["status"] = "success"
+    return head_data
+
+
+@app.api(name="forensic")
+def forensic_api(
+    image_b64: str,
+    tool_name: str,
+    quality: int = 75,
+    scale: int = 50,
+    contrast: int = 20,
+    gradient_intensity: int = 90,
+    blue_mode: str = "Abs",
+    channel: str = "Luminance",
+    bit: int = 0,
+    minmax_radius: int = 2,
+) -> dict:
+    """Run classic digital forensic analysis (ELA, Gradient, BitPlane, MinMax, Wavelet)."""
+    try:
+        image = b64_to_pil(image_b64)
+    except Exception as e:
+        return {"status": "error", "message": f"Image decoding failed: {e}"}
+
+    res = run_forensic_tool(
+        image, tool_name,
+        quality=quality, scale=scale, contrast=contrast,
+        gradient_intensity=gradient_intensity, blue_mode=blue_mode,
+        channel=channel, bit=bit, minmax_radius=minmax_radius,
+    )
+    res["status"] = "success"
+    return res
+
+
+@app.api(name="report")
+def report_api(image_b64: str) -> FileData:
+    """Generate and return downloadable multi-panel forensic report PNG."""
+    image = b64_to_pil(image_b64)
+    model = get_model()
+    pred_data = model.predict(image)
+    results = run_all_methods(model, image)
+    report_path = generate_forensic_report(image, pred_data, results)
+    return FileData(path=report_path)
+
+
+@app.api(name="submit_run")
+def submit_run_api(
+    image_b64: str,
+    ground_truth: str = "unknown",
+    opt_in_image: bool = True,
+) -> dict:
+    """Log analysis run, prediction, ground truth feedback, and XAI composite heatmaps to dataset."""
+    try:
+        image = b64_to_pil(image_b64)
+    except Exception as e:
+        return {"status": "error", "message": f"Image decoding failed: {e}"}
+
+    model = get_model()
+    pred_data = model.predict(image)
+    results = run_all_methods(model, image)
+    run_id = log_run_dataset(image, pred_data, results, ground_truth=ground_truth, opt_in_image=opt_in_image)
+
+    return {
+        "status": "success",
+        "run_id": run_id,
+        "message": f"Run {run_id} successfully submitted to dataset!",
+    }
+
+
+@app.get("/api/config")
+def client_config():
+    """Return model and space configuration for frontend initialization."""
+    return {
+        "model_name": "buildborderless/CommunityForensics-DeepfakeDet-ViT",
+        "model_architecture": "ViT-Small (384x384, 12 layers, 6 heads)",
+        "xai_methods": [
+            {"id": "rollout", "name": "Attention Rollout"},
+            {"id": "chefer", "name": "Gradient Attention Rollout (Chefer)"},
+            {"id": "gradcam", "name": "GradCAM"},
+            {"id": "integrated", "name": "Integrated Gradients"},
+            {"id": "deeplift", "name": "DeepLIFT"},
+            {"id": "occlusion", "name": "Occlusion Sensitivity"},
+        ],
+        "forensic_tools": [
+            {"id": "ela", "name": "Error Level Analysis (ELA)"},
+            {"id": "gradient", "name": "Spatial Edge Gradient"},
+            {"id": "bitplane", "name": "Bit Plane Extractor"},
+            {"id": "minmax", "name": "MinMax Deviation"},
+            {"id": "wavelet", "name": "Wavelet Noise Estimation"},
+        ]
+    }
+
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage():
+    html_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "index.html")
+    with open(html_path, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+if __name__ == "__main__":
+    app.launch(show_error=True)

forensics/__init__.py

@@ -0,0 +1,15 @@
+from .bitplane import bit_plane_extractor
+from .ela import ELA
+# from .exif import exif_full_dump
+from .gradient import gradient_processing
+from .minmax import minmax_process
+from .wavelet import noise_estimation
+
+__all__ = [
+    'bit_plane_extractor',
+    'ELA',
+     # 'exif_full_dump',
+    'gradient_processing',
+    'minmax_process',
+    'noise_estimation'
+] 

forensics/bitplane.py

@@ -0,0 +1,34 @@
+import cv2 as cv
+import numpy as np
+from PIL import Image
+
+def bit_plane_extractor(
+    image: Image.Image,
+    channel: str = "Luminance",
+    bit: int = 0,
+    filter_type: str = "Disabled"
+) -> Image.Image:
+    """Extract and visualize a bit plane from a selected channel of the image.
+
+    Args:
+        image (Image.Image, string: filepath): The input image to analyze.
+        channel (str, optional): The channel to extract. Defaults to "Luminance".
+        bit (int, optional): The bit to extract. Defaults to 0.
+        filter_type (str, optional): The type of filter to apply. Defaults to "Disabled".
+    """
+    img = np.array(image.convert("RGB"))
+    if channel == "Luminance":
+        img = cv.cvtColor(img, cv.COLOR_RGB2GRAY)
+    elif channel == "RGB Norm":
+        b, g, r = cv.split(img.astype(np.float64))
+        img = np.sqrt(np.power(b, 2) + np.power(g, 2) + np.power(r, 2)).astype(np.uint8)
+    else:
+        idx = {"Red": 0, "Green": 1, "Blue": 2}[channel]
+        img = img[:, :, idx]
+    plane = cv.bitwise_and(np.full_like(img, 2 ** bit), img)
+    plane = cv.normalize(plane, None, 0, 255, cv.NORM_MINMAX).astype(np.uint8)
+    if filter_type == "Median":
+        plane = cv.medianBlur(plane, 3)
+    elif filter_type == "Gaussian":
+        plane = cv.GaussianBlur(plane, (3, 3), 0)
+    return Image.fromarray(plane) 

forensics/ela.py

@@ -0,0 +1,64 @@
+import numpy as np
+import cv2 as cv
+from time import time
+from PIL import Image
+
+def compress_jpg(image, quality):
+    """Compress image using JPEG compression."""
+    encode_param = [int(cv.IMWRITE_JPEG_QUALITY), quality]
+    _, buffer = cv.imencode('.jpg', image, encode_param)
+    return cv.imdecode(buffer, cv.IMREAD_COLOR)
+
+def desaturate(image):
+    """Convert image to grayscale."""
+    return cv.cvtColor(image, cv.COLOR_BGR2GRAY)
+
+def create_lut(contrast, brightness):
+    """Create lookup table for contrast and brightness adjustment."""
+    lut = np.arange(256, dtype=np.uint8)
+    lut = cv.LUT(lut, lut)
+    lut = cv.convertScaleAbs(lut, None, contrast/128, brightness)
+    return lut
+
+def elapsed_time(start):
+    """Calculate elapsed time since start."""
+    return f"{time() - start:.3f}s"
+
+def ELA(img, quality=75, scale=50, contrast=20, linear=False, grayscale=False):
+    """
+    Perform Error Level Analysis on an image.
+    
+    Args:
+        img: Input image (numpy array)
+        quality: JPEG compression quality (1-100)
+        scale: Output multiplicative gain (1-100)
+        contrast: Output tonality compression (0-100)
+        linear: Whether to use linear difference
+        grayscale: Whether to output grayscale image
+    
+    Returns:
+        Processed ELA image
+    """
+    # Convert image to float32 and normalize
+    original = img.astype(np.float32) / 255
+    
+    # Compress image
+    compressed = compress_jpg(img, quality)
+    compressed = compressed.astype(np.float32) / 255
+    
+    # Calculate difference based on mode
+    if not linear:
+        difference = cv.absdiff(original, compressed)
+        ela = cv.convertScaleAbs(cv.sqrt(difference) * 255, None, scale / 20)
+    else:
+        ela = cv.convertScaleAbs(cv.subtract(compressed, img), None, scale)
+    
+    # Apply contrast adjustment
+    contrast_value = int(contrast / 100 * 128)
+    ela = cv.LUT(ela, create_lut(contrast_value, contrast_value))
+    
+    # Convert to grayscale if requested
+    if grayscale:
+        ela = desaturate(ela)
+    
+    return Image.fromarray(ela) 

forensics/exif.py

@@ -0,0 +1,11 @@
+# import tempfile
+# import exiftool
+# from PIL import Image
+
+# def exif_full_dump(image: Image.Image) -> dict:
+#     """Extract all EXIF metadata from an image using exiftool."""
+#     with tempfile.NamedTemporaryFile(suffix='.jpg', delete=True) as tmp:
+#         image.save(tmp.name)
+#         with exiftool.ExifTool() as et:
+#             metadata = et.get_metadata(tmp.name)
+#     return metadata 

forensics/gradient.py

@@ -0,0 +1,62 @@
+import numpy as np
+import cv2 as cv
+from PIL import Image
+
+def norm_mat(mat):
+    return cv.normalize(mat, None, 0, 255, cv.NORM_MINMAX).astype(np.uint8)
+
+def equalize_img(img):
+    ycrcb = cv.cvtColor(img, cv.COLOR_BGR2YCrCb)
+    ycrcb[:, :, 0] = cv.equalizeHist(ycrcb[:, :, 0])
+    return cv.cvtColor(ycrcb, cv.COLOR_YCrCb2BGR)
+
+def create_lut(intensity, gamma):
+    lut = np.zeros((256, 1, 3), dtype=np.uint8)
+    for i in range(256):
+        lut[i, 0, 0] = min(255, max(0, i + intensity))
+        lut[i, 0, 1] = min(255, max(0, i + intensity))
+        lut[i, 0, 2] = min(255, max(0, i + intensity))
+    return lut
+
+def gradient_processing(image, intensity=90, blue_mode="Abs", invert=False, equalize=False):
+    """Apply gradient processing to an image. 
+
+    Args:
+        image (Image.Image, string: filepath): The input image to analyze.
+        intensity (int, optional): The intensity of the gradient. Defaults to 90.
+        blue_mode (str, optional): The mode to use for the blue channel. Defaults to "Abs".
+        invert (bool, optional): Whether to invert the gradient. Defaults to False.
+        equalize (bool, optional): Whether to equalize the gradient. Defaults to False.
+
+    Returns:
+        Image.Image: A PIL image of the gradient.
+    """    
+    image = np.array(image)
+    dx, dy = cv.spatialGradient(cv.cvtColor(image, cv.COLOR_BGR2GRAY))
+    intensity = int(intensity / 100 * 127)
+    if invert:
+        dx = (-dx).astype(np.float32)
+        dy = (-dy).astype(np.float32)
+    else:
+        dx = (+dx).astype(np.float32)
+        dy = (+dy).astype(np.float32)
+    dx_abs = np.abs(dx)
+    dy_abs = np.abs(dy)
+    red = ((dx / np.max(dx_abs) * 127) + 127).astype(np.uint8)
+    green = ((dy / np.max(dy_abs) * 127) + 127).astype(np.uint8)
+    if blue_mode == "None":
+        blue = np.zeros_like(red)
+    elif blue_mode == "Flat":
+        blue = np.full_like(red, 255)
+    elif blue_mode == "Abs":
+        blue = norm_mat(dx_abs + dy_abs)
+    elif blue_mode == "Norm":
+        blue = norm_mat(np.linalg.norm(cv.merge((red, green)), axis=2))
+    else:
+        blue = None
+    gradient = cv.merge([blue, green, red])
+    if equalize:
+        gradient = equalize_img(gradient)
+    elif intensity > 0:
+        gradient = cv.LUT(gradient, create_lut(intensity, intensity))
+    return Image.fromarray(gradient) 

forensics/minmax.py

@@ -0,0 +1,94 @@
+import numpy as np
+import cv2 as cv
+from PIL import Image
+
+def norm_mat(mat):
+    return cv.normalize(mat, None, 0, 255, cv.NORM_MINMAX).astype(np.uint8)
+
+def minmax_dev(patch, mask):
+    c = patch[1, 1]
+    minimum, maximum, _, _ = cv.minMaxLoc(patch, mask)
+    if c < minimum:
+        return -1
+    if c > maximum:
+        return +1
+    return 0
+
+def blk_filter(img, radius):
+    result = np.zeros_like(img, np.float32)
+    rows, cols = result.shape
+    block = 2 * radius + 1
+    for i in range(radius, rows, block):
+        for j in range(radius, cols, block):
+            result[
+                i - radius : i + radius + 1, j - radius : j + radius + 1
+            ] = np.std(
+                img[i - radius : i + radius + 1, j - radius : j + radius + 1]
+            )
+    return cv.normalize(result, None, 0, 127, cv.NORM_MINMAX, cv.CV_8UC1)
+
+def minmax_process(image, channel=4, radius=2):
+    """
+    Analyzes local pixel value deviations in an image to detect potential manipulation by comparing each pixel with its neighbors. This forensic technique helps identify areas where pixel values deviate significantly from their local context, which can indicate digital tampering or editing.
+    
+    Args:
+        image: Union[np.ndarray, Image.Image]: Input image to process
+        channel (int): Channel to process (0:Grayscale, 1:Blue, 2:Green, 3:Red, 4:RGB Norm)
+        radius (int): Radius for block filtering
+    Returns:
+        PIL.Image.Image: The processed image showing minmax deviations.
+    Raises:
+        ValueError: If the input image is invalid or channel/radius parameters are out of valid range.
+    """
+    if not isinstance(image, np.ndarray):
+        image = np.array(image)  # Ensure image is a NumPy array
+    if channel == 0:
+        img = cv.cvtColor(image, cv.COLOR_BGR2GRAY)
+    elif channel == 4:
+        b, g, r = cv.split(image.astype(np.float64))
+        img = cv.sqrt(cv.pow(b, 2) + cv.pow(g, 2) + cv.pow(r, 2))
+    else:
+        img = image[:, :, 3 - channel]
+    kernel = 3
+    border = kernel // 2
+    shape = (img.shape[0] - kernel + 1, img.shape[1] - kernel + 1, kernel, kernel)
+    strides = 2 * img.strides
+    patches = np.lib.stride_tricks.as_strided(img, shape=shape, strides=strides)
+    patches = patches.reshape((-1, kernel, kernel))
+    mask = np.full((kernel, kernel), 255, dtype=np.uint8)
+    mask[border, border] = 0
+    blocks = [0] * shape[0] * shape[1]
+    for i, patch in enumerate(patches):
+        blocks[i] = minmax_dev(patch, mask)
+    output = np.array(blocks).reshape(shape[:-2])
+    output = cv.copyMakeBorder(
+        output, border, border, border, border, cv.BORDER_CONSTANT
+    )
+    low = output == -1
+    high = output == +1
+    minmax = np.zeros_like(image)
+    if radius > 0:
+        radius += 3
+        low = blk_filter(low, radius)
+        high = blk_filter(high, radius)
+        if channel <= 2:
+            minmax[:, :, 2 - channel] = low
+            minmax[:, :, 2 - channel] += high
+        else:
+            minmax = np.repeat(low[:, :, np.newaxis], 3, axis=2)
+            minmax += np.repeat(high[:, :, np.newaxis], 3, axis=2)
+        minmax = norm_mat(minmax)
+    else:
+        if channel == 0:
+            minmax[low] = [0, 0, 255]
+            minmax[high] = [0, 0, 255]
+        elif channel == 1:
+            minmax[low] = [0, 255, 0]
+            minmax[high] = [0, 255, 0]
+        elif channel == 2:
+            minmax[low] = [255, 0, 0]
+            minmax[high] = [255, 0, 0]
+        elif channel == 3:
+            minmax[low] = [255, 255, 255]
+            minmax[high] = [255, 255, 255]
+    return Image.fromarray(minmax) 

forensics/runner.py

@@ -0,0 +1,79 @@
+"""
+Unified runner for classic digital forensics tools.
+Wraps ELA, Spatial Gradient, Bit Plane, MinMax Deviation, and Wavelet Noise.
+"""
+
+import time
+import numpy as np
+from PIL import Image
+from .ela import ELA
+from .gradient import gradient_processing
+from .bitplane import bit_plane_extractor
+from .minmax import minmax_process
+from .wavelet import noise_estimation
+from xai_engine.viz import to_b64_png
+
+
+def run_forensic_tool(
+    image: Image.Image,
+    tool_name: str,
+    quality: int = 75,
+    scale: int = 50,
+    contrast: int = 20,
+    gradient_intensity: int = 90,
+    blue_mode: str = "Abs",
+    channel: str = "Luminance",
+    bit: int = 0,
+    minmax_radius: int = 2,
+) -> dict:
+    """
+    Execute selected forensic tool on input image.
+    
+    Returns dict: {
+        "tool": str,
+        "result_b64": str,
+        "info": str,
+        "compute_time_ms": float
+    }
+    """
+    t0 = time.perf_counter()
+    img_np = np.array(image.convert("RGB"))
+    info_text = ""
+
+    if tool_name == "ela":
+        name = "Error Level Analysis (ELA)"
+        res_img = ELA(img_np, quality=quality, scale=scale, contrast=contrast)
+        info_text = f"JPEG Compression Quality: {quality}%, Scale: {scale}, Contrast: {contrast}%"
+
+    elif tool_name == "gradient":
+        name = "Spatial Gradient Analysis"
+        res_img = gradient_processing(image, intensity=gradient_intensity, blue_mode=blue_mode)
+        info_text = f"Gradient Intensity: {gradient_intensity}%, Blue Mode: {blue_mode}"
+
+    elif tool_name == "bitplane":
+        name = "Bit Plane Extractor"
+        res_img = bit_plane_extractor(image, channel=channel, bit=bit)
+        info_text = f"Channel: {channel}, Bit Plane: {bit} (0=LSB, 7=MSB)"
+
+    elif tool_name == "minmax":
+        name = "MinMax Local Deviation"
+        res_img = minmax_process(img_np, channel=4, radius=minmax_radius)
+        info_text = f"Local Block Radius: {minmax_radius} px"
+
+    elif tool_name == "wavelet":
+        name = "Wavelet Noise Estimation"
+        noise_var = noise_estimation(img_np)
+        info_text = f"Estimated High-Frequency Noise Variance: {noise_var:.4f}"
+        res_img = image.convert("RGB")  # Return original with overlay text or noise metric
+
+    else:
+        raise ValueError(f"Unknown forensic tool: {tool_name}")
+
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+
+    return {
+        "tool": name,
+        "result_b64": to_b64_png(res_img),
+        "info": info_text,
+        "compute_time_ms": round(elapsed_ms, 1),
+    }

forensics/wavelet.py

@@ -0,0 +1,28 @@
+import numpy as np
+import pywt
+import cv2
+from PIL import Image
+
+def noise_estimation(image: Image.Image, blocksize: int = 8) -> Image.Image:
+    """Estimate local noise using wavelet blocking. Returns a PIL image of the noise map.
+
+    Args:
+        image (Image.Image, string: filepath): The input image to analyze.
+        blocksize (int): The size of the blocks to use for wavelet blocking.
+
+    Returns:
+        Image.Image: A PIL image of the noise map.
+    """    
+    im = np.array(image.convert('L'))
+    y = np.double(im)
+    cA1, (cH, cV, cD) = pywt.dwt2(y, 'db8')
+    cD = cD[:cD.shape[0] // blocksize * blocksize, :cD.shape[1] // blocksize * blocksize]
+    block = np.zeros((cD.shape[0] // blocksize, cD.shape[1] // blocksize, blocksize ** 2))
+    for ii in range(0, cD.shape[0] - blocksize + 1, blocksize):
+        for jj in range(0, cD.shape[1] - blocksize + 1, blocksize):
+            block_elements = cD[ii:ii+blocksize, jj:jj+blocksize]
+            block[ii // blocksize, jj // blocksize, :] = block_elements.flatten()
+    noise_map = np.median(np.abs(block), axis=2) / 0.6745
+    noise_map_8u = cv2.normalize(noise_map, None, 0, 255, cv2.NORM_MINMAX, dtype=cv2.CV_8U)
+    resized_noise_map = cv2.resize(noise_map_8u, (im.shape[1], im.shape[0]), interpolation=cv2.INTER_NEAREST)
+    return Image.fromarray(resized_noise_map) 

index.html

@@ -0,0 +1,532 @@
+<!DOCTYPE html>
+<html lang="en" class="dark">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>DeepfakeDet-ViT — XAI & Digital Forensics Suite</title>
+  <!-- Tailwind CSS -->
+  <script src="https://cdn.tailwindcss.com"></script>
+  <!-- FontAwesome Icons -->
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css" />
+  <!-- Google Fonts -->
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
+  <script>
+    tailwind.config = {
+      darkMode: 'class',
+      theme: {
+        extend: {
+          fontFamily: {
+            sans: ['Inter', 'sans-serif'],
+            mono: ['JetBrains Mono', 'monospace'],
+          },
+          colors: {
+            brand: {
+              50: '#f0fdfa',
+              500: '#14b8a6',
+              600: '#0d9488',
+              900: '#134e4a',
+            }
+          }
+        }
+      }
+    }
+  </script>
+  <style>
+    body { font-family: 'Inter', sans-serif; }
+    .glass-panel {
+      background: rgba(15, 23, 42, 0.85);
+      backdrop-filter: blur(12px);
+      border: 1px solid rgba(51, 65, 85, 0.5);
+    }
+    .custom-scrollbar::-webkit-scrollbar { width: 6px; height: 6px; }
+    .custom-scrollbar::-webkit-scrollbar-track { background: #0f172a; }
+    .custom-scrollbar::-webkit-scrollbar-thumb { background: #334155; border-radius: 3px; }
+  </style>
+</head>
+<body class="bg-slate-950 text-slate-100 min-h-screen flex flex-col selection:bg-teal-500 selection:text-white">
+
+  <!-- Header Banner -->
+  <header class="border-b border-slate-800 bg-slate-900/80 sticky top-0 z-40 backdrop-blur-md">
+    <div class="max-w-7xl mx-auto px-4 py-3 flex items-center justify-between">
+      <div class="flex items-center space-x-3">
+        <div class="w-10 h-10 rounded-xl bg-gradient-to-tr from-teal-500 to-emerald-400 flex items-center justify-center shadow-lg shadow-teal-500/20">
+          <i class="fa-solid fa-microscope text-slate-950 text-lg"></i>
+        </div>
+        <div>
+          <h1 class="font-bold text-lg text-slate-100 tracking-tight flex items-center gap-2">
+            DeepfakeDet-ViT <span class="text-xs px-2 py-0.5 rounded-full bg-teal-500/10 text-teal-400 font-mono border border-teal-500/20">XAI & Forensics Suite</span>
+          </h1>
+          <p class="text-xs text-slate-400">ViT-Small Deepfake Classifier (384×384) — Attribution & Digital Artifact Analysis</p>
+        </div>
+      </div>
+      <div class="flex items-center space-x-3">
+        <a href="https://huggingface.co/buildborderless/CommunityForensics-DeepfakeDet-ViT" target="_blank" class="text-xs px-3 py-1.5 rounded-lg bg-slate-800 hover:bg-slate-700 text-slate-300 transition flex items-center gap-1.5 border border-slate-700">
+          <i class="fa-brands fa-huggingface"></i> HF Model Hub
+        </a>
+      </div>
+    </div>
+  </header>
+
+  <!-- Navigation Tabs -->
+  <div class="bg-slate-900/50 border-b border-slate-800/80 sticky top-[61px] z-30 backdrop-blur-md">
+    <div class="max-w-7xl mx-auto px-4 flex space-x-2 overflow-x-auto custom-scrollbar">
+      <button onclick="switchTab('quick')" id="tab-quick" class="tab-btn py-3 px-4 text-sm font-medium border-b-2 border-teal-400 text-teal-400 flex items-center gap-2 transition">
+        <i class="fa-solid fa-bolt text-xs"></i> ⚡ Quick Analysis
+      </button>
+      <button onclick="switchTab('explorer')" id="tab-explorer" class="tab-btn py-3 px-4 text-sm font-medium border-b-2 border-transparent text-slate-400 hover:text-slate-200 flex items-center gap-2 transition">
+        <i class="fa-solid fa-sliders text-xs"></i> 🔍 Method Explorer
+      </button>
+      <button onclick="switchTab('heads')" id="tab-heads" class="tab-btn py-3 px-4 text-sm font-medium border-b-2 border-transparent text-slate-400 hover:text-slate-200 flex items-center gap-2 transition">
+        <i class="fa-solid fa-brain text-xs"></i> 🧠 Per-Head Inspector
+      </button>
+      <button onclick="switchTab('forensics')" id="tab-forensics" class="tab-btn py-3 px-4 text-sm font-medium border-b-2 border-transparent text-slate-400 hover:text-slate-200 flex items-center gap-2 transition">
+        <i class="fa-solid fa-user-secret text-xs"></i> 🕵️ Classic Forensics
+      </button>
+      <button onclick="switchTab('guide')" id="tab-guide" class="tab-btn py-3 px-4 text-sm font-medium border-b-2 border-transparent text-slate-400 hover:text-slate-200 flex items-center gap-2 transition">
+        <i class="fa-solid fa-book-open text-xs"></i> 📖 Guide & Reference
+      </button>
+    </div>
+  </div>
+
+  <!-- Main Container -->
+  <main class="max-w-7xl mx-auto px-4 py-6 flex-1 w-full">
+
+    <!-- Global Image Upload Section -->
+    <div class="glass-panel rounded-2xl p-5 mb-6 shadow-xl">
+      <div class="grid grid-cols-1 lg:grid-cols-12 gap-6 items-center">
+        
+        <!-- Left: Upload Box -->
+        <div class="lg:col-span-5">
+          <div id="drop-zone" onclick="document.getElementById('file-input').click()" class="border-2 border-dashed border-slate-700 hover:border-teal-500/60 bg-slate-900/60 hover:bg-slate-900 transition rounded-xl p-6 text-center cursor-pointer relative group">
+            <input type="file" id="file-input" accept="image/*" class="hidden" onchange="handleFileSelect(event)" />
+            
+            <div id="upload-prompt" class="py-2">
+              <i class="fa-solid fa-cloud-arrow-up text-3xl text-teal-400/80 group-hover:scale-110 transition mb-2"></i>
+              <p class="text-sm font-medium text-slate-200">Drag & Drop Image or <span class="text-teal-400 underline">Browse</span></p>
+              <p class="text-xs text-slate-500 mt-1">Supports JPG, PNG, WEBP (Auto-cropped to 384×384)</p>
+            </div>
+            
+            <div id="preview-container" class="hidden relative inline-block">
+              <img id="image-preview" src="" alt="Input Preview" class="max-h-48 rounded-lg shadow-lg border border-slate-700 object-contain mx-auto" />
+              <button onclick="event.stopPropagation(); clearImage()" class="absolute -top-2 -right-2 bg-rose-500 text-white w-6 h-6 rounded-full text-xs flex items-center justify-center hover:bg-rose-600 shadow">
+                <i class="fa-solid fa-xmark"></i>
+              </button>
+            </div>
+          </div>
+        </div>
+
+        <!-- Right: Control Panel & Status -->
+        <div class="lg:col-span-7 flex flex-col justify-between h-full space-y-4">
+          <div class="flex items-center justify-between border-b border-slate-800 pb-3">
+            <div>
+              <span class="text-xs font-mono text-slate-400 uppercase tracking-wider">Analysis Status</span>
+              <div id="prediction-badge" class="mt-1 text-sm font-bold text-slate-500 flex items-center gap-2">
+                <span class="w-2.5 h-2.5 rounded-full bg-slate-600"></span> Awaiting Input Image
+              </div>
+            </div>
+            <div id="confidence-box" class="hidden text-right">
+              <span class="text-xs text-slate-400">Confidence Score</span>
+              <p id="confidence-val" class="font-mono text-lg font-bold text-teal-400">0.00%</p>
+            </div>
+          </div>
+
+          <!-- Buttons -->
+          <div class="flex flex-wrap items-center gap-3">
+            <button id="btn-analyze" onclick="runAnalysis()" class="flex-1 bg-gradient-to-r from-teal-500 to-emerald-500 hover:from-teal-400 hover:to-emerald-400 text-slate-950 font-bold px-6 py-3 rounded-xl shadow-lg shadow-teal-500/20 transition flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed">
+              <i class="fa-solid fa-bolt"></i> Run Full XAI Suite
+            </button>
+            <button id="btn-report" onclick="downloadReport()" disabled class="bg-slate-800 hover:bg-slate-700 text-slate-200 font-semibold px-4 py-3 rounded-xl border border-slate-700 transition flex items-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed">
+              <i class="fa-solid fa-file-arrow-down"></i> Report PNG
+            </button>
+          </div>
+        </div>
+
+      </div>
+    </div>
+
+    <!-- Loading Bar / Spinner -->
+    <div id="loading-spinner" class="hidden glass-panel rounded-2xl p-6 mb-6 text-center">
+      <div class="inline-block animate-spin w-8 h-8 border-4 border-teal-500 border-t-transparent rounded-full mb-3"></div>
+      <p id="loading-text" class="text-sm font-medium text-slate-300">Computing 6 ViT Attribution Maps on CPU...</p>
+    </div>
+
+    <!-- TAB 1: ⚡ Quick Analysis -->
+    <div id="section-quick" class="tab-section">
+      <div class="glass-panel rounded-2xl p-6 shadow-xl mb-6">
+        <h2 class="text-base font-bold text-slate-100 mb-4 flex items-center justify-between">
+          <span><i class="fa-solid fa-layer-group text-teal-400 mr-2"></i> ViT Attribution Overlays</span>
+          <span class="text-xs font-normal text-slate-400">Click any map to inspect in fullscreen modal</span>
+        </h2>
+
+        <!-- Grid of 6 attribution overlays -->
+        <div id="results-grid" class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+          <!-- Placeholder cards -->
+          <div class="bg-slate-900/40 border border-slate-800/80 rounded-xl p-4 text-center py-12 text-slate-600">
+            <i class="fa-regular fa-image text-3xl mb-2"></i>
+            <p class="text-xs">Attention Rollout</p>
+          </div>
+          <div class="bg-slate-900/40 border border-slate-800/80 rounded-xl p-4 text-center py-12 text-slate-600">
+            <i class="fa-regular fa-image text-3xl mb-2"></i>
+            <p class="text-xs">Chefer Gradient-Rollout</p>
+          </div>
+          <div class="bg-slate-900/40 border border-slate-800/80 rounded-xl p-4 text-center py-12 text-slate-600">
+            <i class="fa-regular fa-image text-3xl mb-2"></i>
+            <p class="text-xs">GradCAM</p>
+          </div>
+          <div class="bg-slate-900/40 border border-slate-800/80 rounded-xl p-4 text-center py-12 text-slate-600">
+            <i class="fa-regular fa-image text-3xl mb-2"></i>
+            <p class="text-xs">Integrated Gradients</p>
+          </div>
+          <div class="bg-slate-900/40 border border-slate-800/80 rounded-xl p-4 text-center py-12 text-slate-600">
+            <i class="fa-regular fa-image text-3xl mb-2"></i>
+            <p class="text-xs">DeepLIFT</p>
+          </div>
+          <div class="bg-slate-900/40 border border-slate-800/80 rounded-xl p-4 text-center py-12 text-slate-600">
+            <i class="fa-regular fa-image text-3xl mb-2"></i>
+            <p class="text-xs">Occlusion Sensitivity</p>
+          </div>
+        </div>
+      </div>
+
+      <!-- Dataset Feedback Submission Panel -->
+      <div id="submit-panel" class="hidden glass-panel rounded-2xl p-6 shadow-xl border border-teal-500/20">
+        <h3 class="text-sm font-bold text-slate-200 mb-2 flex items-center gap-2">
+          <i class="fa-solid fa-database text-teal-400"></i> Contribute Ground Truth to Research Dataset
+        </h3>
+        <p class="text-xs text-slate-400 mb-4">
+          Help improve future forensic models by verifying prediction correctness. Your feedback and the composite XAI heatmaps will be uploaded to <code class="text-teal-400 bg-slate-900 px-1.5 py-0.5 rounded">buildborderless/deepfake-explainability</code>.
+        </p>
+
+        <div class="flex flex-wrap items-center gap-6">
+          <div>
+            <span class="text-xs text-slate-400 block mb-1">Ground Truth Label:</span>
+            <div class="flex items-center space-x-3">
+              <label class="inline-flex items-center text-xs text-slate-300 cursor-pointer">
+                <input type="radio" name="ground_truth" value="real" class="form-radio text-teal-500 bg-slate-900 border-slate-700" />
+                <span class="ml-1.5">Real Image</span>
+              </label>
+              <label class="inline-flex items-center text-xs text-slate-300 cursor-pointer">
+                <input type="radio" name="ground_truth" value="fake" class="form-radio text-rose-500 bg-slate-900 border-slate-700" />
+                <span class="ml-1.5">Deepfake</span>
+              </label>
+              <label class="inline-flex items-center text-xs text-slate-300 cursor-pointer">
+                <input type="radio" name="ground_truth" value="unknown" checked class="form-radio text-slate-500 bg-slate-900 border-slate-700" />
+                <span class="ml-1.5">Unsure / Unknown</span>
+              </label>
+            </div>
+          </div>
+
+          <label class="inline-flex items-center text-xs text-slate-300 cursor-pointer">
+            <input type="checkbox" id="opt-in-image" checked class="form-checkbox text-teal-500 bg-slate-900 border-slate-700 rounded" />
+            <span class="ml-2">Include raw image in dataset</span>
+          </label>
+
+          <button onclick="submitDatasetRun()" class="bg-teal-600 hover:bg-teal-500 text-slate-950 font-bold text-xs px-4 py-2 rounded-lg transition ml-auto flex items-center gap-1.5">
+            <i class="fa-solid fa-paper-plane"></i> Submit Entry
+          </button>
+        </div>
+        <p id="submit-status" class="text-xs font-mono text-teal-400 mt-2 hidden"></p>
+      </div>
+    </div>
+
+    <!-- TAB 2: 🔍 Method Explorer -->
+    <div id="section-explorer" class="tab-section hidden">
+      <div class="glass-panel rounded-2xl p-6 shadow-xl mb-6">
+        <h2 class="text-base font-bold text-slate-100 mb-4 flex items-center gap-2">
+          <i class="fa-solid fa-sliders text-teal-400"></i> Interactive Method Parameter Explorer
+        </h2>
+
+        <div class="grid grid-cols-1 lg:grid-cols-12 gap-6">
+          <!-- Parameter Controls -->
+          <div class="lg:col-span-4 space-y-4 bg-slate-900/60 p-4 rounded-xl border border-slate-800">
+            <div>
+              <label class="text-xs font-medium text-slate-300 block mb-1">Select XAI Method</label>
+              <select id="exp-method" onchange="runExplorerMethod()" class="w-full bg-slate-950 border border-slate-700 rounded-lg px-3 py-2 text-xs text-slate-200 focus:outline-none focus:border-teal-500">
+                <option value="rollout">Attention Rollout</option>
+                <option value="chefer">Gradient-Weighted Rollout (Chefer)</option>
+                <option value="gradcam">GradCAM</option>
+                <option value="integrated">Integrated Gradients</option>
+                <option value="deeplift">DeepLIFT</option>
+                <option value="occlusion">Occlusion Sensitivity</option>
+              </select>
+            </div>
+
+            <div>
+              <label class="text-xs font-medium text-slate-300 block mb-1">Colormap</label>
+              <select id="exp-cmap" onchange="runExplorerMethod()" class="w-full bg-slate-950 border border-slate-700 rounded-lg px-3 py-2 text-xs text-slate-200">
+                <option value="jet">Jet (Standard Forensic)</option>
+                <option value="inferno">Inferno (High Contrast)</option>
+                <option value="viridis">Viridis (Perceptual)</option>
+                <option value="hot">Hot (Thermal)</option>
+              </select>
+            </div>
+
+            <div>
+              <label class="text-xs font-medium text-slate-300 block mb-1">Overlay Transparency (Alpha: <span id="val-alpha">0.6</span>)</label>
+              <input type="range" id="exp-alpha" min="0.1" max="1.0" step="0.05" value="0.6" oninput="document.getElementById('val-alpha').innerText=this.value; runExplorerMethod()" class="w-full text-teal-500" />
+            </div>
+
+            <!-- Conditional Controls -->
+            <div id="ctrl-integrated" class="space-y-3 pt-2 border-t border-slate-800">
+              <label class="text-xs font-medium text-slate-300 block mb-1">IG Steps: <span id="val-steps">20</span></label>
+              <input type="range" id="exp-steps" min="10" max="60" step="5" value="20" oninput="document.getElementById('val-steps').innerText=this.value; runExplorerMethod()" class="w-full" />
+            </div>
+
+            <div id="ctrl-occlusion" class="space-y-3 pt-2 border-t border-slate-800">
+              <label class="text-xs font-medium text-slate-300 block mb-1">Patch Size: <span id="val-patch">32</span> px</label>
+              <input type="range" id="exp-patch" min="16" max="64" step="8" value="32" oninput="document.getElementById('val-patch').innerText=this.value; runExplorerMethod()" class="w-full" />
+            </div>
+
+            <div id="ctrl-gradcam" class="space-y-3 pt-2 border-t border-slate-800">
+              <label class="text-xs font-medium text-slate-300 block mb-1">Target Transformer Layer: <span id="val-layer">12</span></label>
+              <input type="range" id="exp-layer" min="1" max="12" step="1" value="12" oninput="document.getElementById('val-layer').innerText=this.value; runExplorerMethod()" class="w-full" />
+            </div>
+          </div>
+
+          <!-- Display Box -->
+          <div class="lg:col-span-8 grid grid-cols-1 sm:grid-cols-2 gap-4">
+            <div class="bg-slate-900/60 p-4 rounded-xl border border-slate-800 text-center">
+              <span class="text-xs text-slate-400 block mb-2 font-mono">Saliency Overlay</span>
+              <img id="exp-img-overlay" src="" class="max-h-72 rounded-lg mx-auto shadow border border-slate-700 object-contain" />
+            </div>
+            <div class="bg-slate-900/60 p-4 rounded-xl border border-slate-800 text-center">
+              <span class="text-xs text-slate-400 block mb-2 font-mono">Raw Heatmap</span>
+              <img id="exp-img-raw" src="" class="max-h-72 rounded-lg mx-auto shadow border border-slate-700 object-contain" />
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- TAB 3: 🧠 Per-Head Inspector -->
+    <div id="section-heads" class="tab-section hidden">
+      <div class="glass-panel rounded-2xl p-6 shadow-xl mb-6">
+        <div class="flex items-center justify-between mb-4">
+          <h2 class="text-base font-bold text-slate-100 flex items-center gap-2">
+            <i class="fa-solid fa-brain text-teal-400"></i> Attention Head Disaggregation (6 Heads per Layer)
+          </h2>
+          <div class="flex items-center space-x-3">
+            <span class="text-xs text-slate-400">Layer: <strong id="head-layer-val" class="text-teal-400">12</strong> / 12</span>
+            <input type="range" id="head-layer-input" min="1" max="12" value="12" onchange="runPerHeadInspector()" class="w-32" />
+          </div>
+        </div>
+
+        <div id="heads-grid" class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-3">
+          <!-- Placeholder cards -->
+          <div class="bg-slate-900/60 border border-slate-800 rounded-xl p-3 text-center py-8 text-slate-600 text-xs">Head 1</div>
+          <div class="bg-slate-900/60 border border-slate-800 rounded-xl p-3 text-center py-8 text-slate-600 text-xs">Head 2</div>
+          <div class="bg-slate-900/60 border border-slate-800 rounded-xl p-3 text-center py-8 text-slate-600 text-xs">Head 3</div>
+          <div class="bg-slate-900/60 border border-slate-800 rounded-xl p-3 text-center py-8 text-slate-600 text-xs">Head 4</div>
+          <div class="bg-slate-900/60 border border-slate-800 rounded-xl p-3 text-center py-8 text-slate-600 text-xs">Head 5</div>
+          <div class="bg-slate-900/60 border border-slate-800 rounded-xl p-3 text-center py-8 text-slate-600 text-xs">Head 6</div>
+        </div>
+      </div>
+    </div>
+
+    <!-- TAB 4: 🕵️ Classic Forensics -->
+    <div id="section-forensics" class="tab-section hidden">
+      <div class="glass-panel rounded-2xl p-6 shadow-xl mb-6">
+        <h2 class="text-base font-bold text-slate-100 mb-4 flex items-center gap-2">
+          <i class="fa-solid fa-user-secret text-teal-400"></i> Classic Digital Image Forensics Suite
+        </h2>
+
+        <div class="grid grid-cols-1 lg:grid-cols-12 gap-6">
+          <!-- Controls -->
+          <div class="lg:col-span-4 space-y-4 bg-slate-900/60 p-4 rounded-xl border border-slate-800">
+            <div>
+              <label class="text-xs font-medium text-slate-300 block mb-1">Forensic Analysis Tool</label>
+              <select id="for-tool" onchange="runForensicAnalysis()" class="w-full bg-slate-950 border border-slate-700 rounded-lg px-3 py-2 text-xs text-slate-200">
+                <option value="ela">Error Level Analysis (ELA)</option>
+                <option value="gradient">Spatial Edge Gradient</option>
+                <option value="bitplane">Bit Plane Extractor</option>
+                <option value="minmax">MinMax Local Deviation</option>
+                <option value="wavelet">Wavelet Noise Estimator</option>
+              </select>
+            </div>
+
+            <!-- ELA Options -->
+            <div id="ctrl-ela" class="space-y-3 pt-2 border-t border-slate-800">
+              <label class="text-xs font-medium text-slate-300 block mb-1">JPEG Quality: <span id="val-quality">75</span>%</label>
+              <input type="range" id="for-quality" min="30" max="95" value="75" oninput="document.getElementById('val-quality').innerText=this.value; runForensicAnalysis()" class="w-full" />
+            </div>
+
+            <!-- Bitplane Options -->
+            <div id="ctrl-bitplane" class="hidden space-y-3 pt-2 border-t border-slate-800">
+              <label class="text-xs font-medium text-slate-300 block mb-1">Bit Index (0=LSB, 7=MSB)</label>
+              <input type="range" id="for-bit" min="0" max="7" value="0" oninput="runForensicAnalysis()" class="w-full" />
+            </div>
+
+            <p id="for-info" class="text-xs font-mono text-teal-400/90 pt-2"></p>
+          </div>
+
+          <!-- Display Box -->
+          <div class="lg:col-span-8 bg-slate-900/60 p-4 rounded-xl border border-slate-800 text-center flex flex-col justify-center items-center min-h-[300px]">
+            <img id="for-img-output" src="" class="max-h-96 rounded-lg shadow border border-slate-700 object-contain hidden" />
+            <p id="for-placeholder" class="text-xs text-slate-500">Upload an image and run analysis</p>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- TAB 5: 📖 Guide & Reference -->
+    <div id="section-guide" class="tab-section hidden">
+      <div class="glass-panel rounded-2xl p-6 shadow-xl space-y-6">
+        <div>
+          <h2 class="text-lg font-bold text-slate-100 mb-2">Model & XAI Documentation</h2>
+          <p class="text-xs text-slate-400">
+            Model: <code class="text-teal-400 font-mono">buildborderless/CommunityForensics-DeepfakeDet-ViT</code> — trained on 2.7M samples across 4,803 generators.
+          </p>
+        </div>
+
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-4 text-xs text-slate-300">
+          <div class="bg-slate-900/60 p-4 rounded-xl border border-slate-800 space-y-2">
+            <h3 class="font-bold text-teal-400">Attention Rollout vs. Chefer Rollout</h3>
+            <p class="text-slate-400">Attention Rollout averages attention maps across all heads and multiplies them layer-by-layer. Chefer et al. (CVPR 2021) improves this by multiplying attention weights by their backward gradients <code class="text-teal-400">∇A × A</code>, making the attribution class-discriminative (specifically showing what pushed towards FAKE).</p>
+          </div>
+          <div class="bg-slate-900/60 p-4 rounded-xl border border-slate-800 space-y-2">
+            <h3 class="font-bold text-teal-400">Integrated Gradients & DeepLIFT</h3>
+            <p class="text-slate-400">Integrated Gradients integrates pixel gradients along a linear path from a black baseline. DeepLIFT decomposes non-linear neural activations relative to baseline to reveal positive vs. negative feature contributions.</p>
+          </div>
+        </div>
+      </div>
+    </div>
+
+  </main>
+
+  <!-- Fullscreen Modal Viewer -->
+  <div id="modal-viewer" class="hidden fixed inset-0 z-50 bg-slate-950/90 backdrop-blur-md flex items-center justify-center p-4" onclick="closeModal()">
+    <div class="relative max-w-4xl w-full bg-slate-900 border border-slate-700 rounded-2xl overflow-hidden p-4 shadow-2xl" onclick="event.stopPropagation()">
+      <div class="flex items-center justify-between mb-3 border-b border-slate-800 pb-2">
+        <h3 id="modal-title" class="text-sm font-bold text-slate-200">Attribution Overlay</h3>
+        <button onclick="closeModal()" class="text-slate-400 hover:text-slate-100 text-lg">
+          <i class="fa-solid fa-xmark"></i>
+        </button>
+      </div>
+      <img id="modal-img" src="" class="max-h-[75vh] mx-auto rounded-lg object-contain" />
+    </div>
+  </div>
+
+  <!-- JavaScript App Logic -->
+  <script>
+    let currentImageB64 = null;
+
+    function switchTab(tabId) {
+      document.querySelectorAll('.tab-btn').forEach(btn => {
+        btn.classList.remove('border-teal-400', 'text-teal-400');
+        btn.classList.add('border-transparent', 'text-slate-400');
+      });
+      document.querySelectorAll('.tab-section').forEach(sec => sec.classList.add('hidden'));
+
+      document.getElementById('tab-' + tabId).classList.add('border-teal-400', 'text-teal-400');
+      document.getElementById('tab-' + tabId).classList.remove('border-transparent', 'text-slate-400');
+      document.getElementById('section-' + tabId).classList.remove('hidden');
+    }
+
+    function handleFileSelect(evt) {
+      const file = evt.target.files[0];
+      if (!file) return;
+      const reader = new FileReader();
+      reader.onload = function(e) {
+        currentImageB64 = e.target.result;
+        document.getElementById('image-preview').src = currentImageB64;
+        document.getElementById('upload-prompt').classList.add('hidden');
+        document.getElementById('preview-container').classList.remove('hidden');
+        document.getElementById('btn-analyze').disabled = false;
+      };
+      reader.readAsDataURL(file);
+    }
+
+    function clearImage() {
+      currentImageB64 = null;
+      document.getElementById('file-input').value = '';
+      document.getElementById('upload-prompt').classList.remove('hidden');
+      document.getElementById('preview-container').classList.add('hidden');
+      document.getElementById('btn-analyze').disabled = true;
+      document.getElementById('btn-report').disabled = true;
+    }
+
+    async function apiCall(endpoint, payload) {
+      const resp = await fetch('/gradio_api/' + endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ data: [payload] })
+      });
+      const data = await resp.json();
+      return data.data ? data.data[0] : data;
+    }
+
+    async function runAnalysis() {
+      if (!currentImageB64) return;
+
+      document.getElementById('loading-spinner').classList.remove('hidden');
+      document.getElementById('btn-analyze').disabled = true;
+
+      try {
+        const resp = await fetch('/api/predict_all', { method: 'POST' }); // Fallback direct fetch
+        const res = await apiCall('analyze', currentImageB64);
+        
+        if (res.status === 'success') {
+          // Update Prediction Badge
+          const pred = res.prediction;
+          const isFake = pred.prediction === 'FAKE';
+          const badge = document.getElementById('prediction-badge');
+          badge.className = `mt-1 text-sm font-bold flex items-center gap-2 ${isFake ? 'text-rose-400' : 'text-emerald-400'}`;
+          badge.innerHTML = `<span class="w-2.5 h-2.5 rounded-full ${isFake ? 'bg-rose-500' : 'bg-emerald-500'}"></span> VERDICT: ${pred.prediction}`;
+
+          document.getElementById('confidence-val').innerText = pred.confidence_pct.toFixed(2) + '%';
+          document.getElementById('confidence-box').classList.remove('hidden');
+
+          // Render Grid
+          const grid = document.getElementById('results-grid');
+          grid.innerHTML = '';
+          res.results.forEach(r => {
+            const card = document.createElement('div');
+            card.className = 'glass-panel rounded-xl p-3 hover:border-teal-500/50 transition cursor-pointer group';
+            card.onclick = () => openModal(r.name, r.overlay_b64);
+            card.innerHTML = `
+              <div class="relative overflow-hidden rounded-lg mb-2">
+                <img src="${r.overlay_b64}" class="w-full h-44 object-cover group-hover:scale-105 transition duration-300" />
+                <span class="absolute bottom-2 right-2 bg-slate-950/80 text-teal-400 text-[10px] font-mono px-2 py-0.5 rounded border border-slate-700">${r.compute_time_ms} ms</span>
+              </div>
+              <h4 class="text-xs font-bold text-slate-200">${r.name}</h4>
+              <p class="text-[10px] text-slate-400 line-clamp-1">${r.description}</p>
+            `;
+            grid.appendChild(card);
+          });
+
+          document.getElementById('submit-panel').classList.remove('hidden');
+          document.getElementById('btn-report').disabled = false;
+        }
+      } catch (err) {
+        console.error(err);
+      } finally {
+        document.getElementById('loading-spinner').classList.add('hidden');
+        document.getElementById('btn-analyze').disabled = false;
+      }
+    }
+
+    async function submitDatasetRun() {
+      if (!currentImageB64) return;
+      const gt = document.querySelector('input[name="ground_truth"]:checked').value;
+      const optIn = document.getElementById('opt-in-image').checked;
+
+      const res = await apiCall('submit_run', currentImageB64);
+      const statusP = document.getElementById('submit-status');
+      statusP.innerText = `Run ${res.run_id} logged to dataset buildborderless/deepfake-explainability!`;
+      statusP.classList.remove('hidden');
+    }
+
+    function openModal(title, b64) {
+      document.getElementById('modal-title').innerText = title;
+      document.getElementById('modal-img').src = b64;
+      document.getElementById('modal-viewer').classList.remove('hidden');
+    }
+
+    function closeModal() {
+      document.getElementById('modal-viewer').classList.add('hidden');
+    }
+  </script>
+</body>
+</html>

logger.py

@@ -0,0 +1,140 @@
+import os
+import json
+import uuid
+import time
+import threading
+from datetime import datetime
+from PIL import Image, ImageDraw, ImageFont
+from huggingface_hub import HfApi, get_token
+
+DATASET_REPO = "buildborderless/deepfake-explainability"
+LOCAL_LOG_DIR = os.path.join(os.path.dirname(__file__), "logs")
+
+
+def create_composite_xai_grid(image: Image.Image, results: list) -> Image.Image:
+    """Combine original image and all XAI heatmap overlays into a single composite image grid."""
+    w, h = 384, 384
+    n = len(results) + 1  # Original + N methods
+    cols = min(n, 4)
+    rows = (n + cols - 1) // cols
+
+    grid_img = Image.new("RGB", (cols * w, rows * h), color=(15, 23, 42))
+
+    # Paste original
+    orig_resized = image.convert("RGB").resize((w, h))
+    grid_img.paste(orig_resized, (0, 0))
+
+    # Paste XAI overlays
+    for idx, res in enumerate(results, start=1):
+        r = idx // cols
+        c = idx % cols
+        if hasattr(res, "overlay_b64"):
+            import base64
+            from io import BytesIO
+            b64_data = res.overlay_b64.split(",")[-1]
+            overlay_pil = Image.open(BytesIO(base64.b64decode(b64_data))).resize((w, h))
+            grid_img.paste(overlay_pil, (c * w, r * h))
+
+    return grid_img
+
+
+def _async_push_to_dataset(record: dict, image: Image.Image, composite_grid: Image.Image):
+    """Background worker function for dataset logging."""
+    os.makedirs(LOCAL_LOG_DIR, exist_ok=True)
+    log_file = os.path.join(LOCAL_LOG_DIR, "runs.jsonl")
+
+    # 1. Always append record to local JSONL
+    try:
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record) + "\n")
+    except Exception as e:
+        print(f"[logger] Local log write failed: {e}")
+
+    # 2. Save images locally
+    run_id = record["run_id"]
+    if image is not None:
+        img_path = os.path.join(LOCAL_LOG_DIR, f"{run_id}_input.png")
+        image.save(img_path)
+
+    grid_path = os.path.join(LOCAL_LOG_DIR, f"{run_id}_xai_composite.png")
+    composite_grid.save(grid_path)
+
+    # 3. Attempt Hub dataset push if token present
+    token = get_token() or os.environ.get("HF_TOKEN")
+    if token:
+        try:
+            api = HfApi(token=token)
+            # Upload local log files to dataset repo
+            api.upload_file(
+                path_or_fileobj=grid_path,
+                path_in_repo=f"grids/{run_id}_xai_composite.png",
+                repo_id=DATASET_REPO,
+                repo_type="dataset",
+            )
+            if image is not None:
+                api.upload_file(
+                    path_or_fileobj=img_path,
+                    path_in_repo=f"images/{run_id}_input.png",
+                    repo_id=DATASET_REPO,
+                    repo_type="dataset",
+                )
+            api.upload_file(
+                path_or_fileobj=log_file,
+                path_in_repo="runs.jsonl",
+                repo_id=DATASET_REPO,
+                repo_type="dataset",
+            )
+            print(f"[logger] Successfully pushed run {run_id} to dataset {DATASET_REPO}")
+        except Exception as e:
+            print(f"[logger] Hub push error (fallback to local): {e}")
+
+
+def log_run_dataset(
+    image: Image.Image,
+    pred_data: dict,
+    results: list,
+    ground_truth: str = "unknown",
+    opt_in_image: bool = True,
+) -> str:
+    """
+    Log run details, prediction, ground truth, and XAI composite heatmaps.
+    
+    Returns run_id.
+    """
+    run_id = str(uuid.uuid4())[:8]
+    now_str = datetime.utcnow().isoformat()
+
+    is_correct = None
+    if ground_truth in ("real", "fake"):
+        pred_clean = pred_data.get("prediction", "").lower()
+        is_correct = (pred_clean == ground_truth)
+
+    methods_run = [r.name for r in results]
+    per_method_time = {r.name: r.compute_time_ms for r in results}
+
+    record = {
+        "timestamp": now_str,
+        "run_id": run_id,
+        "prediction": pred_data.get("prediction"),
+        "probability": pred_data.get("probability"),
+        "confidence_pct": pred_data.get("confidence_pct"),
+        "ground_truth": ground_truth,
+        "is_correct": is_correct,
+        "opt_in_image": opt_in_image,
+        "methods_run": methods_run,
+        "per_method_time_ms": per_method_time,
+        "total_time_ms": sum(per_method_time.values()),
+    }
+
+    composite_grid = create_composite_xai_grid(image, results)
+    logged_image = image if opt_in_image else None
+
+    # Spawn background thread to avoid blocking UI response
+    thread = threading.Thread(
+        target=_async_push_to_dataset,
+        args=(record, logged_image, composite_grid),
+        daemon=True
+    )
+    thread.start()
+
+    return run_id

report.py

@@ -0,0 +1,96 @@
+import os
+import tempfile
+import numpy as np
+from PIL import Image
+import matplotlib.pyplot as plt
+from skimage.transform import resize
+
+
+def generate_forensic_report(
+    image: Image.Image,
+    pred_data: dict,
+    results: list,
+    model_name: str = "buildborderless/CommunityForensics-DeepfakeDet-ViT",
+) -> str:
+    """
+    Generate an aesthetic high-DPI multi-panel PDF/PNG report for the forensic analysis.
+    
+    Returns path to generated PNG file.
+    """
+    plt.style.use('default')
+    
+    orig_w, orig_h = image.size
+    image_resized = image.convert("RGB").resize((384, 384))
+    image_np = np.array(image_resized) / 255.0
+
+    n_methods = len(results)
+    n_cols = min(n_methods + 1, 4)
+    n_rows = ((n_methods + 1) + n_cols - 1) // n_cols
+
+    fig = plt.figure(figsize=(4.2 * n_cols, 4.5 * n_rows), facecolor="#ffffff")
+
+    # Header Title
+    pred_str = pred_data.get("prediction", "N/A")
+    prob = pred_data.get("probability", 0.5)
+    conf_pct = pred_data.get("confidence_pct", 50.0)
+    is_fake = pred_str == "FAKE"
+
+    fig.text(
+        0.04, 0.96, "ViT Deepfake Forensic Analysis Report",
+        fontsize=16, fontweight="bold", color="#0f172a", fontfamily="sans-serif", va="top"
+    )
+    meta_sub = f"Model: {model_name}   │   Resolution: {orig_w}x{orig_h} px   │   Target: {pred_str} (p={prob:.4f})"
+    fig.text(
+        0.04, 0.925, meta_sub,
+        fontsize=9.5, color="#64748b", fontfamily="sans-serif", va="top"
+    )
+
+    # Prediction Badge Top Right
+    badge_bg = "#fee2e2" if is_fake else "#d1fae5"
+    badge_ec = "#ef4444" if is_fake else "#10b981"
+    badge_tc = "#991b1b" if is_fake else "#065f46"
+    badge_text = f"VERDICT: {pred_str}\nConfidence: {conf_pct:.2f}%"
+
+    fig.text(
+        0.96, 0.955, badge_text,
+        fontsize=9.5, fontweight="bold", color=badge_tc, fontfamily="sans-serif",
+        ha="right", va="top", multialignment="right",
+        bbox=dict(
+            boxstyle="round,pad=0.6,rounding_size=0.4",
+            facecolor=badge_bg,
+            edgecolor=badge_ec,
+            linewidth=1.4
+        )
+    )
+
+    gs = fig.add_gridspec(n_rows, n_cols, left=0.04, right=0.96, top=0.88, bottom=0.06, wspace=0.15, hspace=0.35)
+
+    # Plot 0: Original Image
+    ax0 = fig.add_subplot(gs[0, 0])
+    ax0.imshow(image_np)
+    ax0.set_title("Input Image", fontsize=10.5, fontweight="bold", color="#0f172a", pad=6)
+    ax0.axis("off")
+
+    # Plots 1..N: Method Overlays
+    for idx, res in enumerate(results, start=1):
+        r_idx = idx // n_cols
+        c_idx = idx % n_cols
+        ax = fig.add_subplot(gs[r_idx, c_idx])
+
+        # Convert b64 overlay back or use heatmap
+        norm_h = res.heatmap_norm
+        overlay = image_np.copy()
+        heatmap_colored = plt.cm.jet(norm_h)[:, :, :3]
+        overlay = 0.4 * overlay + 0.6 * heatmap_colored
+
+        ax.imshow(overlay)
+        ax.set_title(f"{res.name}\n({res.compute_time_ms:.0f} ms)", fontsize=9.5, fontweight="bold", color="#0f172a", pad=4)
+        ax.axis("off")
+
+    output_dir = tempfile.gettempdir()
+    output_path = os.path.join(output_dir, f"forensic_report_{int(prob * 10000)}.png")
+    
+    plt.savefig(output_path, dpi=200, facecolor=fig.get_facecolor(), edgecolor='none', bbox_inches="tight")
+    plt.close(fig)
+
+    return output_path

requirements.txt

@@ -0,0 +1,11 @@
+torch>=2.0.0
+transformers>=5.4.0
+captum>=0.7.0
+grad-cam>=1.5.0
+Pillow>=10.0.0
+scikit-image>=0.21.0
+opencv-python-headless>=4.8.0
+matplotlib>=3.8.0
+numpy>=1.24.0
+PyWavelets>=1.4.0
+huggingface_hub>=0.25.0

xai_engine/__init__.py

@@ -0,0 +1,13 @@
+from .model import get_model, ViTWrapper
+from .methods import run_all_methods, run_single_method, run_per_head_attention
+from .viz import create_overlay, to_b64_png
+
+__all__ = [
+    "get_model",
+    "ViTWrapper",
+    "run_all_methods",
+    "run_single_method",
+    "run_per_head_attention",
+    "create_overlay",
+    "to_b64_png",
+]

xai_engine/chefer.py

@@ -0,0 +1,116 @@
+"""
+Gradient-weighted Attention Rollout for Vision Transformers (Chefer et al., CVPR 2021).
+Calculates class-discriminative attention maps by weighting attention probabilities with backward gradients.
+"""
+
+import torch
+import numpy as np
+from skimage.transform import resize
+
+
+class ViTCheferRollout:
+    def __init__(self, model):
+        self.model = model
+        self.attentions = []
+        self.attention_gradients = []
+        self.hooks = []
+
+    def _register_hooks(self):
+        self._remove_hooks()
+        self.attentions = []
+        self.attention_gradients = []
+
+        for name, module in self.model.named_modules():
+            if "attention.attention" in name and not hasattr(module, "_chefer_hooked"):
+                def get_attn_hook(module, input, output):
+                    # output in HF ViT self-attention is (context_layer, attn_probs)
+                    if isinstance(output, tuple) and len(output) > 1:
+                        self.attentions.append(output[1])
+                    elif hasattr(output, "attentions"):
+                        self.attentions.append(output.attentions)
+
+                def get_attn_grad_hook(module, grad_input, grad_output):
+                    # grad_output[1] is gradient w.r.t attention probabilities
+                    if len(grad_output) > 1 and grad_output[1] is not None:
+                        self.attention_gradients.append(grad_output[1])
+
+                h1 = module.register_forward_hook(get_attn_hook)
+                h2 = module.register_full_backward_hook(get_attn_grad_hook)
+                self.hooks.extend([h1, h2])
+
+    def _remove_hooks(self):
+        for h in self.hooks:
+            h.remove()
+        self.hooks = []
+
+    def attribute(self, input_tensor, target_class=0):
+        """
+        Compute Chefer Gradient-Weighted Attention Rollout.
+        
+        Args:
+            input_tensor: (1, 3, 384, 384) preprocessed input tensor
+            target_class: output index (0 for single binary logit)
+            
+        Returns:
+            24x24 numpy array of patch attributions
+        """
+        self.model.eval()
+        self._register_hooks()
+        device = input_tensor.device
+
+        # Enable gradients for backward pass
+        input_tensor.requires_grad_(True)
+        self.model.zero_grad()
+
+        # Forward pass with output_attentions=True
+        outputs = self.model(input_tensor, output_attentions=True)
+        logits = outputs.logits  # (1, 1)
+
+        # Backward pass on logit
+        if logits.dim() > 1 and logits.size(1) > target_class:
+            score = logits[:, target_class]
+        else:
+            score = logits.squeeze()
+
+        score.backward()
+
+        attentions = outputs.attentions  # Tuple of 12 (B, heads, 577, 577) tensors
+        
+        # Cleanup hooks
+        self._remove_hooks()
+
+        if not attentions:
+            # Fallback if hooks failed to catch: return flat matrix
+            return np.zeros((24, 24))
+
+        seq_len = attentions[0].size(-1)  # 577
+        result = torch.eye(seq_len, device=device)
+
+        # Reverse gradient order because backward hook captures in reverse
+        gradients = self.attention_gradients[::-1] if self.attention_gradients else [None] * len(attentions)
+
+        for i, attn in enumerate(attentions):
+            # attn: (1, heads, 577, 577)
+            if i < len(gradients) and gradients[i] is not None:
+                grad = gradients[i]
+                # Elementwise product: gradient * attention
+                cam = (grad * attn).clamp(min=0).mean(dim=1)  # (1, 577, 577)
+            else:
+                # Fallback to plain attention if gradient missing
+                cam = attn.mean(dim=1)
+
+            cam = cam[0]  # (577, 577)
+            cam = cam + torch.eye(seq_len, device=device)
+            cam = cam / cam.sum(dim=-1, keepdim=True)
+
+            result = torch.matmul(cam, result)
+
+        # Extract CLS token -> patch tokens
+        patch_attn = result[0, 1:].reshape(24, 24).detach().cpu().numpy()
+        return patch_attn
+
+
+def chefer_gradient_rollout(wrapper, input_tensor) -> np.ndarray:
+    """Convenience function for running Chefer rollout on ViTWrapper."""
+    explainer = ViTCheferRollout(wrapper.model)
+    return explainer.attribute(input_tensor, target_class=0)

xai_engine/methods.py

@@ -0,0 +1,241 @@
+import time
+from dataclasses import dataclass
+import numpy as np
+import torch
+from PIL import Image
+from skimage.transform import resize
+from captum.attr import IntegratedGradients, Occlusion, DeepLift
+from pytorch_grad_cam import GradCAM
+from pytorch_grad_cam.utils.model_targets import BinaryClassifierOutputTarget
+
+from .chefer import chefer_gradient_rollout
+from .viz import create_overlay, render_heatmap_raw, to_b64_png, normalize_heatmap
+
+
+@dataclass
+class AttributionResult:
+    name: str
+    description: str
+    heatmap: np.ndarray          # 2D or 3D numpy array
+    heatmap_norm: np.ndarray     # Normalized [0, 1] 2D heatmap (384, 384)
+    overlay_b64: str             # Base64 PNG data URL
+    raw_heatmap_b64: str         # Base64 PNG data URL
+    metadata: dict
+    compute_time_ms: float
+
+
+def attention_rollout(wrapper, input_tensor) -> np.ndarray:
+    """Attention Rollout for ViT across 12 transformer layers."""
+    model = wrapper.model
+    model.eval()
+
+    with torch.no_grad():
+        outputs = model(input_tensor, output_attentions=True)
+        attentions = outputs.attentions
+
+    device = attentions[0].device
+    seq_len = attentions[0].size(-1)  # 577
+    result = torch.eye(seq_len, device=device)
+
+    for attn in attentions:
+        attn_heads = attn.mean(dim=1)  # Average over 6 heads -> (B, 577, 577)
+        attn_heads = attn_heads + torch.eye(attn_heads.size(-1), device=attn_heads.device)
+        attn_heads = attn_heads / attn_heads.sum(dim=-1, keepdim=True)
+        result = torch.matmul(attn_heads[0], result)
+
+    patch_attention = result[0, 1:].reshape(24, 24).cpu().numpy()
+    return patch_attention
+
+
+def integrated_gradients(wrapper, input_tensor, steps=20) -> tuple[np.ndarray, float]:
+    """Integrated Gradients using Captum with memory-safe mini-batching."""
+    ig = IntegratedGradients(wrapper)
+    baseline = torch.zeros_like(input_tensor)
+
+    attributions, delta = ig.attribute(
+        input_tensor,
+        baselines=baseline,
+        target=0,
+        n_steps=steps,
+        internal_batch_size=2,  # Prevents memory spike on CPU/RAM
+        return_convergence_delta=True
+    )
+    heatmap = attributions[0].sum(dim=0).detach().cpu().numpy()
+    delta_val = float(delta[0].item()) if hasattr(delta, "__getitem__") else float(delta.item())
+    return heatmap, delta_val
+
+
+def vit_grad_cam(wrapper, input_tensor, target_layer_idx=11) -> np.ndarray:
+    """GradCAM for ViT using pytorch_grad_cam with custom reshape transform."""
+    # Target layer: last encoder layer output
+    target_layer = [wrapper.model.vit.encoder.layer[target_layer_idx].output]
+
+    def reshape_transform(tensor):
+        # tensor shape: (B, 577, 384) -> drop CLS token -> (B, 576, 384) -> (B, 24, 24, 384) -> (B, 384, 24, 24)
+        result = tensor[:, 1:, :].reshape(tensor.size(0), 24, 24, tensor.size(2))
+        result = result.permute(0, 3, 1, 2)
+        return result
+
+    cam = GradCAM(
+        model=wrapper,
+        target_layers=target_layer,
+        reshape_transform=reshape_transform,
+    )
+    targets = [BinaryClassifierOutputTarget(0)]
+    grayscale_cam = cam(input_tensor=input_tensor, targets=targets)
+    return grayscale_cam[0]  # (24, 24) or (384, 384)
+
+
+def occlusion_sensitivity(wrapper, input_tensor, patch_size=32, stride=16) -> np.ndarray:
+    """Occlusion Sensitivity attribution using Captum with memory-safe mini-batching."""
+    occ = Occlusion(wrapper)
+    attributions = occ.attribute(
+        input_tensor,
+        target=0,
+        strides=(3, stride, stride),
+        sliding_window_shapes=(3, patch_size, patch_size),
+        baselines=0.0,
+        perturbations_per_eval=4,  # Limits memory allocation per evaluation batch
+    )
+    heatmap = attributions[0].sum(dim=0).detach().cpu().numpy()
+    return heatmap
+
+
+def deeplift(wrapper, input_tensor) -> np.ndarray:
+    """DeepLIFT attribution using Captum."""
+    dl = DeepLift(wrapper)
+    baseline = torch.zeros_like(input_tensor)
+    attributions = dl.attribute(input_tensor, baselines=baseline, target=0)
+    heatmap = attributions[0].sum(dim=0).detach().cpu().numpy()
+    return heatmap
+
+
+def run_per_head_attention(wrapper, image: Image.Image, layer_idx: int = 11, cmap: str = "jet") -> dict:
+    """Extract and render attention maps for all 6 heads at a specific layer."""
+    input_tensor = wrapper.preprocess(image)
+    device = next(wrapper.model.parameters()).device
+    input_tensor = input_tensor.to(device)
+
+    with torch.no_grad():
+        outputs = wrapper.model(input_tensor, output_attentions=True)
+        attns = outputs.attentions[layer_idx][0]  # (6, 577, 577)
+
+    head_results = []
+    for h in range(6):
+        head_map = attns[h, 0, 1:].reshape(24, 24).cpu().numpy()
+        overlay = create_overlay(image, head_map, alpha=0.6, cmap=cmap)
+        head_results.append({
+            "head": h + 1,
+            "overlay_b64": to_b64_png(overlay),
+            "raw_b64": to_b64_png(render_heatmap_raw(head_map, cmap=cmap)),
+            "min": round(float(head_map.min()), 4),
+            "max": round(float(head_map.max()), 4),
+        })
+
+    return {
+        "layer": layer_idx + 1,
+        "heads": head_results,
+    }
+
+
+def run_single_method(
+    wrapper,
+    image: Image.Image,
+    method_name: str,
+    alpha: float = 0.6,
+    cmap: str = "jet",
+    steps: int = 20,
+    patch_size: int = 32,
+    stride: int = 16,
+    target_layer_idx: int = 11,
+) -> AttributionResult:
+    """Execute a single specified XAI method."""
+    input_tensor = wrapper.preprocess(image)
+    device = next(wrapper.model.parameters()).device
+    input_tensor = input_tensor.to(device)
+
+    t0 = time.perf_counter()
+    metadata = {}
+
+    if method_name == "rollout":
+        disp_name = "Attention Rollout"
+        desc = "Global multi-layer attention flow across all 12 transformer blocks."
+        heatmap = attention_rollout(wrapper, input_tensor)
+
+    elif method_name == "integrated":
+        disp_name = "Integrated Gradients"
+        desc = "Path-integral gradient attribution relative to a black baseline."
+        heatmap, delta = integrated_gradients(wrapper, input_tensor, steps=steps)
+        metadata["delta"] = delta
+        metadata["steps"] = steps
+
+    elif method_name == "gradcam":
+        disp_name = "GradCAM"
+        desc = f"Gradient-weighted activation map targeting layer {target_layer_idx + 1}."
+        heatmap = vit_grad_cam(wrapper, input_tensor, target_layer_idx=target_layer_idx)
+        metadata["target_layer"] = target_layer_idx + 1
+
+    elif method_name == "chefer":
+        disp_name = "Gradient Attention Rollout (Chefer)"
+        desc = "Gradient-weighted attention rollout combining gradients and self-attention (CVPR 2021)."
+        heatmap = chefer_gradient_rollout(wrapper, input_tensor)
+
+    elif method_name == "occlusion":
+        disp_name = "Occlusion Sensitivity"
+        desc = f"Sliding window perturbation ({patch_size}x{patch_size} patch, stride {stride})."
+        heatmap = occlusion_sensitivity(wrapper, input_tensor, patch_size=patch_size, stride=stride)
+        metadata["patch_size"] = patch_size
+        metadata["stride"] = stride
+
+    elif method_name == "deeplift":
+        disp_name = "DeepLIFT"
+        desc = "Non-linear feature attribution backpropagating differences from baseline."
+        heatmap = deeplift(wrapper, input_tensor)
+
+    else:
+        raise ValueError(f"Unknown XAI method: {method_name}")
+
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+
+    # Resize heatmap to 384x384 if needed
+    if heatmap.shape != (384, 384):
+        heatmap_resized = resize(heatmap, (384, 384), order=1)
+    else:
+        heatmap_resized = heatmap
+
+    norm_h = normalize_heatmap(heatmap_resized)
+    overlay = create_overlay(image, heatmap, alpha=alpha, cmap=cmap)
+    raw_render = render_heatmap_raw(heatmap, cmap=cmap)
+
+    metadata.update({
+        "min": round(float(heatmap.min()), 5),
+        "max": round(float(heatmap.max()), 5),
+        "mean": round(float(heatmap.mean()), 5),
+        "std": round(float(heatmap.std()), 5),
+    })
+
+    return AttributionResult(
+        name=disp_name,
+        description=desc,
+        heatmap=heatmap,
+        heatmap_norm=norm_h,
+        overlay_b64=to_b64_png(overlay),
+        raw_heatmap_b64=to_b64_png(raw_render),
+        metadata=metadata,
+        compute_time_ms=round(elapsed_ms, 1),
+    )
+
+
+def run_all_methods(
+    wrapper,
+    image: Image.Image,
+    alpha: float = 0.6,
+    cmap: str = "jet",
+) -> list[AttributionResult]:
+    """Run all 6 primary spatial attribution methods (excluding per-head)."""
+    methods = ["rollout", "chefer", "gradcam", "integrated", "deeplift", "occlusion"]
+    results = []
+    for m in methods:
+        res = run_single_method(wrapper, image, m, alpha=alpha, cmap=cmap)
+        results.append(res)
+    return results

xai_engine/model.py

@@ -0,0 +1,79 @@
+import time
+import threading
+import torch
+import torch.nn as nn
+from PIL import Image
+from transformers import ViTForImageClassification, ViTImageProcessor
+
+MODEL_REPO = "buildborderless/CommunityForensics-DeepfakeDet-ViT"
+MODEL_TTL_SECONDS = 45 * 60  # 45 minutes
+
+_model_lock = threading.Lock()
+_model_instance = None
+_model_loaded_at = 0.0
+
+
+class ViTWrapper(nn.Module):
+    """Wrap HF ViT to work with Captum and PyTorch XAI methods."""
+    
+    def __init__(self, model_name=MODEL_REPO):
+        super().__init__()
+        self.model_name = model_name
+        self.model = ViTForImageClassification.from_pretrained(model_name)
+        self.model.set_attn_implementation('eager')  # Required for output_attentions
+        self.model.eval()
+        self.processor = ViTImageProcessor.from_pretrained(model_name)
+
+    def forward(self, x):
+        """Forward pass taking preprocessed tensor (B, C, H, W) and returning logits (B, 1)."""
+        outputs = self.model(pixel_values=x)
+        return outputs.logits
+
+    def preprocess(self, image: Image.Image) -> torch.Tensor:
+        """Preprocess PIL image to model input tensor matching preprocessor_config."""
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+        inputs = self.processor(
+            images=image,
+            return_tensors="pt",
+            size={"height": 384, "width": 384},
+        )
+        return inputs.pixel_values  # (1, 3, 384, 384)
+
+    def predict(self, image: Image.Image) -> dict:
+        """Get prediction label, probability, and raw logit."""
+        tensor = self.preprocess(image)
+        device = next(self.model.parameters()).device
+        tensor = tensor.to(device)
+        
+        with torch.no_grad():
+            logit = self.forward(tensor).item()
+            prob = float(torch.sigmoid(torch.tensor(logit)).item())
+            pred = "FAKE" if prob > 0.5 else "REAL"
+            conf = prob if pred == "FAKE" else (1.0 - prob)
+            
+        return {
+            "prediction": pred,
+            "probability": prob,
+            "confidence_pct": round(conf * 100, 2),
+            "logit": round(logit, 4),
+        }
+
+
+def get_model(device: str = None) -> ViTWrapper:
+    """Thread-safe singleton model loader with periodic background refresh."""
+    global _model_instance, _model_loaded_at
+    with _model_lock:
+        now = time.time()
+        if _model_instance is None or (now - _model_loaded_at) > MODEL_TTL_SECONDS:
+            if device is None:
+                device = "cpu"  # Default to CPU for CPU-based HF Space & low VRAM stability
+            wrapper = ViTWrapper(MODEL_REPO)
+            try:
+                wrapper.to(device)
+            except Exception as e:
+                print(f"[model] Target device {device} failed ({e}), falling back to CPU.")
+                wrapper.to("cpu")
+            _model_instance = wrapper
+            _model_loaded_at = now
+        return _model_instance

xai_engine/viz.py

@@ -0,0 +1,57 @@
+import base64
+from io import BytesIO
+import numpy as np
+from PIL import Image
+import matplotlib.pyplot as plt
+from skimage.transform import resize
+
+
+def normalize_heatmap(heatmap: np.ndarray) -> np.ndarray:
+    """Min-max normalize a heatmap array to [0, 1]."""
+    h_min, h_max = heatmap.min(), heatmap.max()
+    if h_max - h_min < 1e-8:
+        return np.zeros_like(heatmap)
+    return (heatmap - h_min) / (h_max - h_min + 1e-8)
+
+
+def create_overlay(image: Image.Image, heatmap: np.ndarray, alpha: float = 0.6, cmap: str = "jet") -> Image.Image:
+    """Blend a heatmap overlay onto a PIL Image."""
+    image_rgb = image.convert("RGB").resize((384, 384))
+    img_np = np.array(image_rgb) / 255.0
+
+    # Resize heatmap to match image dimension (384, 384)
+    if heatmap.shape != (384, 384):
+        heatmap_resized = resize(heatmap, (384, 384), order=1)
+    else:
+        heatmap_resized = heatmap
+
+    norm_h = normalize_heatmap(heatmap_resized)
+    
+    colormap = plt.get_cmap(cmap)
+    colored_heatmap = colormap(norm_h)[:, :, :3]  # Drop alpha channel
+    
+    overlay = (1 - alpha) * img_np + alpha * colored_heatmap
+    overlay = np.clip(overlay * 255, 0, 255).astype(np.uint8)
+    
+    return Image.fromarray(overlay)
+
+
+def render_heatmap_raw(heatmap: np.ndarray, cmap: str = "jet") -> Image.Image:
+    """Render raw normalized heatmap as RGB PIL Image using colormap."""
+    if heatmap.shape != (384, 384):
+        heatmap_resized = resize(heatmap, (384, 384), order=1)
+    else:
+        heatmap_resized = heatmap
+
+    norm_h = normalize_heatmap(heatmap_resized)
+    colormap = plt.get_cmap(cmap)
+    colored = (colormap(norm_h)[:, :, :3] * 255).astype(np.uint8)
+    return Image.fromarray(colored)
+
+
+def to_b64_png(image: Image.Image) -> str:
+    """Convert a PIL Image to a base64 encoded PNG data URL."""
+    buffer = BytesIO()
+    image.save(buffer, format="PNG")
+    b64_str = base64.b64encode(buffer.getvalue()).decode("utf-8")
+    return f"data:image/png;base64,{b64_str}"