Deploy DeepFake Detector API - 2026-03-07 09:12:00

.env.example

@@ -0,0 +1,24 @@
+# DeepFake Detector Backend - Environment Variables
+# Copy this file to .env and update with your values
+
+# Hugging Face Configuration
+# Available fusion models:
+#   - DeepFakeDetector/fusion-logreg-final (Logistic Regression - default)
+#   - DeepFakeDetector/fusion-meta-final (Meta-classifier)
+HF_FUSION_REPO_ID=DeepFakeDetector/fusion-logreg-final
+HF_CACHE_DIR=.hf_cache
+# HF_TOKEN=your_huggingface_token_here  # Optional: for private repos
+
+# Google Gemini API (Optional - for LLM explanations)
+# GOOGLE_API_KEY=your_google_api_key_here
+
+# Server Configuration
+HOST=0.0.0.0
+PORT=8000
+
+# CORS Configuration (comma-separated list of allowed origins)
+CORS_ORIGINS=http://localhost:8082,https://www.deepfake-detector.app,https://deepfake-detector.app
+
+# Debugging
+ENABLE_DEBUG=false
+LOG_LEVEL=INFO

Dockerfile

@@ -0,0 +1,43 @@
+# DeepFake Detector API - Hugging Face Spaces Docker Image
+# Optimized for HF Spaces deployment with GPU support
+
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PORT=7860
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user (HF Spaces requirement)
+RUN useradd -m -u 1000 user
+USER user
+
+# Set PATH for user-installed packages
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# Copy requirements and install dependencies as user
+COPY --chown=user:user requirements.txt .
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+# Copy application code
+COPY --chown=user:user . /app
+
+# Create cache directory for Hugging Face models
+RUN mkdir -p /app/.hf_cache
+
+# Expose HF Spaces port
+EXPOSE 7860
+
+# Run the application (start.sh already defaults to port 7860)
+CMD ["./start.sh"]

Dockerfile.huggingface

@@ -0,0 +1,43 @@
+# DeepFake Detector API - Hugging Face Spaces Docker Image
+# Optimized for HF Spaces deployment with GPU support
+
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PORT=7860
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user (HF Spaces requirement)
+RUN useradd -m -u 1000 user
+USER user
+
+# Set PATH for user-installed packages
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# Copy requirements and install dependencies as user
+COPY --chown=user:user requirements.txt .
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+# Copy application code
+COPY --chown=user:user . /app
+
+# Create cache directory for Hugging Face models
+RUN mkdir -p /app/.hf_cache
+
+# Expose HF Spaces port
+EXPOSE 7860
+
+# Run the application (start.sh already defaults to port 7860)
+CMD ["./start.sh"]

README.md

@@ -1,12 +1,182 @@
 ---
-title: DeepFakeDetectorBackend
-emoji: 👁
-colorFrom: gray
-colorTo: yellow
+title: DeepFake Detector API
+emoji: 🎭
+colorFrom: blue
+colorTo: purple
 sdk: docker
-pinned: false
-license: mit
-short_description: FastAPI Backend for MacAI Society DeepFake Detector
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎭 DeepFake Detector API
+
+FastAPI backend for detecting AI-generated (deepfake) images using an ensemble of state-of-the-art deep learning models.
+
+## 🤖 Models
+
+This API uses a fusion ensemble of 5 deep learning models:
+
+- **CNN Transfer** (EfficientNet-B0) - Transfer learning from ImageNet
+- **ViT Base** (Vision Transformer) - Attention-based architecture
+- **DeiT Distilled** (Data-efficient Image Transformer) - Distilled ViT variant
+- **Gradient Field CNN** - Custom architecture analyzing gradient patterns
+- **FFT CNN** - Frequency domain analysis using Fast Fourier Transform
+
+All models are combined using a **Logistic Regression stacking ensemble** for optimal accuracy.
+
+## 🔗 API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check - returns API status |
+| `/ready` | GET | Model readiness check - confirms models are loaded |
+| `/models` | GET | List all loaded models with metadata |
+| `/predict` | POST | Predict if an image is real or AI-generated |
+| `/docs` | GET | Interactive Swagger API documentation |
+| `/redoc` | GET | Alternative API documentation |
+
+## 🚀 Usage Example
+
+### Using cURL
+
+```bash
+# Check if API is ready
+curl https://lukhsaankumar-deepfakedetectorbackend.hf.space/ready
+
+# Make a prediction
+curl -X POST "https://lukhsaankumar-deepfakedetectorbackend.hf.space/predict" \
+  -F "file=@image.jpg" \
+  -F "explain=true"
+```
+
+### Using Python
+
+```python
+import requests
+
+# Upload an image for prediction
+url = "https://lukhsaankumar-deepfakedetectorbackend.hf.space/predict"
+files = {"file": open("image.jpg", "rb")}
+data = {"explain": True}
+
+response = requests.post(url, files=files, data=data)
+result = response.json()
+
+print(f"Prediction: {result['prediction']}")
+print(f"Confidence: {result['confidence']:.2%}")
+print(f"Explanation: {result['explanation']}")
+```
+
+## 🎯 Response Format
+
+```json
+{
+  "prediction": "fake",
+  "confidence": 0.8734,
+  "probabilities": {
+    "real": 0.1266,
+    "fake": 0.8734
+  },
+  "model_predictions": {
+    "cnn_transfer": {"prediction": "fake", "confidence": 0.89},
+    "vit_base": {"prediction": "fake", "confidence": 0.92},
+    "deit": {"prediction": "fake", "confidence": 0.85},
+    "gradient_field": {"prediction": "real", "confidence": 0.55},
+    "fft_cnn": {"prediction": "fake", "confidence": 0.78}
+  },
+  "fusion_confidence": 0.8734,
+  "explanation": "AI-powered analysis of the prediction...",
+  "processing_time_ms": 342
+}
+```
+
+## 🔧 Configuration
+
+### Required Secrets
+
+Set these in your Space Settings → Repository secrets:
+
+| Secret | Description | Required |
+|--------|-------------|----------|
+| `GOOGLE_API_KEY` | Google Gemini API key for AI explanations | Yes |
+| `HF_TOKEN` | Hugging Face token (auto-set by Spaces) | No |
+
+### Optional Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HF_FUSION_REPO_ID` | `DeepFakeDetector/fusion-logreg-final` | Hugging Face model repository |
+| `CORS_ORIGINS` | Multiple defaults | Comma-separated allowed CORS origins |
+| `GEMINI_MODEL` | `gemini-2.5-flash` | Gemini model for explanations |
+
+## 🏗️ Architecture
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────────────────┐
+│      FastAPI Backend            │
+│  ┌──────────────────────────┐   │
+│  │   Model Registry         │   │
+│  │  ┌────────────────────┐  │   │
+│  │  │ CNN Transfer       │  │   │
+│  │  │ ViT Base          │  │   │
+│  │  │ DeiT Distilled    │  │   │
+│  │  │ Gradient Field    │  │   │
+│  │  │ FFT CNN          │  │   │
+│  │  └────────────────────┘  │   │
+│  │  ┌────────────────────┐  │   │
+│  │  │ Fusion Ensemble    │  │   │
+│  │  │ (LogReg Stacking)  │  │   │
+│  │  └────────────────────┘  │   │
+│  └──────────────────────────┘   │
+│  ┌──────────────────────────┐   │
+│  │   Gemini Explainer       │   │
+│  └──────────────��───────────┘   │
+└─────────────────────────────────┘
+```
+
+## 📊 Performance
+
+- **Accuracy**: ~87% on test set (OpenFake dataset)
+- **Inference Time**: ~200-500ms per image (with GPU)
+- **Model Size**: ~500MB total
+- **Supported Formats**: JPG, PNG, WEBP
+
+## 🐛 Troubleshooting
+
+### Models not loading?
+- Check the Logs tab for specific errors
+- Verify `HF_FUSION_REPO_ID` points to a valid repository
+- Ensure the repository is public or `HF_TOKEN` is set
+
+### Explanations not working?
+- Verify `GOOGLE_API_KEY` is set in Space Settings
+- Check if you have Gemini API quota remaining
+- Review logs for API errors
+
+### CORS errors?
+- Add your frontend domain to `CORS_ORIGINS` in Space Settings
+- Format: `https://yourdomain.com,https://www.yourdomain.com`
+
+## 📚 Documentation
+
+- **Interactive Docs**: Visit `/docs` for Swagger UI
+- **ReDoc**: Visit `/redoc` for alternative documentation
+- **Source Code**: [GitHub Repository](https://github.com/lukhsaankumar/DeepFakeDetector)
+
+## 📝 License
+
+This project is part of the MacAI Society research initiative.
+
+## 🙏 Acknowledgments
+
+- Models trained on OpenFake, ImageNet, and custom datasets
+- Powered by PyTorch, Hugging Face, and FastAPI
+- AI explanations by Google Gemini
+
+---
+
+**Built with ❤️ by MacAI Society**

README_HF.md

@@ -0,0 +1,182 @@
+---
+title: DeepFake Detector API
+emoji: 🎭
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+---
+
+# 🎭 DeepFake Detector API
+
+FastAPI backend for detecting AI-generated (deepfake) images using an ensemble of state-of-the-art deep learning models.
+
+## 🤖 Models
+
+This API uses a fusion ensemble of 5 deep learning models:
+
+- **CNN Transfer** (EfficientNet-B0) - Transfer learning from ImageNet
+- **ViT Base** (Vision Transformer) - Attention-based architecture
+- **DeiT Distilled** (Data-efficient Image Transformer) - Distilled ViT variant
+- **Gradient Field CNN** - Custom architecture analyzing gradient patterns
+- **FFT CNN** - Frequency domain analysis using Fast Fourier Transform
+
+All models are combined using a **Logistic Regression stacking ensemble** for optimal accuracy.
+
+## 🔗 API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check - returns API status |
+| `/ready` | GET | Model readiness check - confirms models are loaded |
+| `/models` | GET | List all loaded models with metadata |
+| `/predict` | POST | Predict if an image is real or AI-generated |
+| `/docs` | GET | Interactive Swagger API documentation |
+| `/redoc` | GET | Alternative API documentation |
+
+## 🚀 Usage Example
+
+### Using cURL
+
+```bash
+# Check if API is ready
+curl https://lukhsaankumar-deepfakedetectorbackend.hf.space/ready
+
+# Make a prediction
+curl -X POST "https://lukhsaankumar-deepfakedetectorbackend.hf.space/predict" \
+  -F "file=@image.jpg" \
+  -F "explain=true"
+```
+
+### Using Python
+
+```python
+import requests
+
+# Upload an image for prediction
+url = "https://lukhsaankumar-deepfakedetectorbackend.hf.space/predict"
+files = {"file": open("image.jpg", "rb")}
+data = {"explain": True}
+
+response = requests.post(url, files=files, data=data)
+result = response.json()
+
+print(f"Prediction: {result['prediction']}")
+print(f"Confidence: {result['confidence']:.2%}")
+print(f"Explanation: {result['explanation']}")
+```
+
+## 🎯 Response Format
+
+```json
+{
+  "prediction": "fake",
+  "confidence": 0.8734,
+  "probabilities": {
+    "real": 0.1266,
+    "fake": 0.8734
+  },
+  "model_predictions": {
+    "cnn_transfer": {"prediction": "fake", "confidence": 0.89},
+    "vit_base": {"prediction": "fake", "confidence": 0.92},
+    "deit": {"prediction": "fake", "confidence": 0.85},
+    "gradient_field": {"prediction": "real", "confidence": 0.55},
+    "fft_cnn": {"prediction": "fake", "confidence": 0.78}
+  },
+  "fusion_confidence": 0.8734,
+  "explanation": "AI-powered analysis of the prediction...",
+  "processing_time_ms": 342
+}
+```
+
+## 🔧 Configuration
+
+### Required Secrets
+
+Set these in your Space Settings → Repository secrets:
+
+| Secret | Description | Required |
+|--------|-------------|----------|
+| `GOOGLE_API_KEY` | Google Gemini API key for AI explanations | Yes |
+| `HF_TOKEN` | Hugging Face token (auto-set by Spaces) | No |
+
+### Optional Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HF_FUSION_REPO_ID` | `DeepFakeDetector/fusion-logreg-final` | Hugging Face model repository |
+| `CORS_ORIGINS` | Multiple defaults | Comma-separated allowed CORS origins |
+| `GEMINI_MODEL` | `gemini-2.5-flash` | Gemini model for explanations |
+
+## 🏗️ Architecture
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────────────────┐
+│      FastAPI Backend            │
+│  ┌──────────────────────────┐   │
+│  │   Model Registry         │   │
+│  │  ┌────────────────────┐  │   │
+│  │  │ CNN Transfer       │  │   │
+│  │  │ ViT Base          │  │   │
+│  │  │ DeiT Distilled    │  │   │
+│  │  │ Gradient Field    │  │   │
+│  │  │ FFT CNN          │  │   │
+│  │  └────────────────────┘  │   │
+│  │  ┌────────────────────┐  │   │
+│  │  │ Fusion Ensemble    │  │   │
+│  │  │ (LogReg Stacking)  │  │   │
+│  │  └────────────────────┘  │   │
+│  └──────────────────────────┘   │
+│  ┌──────────────────────────┐   │
+│  │   Gemini Explainer       │   │
+│  └──────────────────────────┘   │
+└─────────────────────────────────┘
+```
+
+## 📊 Performance
+
+- **Accuracy**: ~87% on test set (OpenFake dataset)
+- **Inference Time**: ~200-500ms per image (with GPU)
+- **Model Size**: ~500MB total
+- **Supported Formats**: JPG, PNG, WEBP
+
+## 🐛 Troubleshooting
+
+### Models not loading?
+- Check the Logs tab for specific errors
+- Verify `HF_FUSION_REPO_ID` points to a valid repository
+- Ensure the repository is public or `HF_TOKEN` is set
+
+### Explanations not working?
+- Verify `GOOGLE_API_KEY` is set in Space Settings
+- Check if you have Gemini API quota remaining
+- Review logs for API errors
+
+### CORS errors?
+- Add your frontend domain to `CORS_ORIGINS` in Space Settings
+- Format: `https://yourdomain.com,https://www.yourdomain.com`
+
+## 📚 Documentation
+
+- **Interactive Docs**: Visit `/docs` for Swagger UI
+- **ReDoc**: Visit `/redoc` for alternative documentation
+- **Source Code**: [GitHub Repository](https://github.com/lukhsaankumar/DeepFakeDetector)
+
+## 📝 License
+
+This project is part of the MacAI Society research initiative.
+
+## 🙏 Acknowledgments
+
+- Models trained on OpenFake, ImageNet, and custom datasets
+- Powered by PyTorch, Hugging Face, and FastAPI
+- AI explanations by Google Gemini
+
+---
+
+**Built with ❤️ by MacAI Society**

app/__init__.py

@@ -0,0 +1 @@
+# DeepFake Detector Backend Application

app/api/__init__.py

@@ -0,0 +1 @@
+# API module

app/api/routes_health.py

@@ -0,0 +1,62 @@
+"""
+Health check routes.
+"""
+
+from fastapi import APIRouter
+
+from app.core.logging import get_logger
+from app.schemas.models import HealthResponse, ReadyResponse
+from app.services.model_registry import get_model_registry
+
+logger = get_logger(__name__)
+router = APIRouter(tags=["health"])
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    summary="Health check",
+    description="Simple health check to verify the API is running"
+)
+async def health_check() -> HealthResponse:
+    """
+    Health check endpoint.
+    
+    Returns OK if the API server is running.
+    """
+    return HealthResponse(status="ok")
+
+
+@router.get(
+    "/ready",
+    response_model=ReadyResponse,
+    summary="Readiness check",
+    description="Check if models are loaded and the API is ready to serve predictions"
+)
+async def readiness_check() -> ReadyResponse:
+    """
+    Readiness check endpoint.
+    
+    Verifies that models are loaded and ready for inference.
+    Returns detailed information about loaded models.
+    """
+    registry = get_model_registry()
+    
+    if not registry.is_loaded:
+        return ReadyResponse(
+            status="not_ready",
+            models_loaded=False,
+            fusion_repo=None,
+            submodels=[]
+        )
+    
+    return ReadyResponse(
+        status="ready",
+        models_loaded=True,
+        fusion_repo=registry.get_fusion_repo_id(),
+        submodels=[
+            model["repo_id"] 
+            for model in registry.list_models() 
+            if model["model_type"] == "submodel"
+        ]
+    )

app/api/routes_models.py

@@ -0,0 +1,51 @@
+"""
+Model listing routes.
+"""
+
+from fastapi import APIRouter
+
+from app.core.logging import get_logger
+from app.schemas.models import ModelsListResponse, ModelInfo
+from app.services.model_registry import get_model_registry
+
+logger = get_logger(__name__)
+router = APIRouter(tags=["models"])
+
+
+@router.get(
+    "/models",
+    response_model=ModelsListResponse,
+    summary="List loaded models",
+    description="Get information about all loaded models including fusion and submodels"
+)
+async def list_models() -> ModelsListResponse:
+    """
+    List all loaded models.
+    
+    Returns information about the fusion model and all submodels,
+    including their Hugging Face repository IDs and configurations.
+    """
+    registry = get_model_registry()
+    models = registry.list_models()
+    
+    fusion_info = None
+    submodels_info = []
+    
+    for model in models:
+        model_info = ModelInfo(
+            repo_id=model["repo_id"],
+            name=model["name"],
+            model_type=model["model_type"],
+            config=model.get("config")
+        )
+        
+        if model["model_type"] == "fusion":
+            fusion_info = model_info
+        else:
+            submodels_info.append(model_info)
+    
+    return ModelsListResponse(
+        fusion=fusion_info,
+        submodels=submodels_info,
+        total_count=len(models)
+    )

app/api/routes_predict.py

@@ -0,0 +1,286 @@
+"""
+Prediction routes.
+"""
+
+import base64
+from typing import Optional
+
+from fastapi import APIRouter, File, Form, HTTPException, Query, UploadFile
+
+from app.core.errors import (
+    DeepFakeDetectorError,
+    ImageProcessingError,
+    InferenceError,
+    FusionError,
+    ModelNotFoundError,
+    ModelNotLoadedError
+)
+from app.core.logging import get_logger
+from app.schemas.predict import (
+    PredictResponse,
+    PredictionResult,
+    TimingInfo,
+    ErrorResponse,
+    FusionMeta,
+    ModelDisplayInfo,
+    ExplainModelResponse,
+    SingleModelInsight
+)
+from app.services.inference_service import get_inference_service
+from app.services.fusion_service import get_fusion_service
+from app.services.preprocess_service import get_preprocess_service
+from app.services.model_registry import get_model_registry
+from app.services.llm_service import get_llm_service, get_model_display_info, MODEL_DISPLAY_INFO
+from app.utils.timing import Timer
+
+logger = get_logger(__name__)
+router = APIRouter(tags=["predict"])
+
+
+@router.post(
+    "/predict",
+    response_model=PredictResponse,
+    summary="Predict if image is real or fake",
+    description="Upload an image to get a deepfake detection prediction",
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid image or request"},
+        404: {"model": ErrorResponse, "description": "Model not found"},
+        500: {"model": ErrorResponse, "description": "Inference error"}
+    }
+)
+async def predict(
+    image: UploadFile = File(..., description="Image file to analyze"),
+    use_fusion: bool = Query(
+        True,
+        description="Use fusion model (majority vote) across all submodels"
+    ),
+    model: Optional[str] = Query(
+        None,
+        description="Specific submodel to use (name or repo_id). Only used when use_fusion=false"
+    ),
+    return_submodels: Optional[bool] = Query(
+        None,
+        description="Include individual submodel predictions in response. Defaults to true when use_fusion=true"
+    ),
+    explain: bool = Query(
+        True,
+        description="Generate explainability heatmaps (Grad-CAM for CNNs, attention rollout for transformers)"
+    )
+) -> PredictResponse:
+    """
+    Predict if an uploaded image is real or fake.
+    
+    When use_fusion=true (default):
+    - Runs all submodels on the image
+    - Combines predictions using majority vote fusion
+    - Returns the fused result plus optionally individual submodel results
+    
+    When use_fusion=false:
+    - Runs only the specified submodel (or the first available if not specified)
+    - Returns just that model's prediction
+    
+    Response includes timing information for each step.
+    """
+    timer = Timer()
+    timer.start_total()
+    
+    # Determine if we should return submodel results
+    should_return_submodels = return_submodels if return_submodels is not None else use_fusion
+    
+    try:
+        # Read image bytes
+        with timer.measure("download"):
+            image_bytes = await image.read()
+        
+        # Validate and preprocess
+        with timer.measure("preprocess"):
+            preprocess_service = get_preprocess_service()
+            preprocess_service.validate_image(image_bytes)
+        
+        inference_service = get_inference_service()
+        fusion_service = get_fusion_service()
+        registry = get_model_registry()
+        
+        if use_fusion:
+            # Run all submodels
+            with timer.measure("inference"):
+                submodel_outputs = inference_service.predict_all_submodels(
+                    image_bytes=image_bytes,
+                    explain=explain
+                )
+            
+            # Run fusion
+            with timer.measure("fusion"):
+                final_result = fusion_service.fuse(submodel_outputs=submodel_outputs)
+            
+            timer.stop_total()
+            
+            # Extract fusion meta (contribution percentages)
+            fusion_meta_dict = final_result.get("meta", {})
+            contribution_percentages = fusion_meta_dict.get("contribution_percentages", {})
+            
+            # Build fusion meta object
+            fusion_meta = FusionMeta(
+                submodel_weights=fusion_meta_dict.get("submodel_weights", {}),
+                weighted_contributions=fusion_meta_dict.get("weighted_contributions", {}),
+                contribution_percentages=contribution_percentages
+            ) if fusion_meta_dict else None
+            
+            # Build model display info for frontend
+            model_display_info = {
+                name: ModelDisplayInfo(**get_model_display_info(name))
+                for name in submodel_outputs.keys()
+            }
+            
+            # Build response
+            return PredictResponse(
+                final=PredictionResult(
+                    pred=final_result["pred"],
+                    pred_int=final_result["pred_int"],
+                    prob_fake=final_result["prob_fake"]
+                ),
+                fusion_used=True,
+                submodels={
+                    name: PredictionResult(
+                        pred=output["pred"],
+                        pred_int=output["pred_int"],
+                        prob_fake=output["prob_fake"],
+                        heatmap_base64=output.get("heatmap_base64"),
+                        explainability_type=output.get("explainability_type"),
+                        focus_summary=output.get("focus_summary"),
+                        contribution_percentage=contribution_percentages.get(name)
+                    )
+                    for name, output in submodel_outputs.items()
+                } if should_return_submodels else None,
+                fusion_meta=fusion_meta,
+                model_display_info=model_display_info if should_return_submodels else None,
+                timing_ms=TimingInfo(**timer.get_timings())
+            )
+        
+        else:
+            # Single model prediction
+            model_key = model or registry.get_submodel_names()[0]
+            
+            with timer.measure("inference"):
+                result = inference_service.predict_single(
+                    model_key=model_key,
+                    image_bytes=image_bytes,
+                    explain=explain
+                )
+            
+            timer.stop_total()
+            
+            return PredictResponse(
+                final=PredictionResult(
+                    pred=result["pred"],
+                    pred_int=result["pred_int"],
+                    prob_fake=result["prob_fake"],
+                    heatmap_base64=result.get("heatmap_base64"),
+                    explainability_type=result.get("explainability_type"),
+                    focus_summary=result.get("focus_summary")
+                ),
+                fusion_used=False,
+                submodels=None,
+                timing_ms=TimingInfo(**timer.get_timings())
+            )
+    
+    except ImageProcessingError as e:
+        logger.warning(f"Image processing error: {e.message}")
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "ImageProcessingError", "message": e.message, "details": e.details}
+        )
+    
+    except ModelNotFoundError as e:
+        logger.warning(f"Model not found: {e.message}")
+        raise HTTPException(
+            status_code=404,
+            detail={"error": "ModelNotFoundError", "message": e.message, "details": e.details}
+        )
+    
+    except ModelNotLoadedError as e:
+        logger.error(f"Models not loaded: {e.message}")
+        raise HTTPException(
+            status_code=503,
+            detail={"error": "ModelNotLoadedError", "message": e.message, "details": e.details}
+        )
+    
+    except (InferenceError, FusionError) as e:
+        logger.error(f"Inference/Fusion error: {e.message}")
+        raise HTTPException(
+            status_code=500,
+            detail={"error": type(e).__name__, "message": e.message, "details": e.details}
+        )
+    
+    except Exception as e:
+        logger.exception(f"Unexpected error in predict endpoint: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail={"error": "InternalError", "message": str(e)}
+        )
+
+
+@router.post("/explain-model", response_model=ExplainModelResponse)
+async def explain_model(
+    image: UploadFile = File(...),
+    model_name: str = Form(...),
+    prob_fake: float = Form(...),
+    contribution_percentage: float = Form(None),
+    heatmap_base64: str = Form(None),
+    focus_summary: str = Form(None)
+):
+    """
+    Generate an on-demand LLM explanation for a single model's prediction.
+    This endpoint is token-efficient - only called when user requests insights.
+    """
+    try:
+        # Read and validate image
+        image_bytes = await image.read()
+        if len(image_bytes) == 0:
+            raise HTTPException(status_code=400, detail="Empty image file")
+        
+        # Encode image to base64 for LLM
+        original_b64 = base64.b64encode(image_bytes).decode('utf-8')
+        
+        # Get LLM service
+        llm_service = get_llm_service()
+        if not llm_service.enabled:
+            raise HTTPException(
+                status_code=503, 
+                detail="LLM service is not enabled. Set GEMINI_API_KEY environment variable."
+            )
+        
+        # Generate explanation
+        result = llm_service.generate_single_model_explanation(
+            model_name=model_name,
+            original_image_b64=original_b64,
+            prob_fake=prob_fake,
+            heatmap_b64=heatmap_base64,
+            contribution_percentage=contribution_percentage,
+            focus_summary=focus_summary
+        )
+        
+        if result is None:
+            raise HTTPException(
+                status_code=500,
+                detail="Failed to generate explanation from LLM"
+            )
+        
+        return ExplainModelResponse(
+            model_name=model_name,
+            insight=SingleModelInsight(
+                key_finding=result["key_finding"],
+                what_model_saw=result["what_model_saw"],
+                important_regions=result["important_regions"],
+                confidence_qualifier=result["confidence_qualifier"]
+            )
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception(f"Error generating model explanation: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail={"error": "ExplanationError", "message": str(e)}
+        )

app/core/__init__.py

@@ -0,0 +1 @@
+# Core module

app/core/config.py

@@ -0,0 +1,64 @@
+"""
+Application configuration with environment variable support.
+"""
+
+import os
+from functools import lru_cache
+from pydantic_settings import BaseSettings
+from typing import Optional
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+    
+    # Hugging Face configuration
+    # Available fusion models:
+    #   - DeepFakeDetector/fusion-logreg-final (Logistic Regression - default)
+    #   - DeepFakeDetector/fusion-meta-final (Meta-classifier)
+    HF_FUSION_REPO_ID: str = "DeepFakeDetector/fusion-logreg-final"
+    HF_CACHE_DIR: str = ".hf_cache"
+    HF_TOKEN: Optional[str] = None
+    
+    # Google Gemini API configuration
+    GOOGLE_API_KEY: Optional[str] = None
+    GEMINI_MODEL: str = "gemini-2.5-flash"
+    
+    @property
+    def llm_enabled(self) -> bool:
+        """Check if LLM explanations are available."""
+        return self.GOOGLE_API_KEY is not None and len(self.GOOGLE_API_KEY) > 0
+    
+    # Application configuration
+    ENABLE_DEBUG: bool = False
+    LOG_LEVEL: str = "INFO"
+    
+    # Server configuration
+    HOST: str = "0.0.0.0"
+    PORT: int = 8000
+    
+    # CORS configuration
+    CORS_ORIGINS: str = "http://localhost:5173,http://localhost:3000,https://www.deepfake-detector.app,https://deepfake-detector.app"
+    
+    @property
+    def cors_origins_list(self) -> list[str]:
+        """Parse CORS origins from comma-separated string."""
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",") if origin.strip()]
+    
+    # API configuration
+    API_V1_PREFIX: str = "/api/v1"
+    PROJECT_NAME: str = "DeepFake Detector API"
+    VERSION: str = "0.1.0"
+    
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = True
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings()
+
+
+settings = get_settings()

app/core/errors.py

@@ -0,0 +1,53 @@
+"""
+Custom exceptions and error handling for the application.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class DeepFakeDetectorError(Exception):
+    """Base exception for DeepFake Detector application."""
+    
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        self.message = message
+        self.details = details or {}
+        super().__init__(self.message)
+
+
+class ModelNotLoadedError(DeepFakeDetectorError):
+    """Raised when attempting to use a model that hasn't been loaded."""
+    pass
+
+
+class ModelNotFoundError(DeepFakeDetectorError):
+    """Raised when a requested model is not found in the registry."""
+    pass
+
+
+class HuggingFaceDownloadError(DeepFakeDetectorError):
+    """Raised when downloading from Hugging Face fails."""
+    pass
+
+
+class ImageProcessingError(DeepFakeDetectorError):
+    """Raised when image processing/decoding fails."""
+    pass
+
+
+class InferenceError(DeepFakeDetectorError):
+    """Raised when model inference fails."""
+    pass
+
+
+class FusionError(DeepFakeDetectorError):
+    """Raised when fusion prediction fails."""
+    pass
+
+
+class ConfigurationError(DeepFakeDetectorError):
+    """Raised when configuration is invalid or missing."""
+    pass

app/core/logging.py

@@ -0,0 +1,61 @@
+"""
+Logging configuration for the application.
+"""
+
+import logging
+import sys
+from typing import Optional
+
+from app.core.config import settings
+
+
+def setup_logging(level: Optional[str] = None) -> logging.Logger:
+    """
+    Set up application logging.
+    
+    Args:
+        level: Log level string (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        
+    Returns:
+        Configured logger instance
+    """
+    log_level = level or settings.LOG_LEVEL
+    
+    # Create formatter
+    formatter = logging.Formatter(
+        fmt="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S"
+    )
+    
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(getattr(logging, log_level.upper(), logging.INFO))
+    
+    # Remove existing handlers
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+    
+    # Add stdout handler
+    stdout_handler = logging.StreamHandler(sys.stdout)
+    stdout_handler.setFormatter(formatter)
+    root_logger.addHandler(stdout_handler)
+    
+    # Set third-party loggers to WARNING to reduce noise
+    logging.getLogger("uvicorn").setLevel(logging.WARNING)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("huggingface_hub").setLevel(logging.WARNING)
+    
+    return root_logger
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a named logger instance.
+    
+    Args:
+        name: Logger name (typically __name__)
+        
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(name)

app/main.py

@@ -0,0 +1,128 @@
+"""
+FastAPI application entry point.
+
+DeepFake Detector API - Milestone 1: Hugging Face hosted dummy models.
+"""
+
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from app.api import routes_health, routes_models, routes_predict
+from app.core.config import settings
+from app.core.errors import DeepFakeDetectorError
+from app.core.logging import setup_logging, get_logger
+from app.services.model_registry import get_model_registry
+
+# Set up logging
+setup_logging()
+logger = get_logger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """
+    Application lifespan manager.
+    
+    Handles startup and shutdown events:
+    - Startup: Load models from Hugging Face
+    - Shutdown: Cleanup resources
+    """
+    # Startup
+    logger.info("Starting DeepFake Detector API...")
+    logger.info(f"Configuration: HF_FUSION_REPO_ID={settings.HF_FUSION_REPO_ID}")
+    logger.info(f"Configuration: HF_CACHE_DIR={settings.HF_CACHE_DIR}")
+    
+    # Load models from Hugging Face
+    try:
+        registry = get_model_registry()
+        await registry.load_from_fusion_repo(settings.HF_FUSION_REPO_ID)
+        logger.info("Models loaded successfully!")
+    except Exception as e:
+        logger.error(f"Failed to load models on startup: {e}")
+        logger.warning("API will start but /ready will report not_ready until models are loaded")
+    
+    yield  # Application runs here
+    
+    # Shutdown
+    logger.info("Shutting down DeepFake Detector API...")
+
+
+# Create FastAPI application
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version=settings.VERSION,
+    description="""
+    DeepFake Detector API - Analyze images to detect AI-generated content.
+    
+    ## Features
+    
+    - **Fusion prediction**: Combines multiple model predictions using majority vote
+    - **Individual model prediction**: Run specific submodels directly
+    - **Timing information**: Detailed performance metrics for each request
+    
+    ## Milestone 1
+    
+    This is the initial milestone using dummy random models hosted on Hugging Face
+    for testing the API infrastructure.
+    """,
+    lifespan=lifespan,
+    debug=settings.ENABLE_DEBUG
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+logger.info(f"CORS enabled for origins: {settings.cors_origins_list}")
+
+
+# Global exception handler for custom errors
+@app.exception_handler(DeepFakeDetectorError)
+async def deepfake_error_handler(request: Request, exc: DeepFakeDetectorError):
+    """Handle custom DeepFakeDetector exceptions."""
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": type(exc).__name__,
+            "message": exc.message,
+            "details": exc.details
+        }
+    )
+
+
+# Include routers
+app.include_router(routes_health.router)
+app.include_router(routes_models.router)
+app.include_router(routes_predict.router)
+
+
+# Root endpoint
+@app.get("/", tags=["root"])
+async def root():
+    """Root endpoint with API information."""
+    return {
+        "name": settings.PROJECT_NAME,
+        "version": settings.VERSION,
+        "docs": "/docs",
+        "health": "/health",
+        "ready": "/ready"
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "app.main:app",
+        host=settings.HOST,
+        port=settings.PORT,
+        reload=settings.ENABLE_DEBUG
+    )

app/models/__init__.py

@@ -0,0 +1 @@
+# Models module

app/models/wrappers/__init__.py

@@ -0,0 +1 @@
+# Model wrappers module

app/models/wrappers/base_wrapper.py

@@ -0,0 +1,150 @@
+"""
+Base wrapper class for model wrappers.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, Optional
+
+from PIL import Image
+
+
+class BaseModelWrapper(ABC):
+    """
+    Abstract base class for model wrappers.
+    
+    All model wrappers should inherit from this class and implement
+    the abstract methods.
+    """
+    
+    def __init__(
+        self,
+        repo_id: str,
+        config: Dict[str, Any],
+        local_path: str
+    ):
+        """
+        Initialize the wrapper.
+        
+        Args:
+            repo_id: Hugging Face repository ID
+            config: Configuration from config.json
+            local_path: Local path where the model files are stored
+        """
+        self.repo_id = repo_id
+        self.config = config
+        self.local_path = local_path
+        self._predict_fn: Optional[Callable] = None
+    
+    @property
+    def name(self) -> str:
+        """
+        Get the short name of the model.
+        
+        Prefers 'name' from config if available, otherwise derives from repo_id.
+        Strips '-final' suffix to ensure consistency with fusion configs.
+        """
+        # Try to get name from config first
+        config_name = self.config.get("name")
+        if config_name:
+            # Strip -final suffix if present
+            return config_name.replace("-final", "")
+        
+        # Fall back to repo_id last part, strip -final suffix
+        repo_name = self.repo_id.split("/")[-1]
+        return repo_name.replace("-final", "")
+    
+    @abstractmethod
+    def load(self) -> None:
+        """
+        Load the model and prepare for inference.
+        
+        This method should import the predict function from the downloaded
+        repository and store it for later use.
+        """
+        pass
+    
+    @abstractmethod
+    def predict(self, *args, **kwargs) -> Dict[str, Any]:
+        """
+        Run prediction.
+        
+        Returns:
+            Dictionary with standardized prediction fields:
+            - pred_int: 0 (real) or 1 (fake)
+            - pred: "real" or "fake"
+            - prob_fake: float probability
+            - meta: dict with any additional metadata
+        """
+        pass
+    
+    def is_loaded(self) -> bool:
+        """Check if the model is loaded and ready for inference."""
+        return self._predict_fn is not None
+    
+    def get_info(self) -> Dict[str, Any]:
+        """
+        Get model information.
+        
+        Returns:
+            Dictionary with model info
+        """
+        return {
+            "repo_id": self.repo_id,
+            "name": self.name,
+            "config": self.config,
+            "local_path": self.local_path,
+            "is_loaded": self.is_loaded()
+        }
+
+
+class BaseSubmodelWrapper(BaseModelWrapper):
+    """Base wrapper for submodels that process images."""
+    
+    @abstractmethod
+    def predict(
+        self,
+        image: Optional[Image.Image] = None,
+        image_bytes: Optional[bytes] = None,
+        explain: bool = False,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run prediction on an image.
+        
+        Args:
+            image: PIL Image object
+            image_bytes: Raw image bytes (alternative to image)
+            explain: If True, include explainability heatmap in output
+            **kwargs: Additional arguments
+            
+        Returns:
+            Standardized prediction dictionary with:
+            - pred_int: 0 (real) or 1 (fake)
+            - pred: "real" or "fake"
+            - prob_fake: float probability
+            - heatmap_base64: Optional[str] (when explain=True)
+            - explainability_type: Optional[str] (when explain=True)
+        """
+        pass
+
+
+class BaseFusionWrapper(BaseModelWrapper):
+    """Base wrapper for fusion models that combine submodel outputs."""
+    
+    @abstractmethod
+    def predict(
+        self,
+        submodel_outputs: Dict[str, Dict[str, Any]],
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run fusion prediction on submodel outputs.
+        
+        Args:
+            submodel_outputs: Dictionary mapping submodel name to its output
+            **kwargs: Additional arguments
+            
+        Returns:
+            Standardized prediction dictionary
+        """
+        pass

app/models/wrappers/cnn_transfer_wrapper.py

@@ -0,0 +1,226 @@
+"""
+Wrapper for CNN Transfer (EfficientNet-B0) submodel.
+"""
+
+import json
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+from PIL import Image
+from torchvision import transforms
+from torchvision.models import efficientnet_b0, EfficientNet_B0_Weights
+
+from app.core.errors import InferenceError, ConfigurationError
+from app.core.logging import get_logger
+from app.models.wrappers.base_wrapper import BaseSubmodelWrapper
+from app.services.explainability import GradCAM, heatmap_to_base64, compute_focus_summary
+
+logger = get_logger(__name__)
+
+
+class CNNTransferWrapper(BaseSubmodelWrapper):
+    """
+    Wrapper for CNN Transfer model using EfficientNet-B0 backbone.
+    
+    Model expects 224x224 RGB images with ImageNet normalization.
+    """
+    
+    def __init__(
+        self,
+        repo_id: str,
+        config: Dict[str, Any],
+        local_path: str
+    ):
+        super().__init__(repo_id, config, local_path)
+        self._model: Optional[nn.Module] = None
+        self._transform: Optional[transforms.Compose] = None
+        self._device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        self._threshold = config.get("threshold", 0.5)
+        logger.info(f"Initialized CNNTransferWrapper for {repo_id}")
+    
+    def load(self) -> None:
+        """Load the EfficientNet-B0 model with trained weights."""
+        weights_path = Path(self.local_path) / "model.pth"
+        preprocess_path = Path(self.local_path) / "preprocess.json"
+        
+        if not weights_path.exists():
+            raise ConfigurationError(
+                message=f"model.pth not found in {self.local_path}",
+                details={"repo_id": self.repo_id, "expected_path": str(weights_path)}
+            )
+        
+        try:
+            # Load preprocessing config
+            preprocess_config = {}
+            if preprocess_path.exists():
+                with open(preprocess_path, "r") as f:
+                    preprocess_config = json.load(f)
+            
+            # Build transform pipeline
+            input_size = preprocess_config.get("input_size", [224, 224])
+            if isinstance(input_size, int):
+                input_size = [input_size, input_size]
+            
+            normalize_config = preprocess_config.get("normalize", {})
+            mean = normalize_config.get("mean", [0.485, 0.456, 0.406])
+            std = normalize_config.get("std", [0.229, 0.224, 0.225])
+            
+            self._transform = transforms.Compose([
+                transforms.Resize(input_size),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std)
+            ])
+            
+            # Create model architecture
+            num_classes = self.config.get("num_classes", 2)
+            self._model = efficientnet_b0(weights=None)
+            
+            # Replace classifier for binary classification
+            in_features = self._model.classifier[1].in_features
+            self._model.classifier = nn.Sequential(
+                nn.Dropout(p=0.2, inplace=True),
+                nn.Linear(in_features, num_classes)
+            )
+            
+            # Load trained weights
+            state_dict = torch.load(weights_path, map_location=self._device, weights_only=True)
+            self._model.load_state_dict(state_dict)
+            self._model.to(self._device)
+            self._model.eval()
+            
+            # Mark as loaded
+            self._predict_fn = self._run_inference
+            logger.info(f"Loaded CNN Transfer model from {self.repo_id}")
+            
+        except ConfigurationError:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load CNN Transfer model: {e}")
+            raise ConfigurationError(
+                message=f"Failed to load model: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def _run_inference(
+        self,
+        image_tensor: torch.Tensor,
+        explain: bool = False
+    ) -> Dict[str, Any]:
+        """Run model inference on preprocessed tensor."""
+        heatmap = None
+        
+        if explain:
+            # Use GradCAM for explainability (requires gradients)
+            target_layer = self._model.features[-1]  # Last MBConv block
+            gradcam = GradCAM(self._model, target_layer)
+            try:
+                # GradCAM needs gradients, so don't use no_grad
+                logits = self._model(image_tensor)
+                probs = F.softmax(logits, dim=1)
+                prob_fake = probs[0, 1].item()
+                pred_int = 1 if prob_fake >= self._threshold else 0
+                
+                # Compute heatmap for predicted class
+                heatmap = gradcam(
+                    image_tensor.clone(),
+                    target_class=pred_int,
+                    output_size=(224, 224)
+                )
+            finally:
+                gradcam.remove_hooks()
+        else:
+            with torch.no_grad():
+                logits = self._model(image_tensor)
+                probs = F.softmax(logits, dim=1)
+                prob_fake = probs[0, 1].item()
+                pred_int = 1 if prob_fake >= self._threshold else 0
+        
+        result = {
+            "logits": logits[0].detach().cpu().numpy().tolist(),
+            "prob_fake": prob_fake,
+            "pred_int": pred_int
+        }
+        
+        if heatmap is not None:
+            result["heatmap"] = heatmap
+        
+        return result
+    
+    def predict(
+        self,
+        image: Optional[Image.Image] = None,
+        image_bytes: Optional[bytes] = None,
+        explain: bool = False,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run prediction on an image.
+        
+        Args:
+            image: PIL Image object
+            image_bytes: Raw image bytes (will be converted to PIL Image)
+            explain: If True, compute GradCAM heatmap
+            
+        Returns:
+            Standardized prediction dictionary with optional heatmap
+        """
+        if self._model is None or self._transform is None:
+            raise InferenceError(
+                message="Model not loaded",
+                details={"repo_id": self.repo_id}
+            )
+        
+        try:
+            # Convert bytes to PIL Image if needed
+            if image is None and image_bytes is not None:
+                import io
+                image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+            elif image is not None:
+                image = image.convert("RGB")
+            else:
+                raise InferenceError(
+                    message="No image provided",
+                    details={"repo_id": self.repo_id}
+                )
+            
+            # Preprocess
+            image_tensor = self._transform(image).unsqueeze(0).to(self._device)
+            
+            # Run inference
+            result = self._run_inference(image_tensor, explain=explain)
+            
+            # Standardize output
+            labels = self.config.get("labels", {"0": "real", "1": "fake"})
+            pred_int = result["pred_int"]
+            
+            output = {
+                "pred_int": pred_int,
+                "pred": labels.get(str(pred_int), "unknown"),
+                "prob_fake": result["prob_fake"],
+                "meta": {
+                    "model": self.name,
+                    "threshold": self._threshold,
+                    "logits": result["logits"]
+                }
+            }
+            
+            # Add heatmap if requested
+            if explain and "heatmap" in result:
+                heatmap = result["heatmap"]
+                output["heatmap_base64"] = heatmap_to_base64(heatmap)
+                output["explainability_type"] = "grad_cam"
+                output["focus_summary"] = compute_focus_summary(heatmap)
+            
+            return output
+            
+        except InferenceError:
+            raise
+        except Exception as e:
+            logger.error(f"Prediction failed for {self.repo_id}: {e}")
+            raise InferenceError(
+                message=f"Prediction failed: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )

app/models/wrappers/deit_distilled_wrapper.py

@@ -0,0 +1,312 @@
+"""
+Wrapper for DeiT Distilled submodel.
+"""
+
+import json
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from PIL import Image
+from torchvision import transforms
+
+try:
+    import timm
+    TIMM_AVAILABLE = True
+except ImportError:
+    TIMM_AVAILABLE = False
+
+from app.core.errors import InferenceError, ConfigurationError
+from app.core.logging import get_logger
+from app.models.wrappers.base_wrapper import BaseSubmodelWrapper
+from app.services.explainability import attention_rollout, heatmap_to_base64, compute_focus_summary
+
+logger = get_logger(__name__)
+
+
+def create_custom_mlp_head(in_features: int = 768, num_classes: int = 2) -> nn.Sequential:
+    """
+    Create custom MLP head for DeiT model matching training configuration.
+    
+    Returns nn.Sequential to match saved state dict keys (0, 1, 4 indices).
+    """
+    return nn.Sequential(
+        nn.LayerNorm(in_features),   # 0
+        nn.Linear(in_features, 512), # 1
+        nn.GELU(),                   # 2 (no params)
+        nn.Dropout(p=0.2),           # 3 (no params)
+        nn.Linear(512, num_classes)  # 4
+    )
+
+
+class DeiTDistilledWrapper(BaseSubmodelWrapper):
+    """
+    Wrapper for DeiT Distilled model.
+    
+    Model expects 224x224 RGB images with ImageNet normalization.
+    Uses a custom MLP head for classification.
+    """
+    
+    def __init__(
+        self,
+        repo_id: str,
+        config: Dict[str, Any],
+        local_path: str
+    ):
+        super().__init__(repo_id, config, local_path)
+        self._model: Optional[nn.Module] = None
+        self._transform: Optional[transforms.Compose] = None
+        self._device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        self._threshold = config.get("threshold", 0.5)
+        logger.info(f"Initialized DeiTDistilledWrapper for {repo_id}")
+    
+    def load(self) -> None:
+        """Load the DeiT model with custom head and trained weights."""
+        if not TIMM_AVAILABLE:
+            raise ConfigurationError(
+                message="timm package not installed. Run: pip install timm",
+                details={"repo_id": self.repo_id}
+            )
+        
+        weights_path = Path(self.local_path) / "deit_distilled_final.pt"
+        preprocess_path = Path(self.local_path) / "preprocess.json"
+        
+        if not weights_path.exists():
+            raise ConfigurationError(
+                message=f"deit_distilled_final.pt not found in {self.local_path}",
+                details={"repo_id": self.repo_id, "expected_path": str(weights_path)}
+            )
+        
+        try:
+            # Load preprocessing config
+            preprocess_config = {}
+            if preprocess_path.exists():
+                with open(preprocess_path, "r") as f:
+                    preprocess_config = json.load(f)
+            
+            # Build transform pipeline
+            input_size = preprocess_config.get("input_size", 224)
+            if isinstance(input_size, list):
+                input_size = input_size[0]
+            
+            normalize_config = preprocess_config.get("normalize", {})
+            mean = normalize_config.get("mean", [0.485, 0.456, 0.406])
+            std = normalize_config.get("std", [0.229, 0.224, 0.225])
+            
+            # Use bicubic interpolation as specified
+            interpolation = preprocess_config.get("interpolation", "bicubic")
+            interp_mode = transforms.InterpolationMode.BICUBIC if interpolation == "bicubic" else transforms.InterpolationMode.BILINEAR
+            
+            self._transform = transforms.Compose([
+                transforms.Resize((input_size, input_size), interpolation=interp_mode),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std)
+            ])
+            
+            # Create model architecture
+            model_name = self.config.get("model_name", "deit_base_distilled_patch16_224")
+            num_classes = self.config.get("num_classes", 2)
+            
+            # Create base model without pretrained weights
+            self._model = timm.create_model(model_name, pretrained=False, num_classes=0)
+            
+            # Replace heads with custom MLP heads (Sequential assigned directly)
+            # Note: state dict has separate keys for head and head_dist, so don't share
+            hidden_dim = 768  # DeiT base hidden dimension
+            self._model.head = create_custom_mlp_head(hidden_dim, num_classes)
+            self._model.head_dist = create_custom_mlp_head(hidden_dim, num_classes)
+            
+            # Load trained weights
+            state_dict = torch.load(weights_path, map_location=self._device, weights_only=True)
+            self._model.load_state_dict(state_dict)
+            self._model.to(self._device)
+            self._model.eval()
+            
+            # Mark as loaded
+            self._predict_fn = self._run_inference
+            logger.info(f"Loaded DeiT Distilled model from {self.repo_id}")
+            
+        except ConfigurationError:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load DeiT Distilled model: {e}")
+            raise ConfigurationError(
+                message=f"Failed to load model: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def _run_inference(
+        self,
+        image_tensor: torch.Tensor,
+        explain: bool = False
+    ) -> Dict[str, Any]:
+        """Run model inference on preprocessed tensor."""
+        heatmap = None
+        
+        if explain:
+            # Collect attention weights from all blocks
+            attentions: List[torch.Tensor] = []
+            handles = []
+            
+            # Hook into attention modules to capture weights
+            # DeiT blocks structure: blocks[i].attn
+            def create_attn_hook():
+                stored_attn = []
+                
+                def hook(module, inputs, outputs):
+                    # Get q, k from the module's forward computation
+                    # inputs[0] is x of shape [B, N, C]
+                    x = inputs[0]
+                    B, N, C = x.shape
+                    
+                    # Access the attention module's parameters
+                    qkv = module.qkv(x)  # [B, N, 3*dim]
+                    qkv = qkv.reshape(B, N, 3, module.num_heads, C // module.num_heads)
+                    qkv = qkv.permute(2, 0, 3, 1, 4)  # [3, B, heads, N, dim_head]
+                    q, k, v = qkv[0], qkv[1], qkv[2]
+                    
+                    # Compute attention weights
+                    scale = (C // module.num_heads) ** -0.5
+                    attn = (q @ k.transpose(-2, -1)) * scale
+                    attn = attn.softmax(dim=-1)  # [B, heads, N, N]
+                    
+                    # Average over heads
+                    attn_avg = attn.mean(dim=1)  # [B, N, N]
+                    stored_attn.append(attn_avg.detach())
+                
+                return hook, stored_attn
+            
+            all_stored_attns = []
+            for block in self._model.blocks:
+                hook_fn, stored = create_attn_hook()
+                all_stored_attns.append(stored)
+                handle = block.attn.register_forward_hook(hook_fn)
+                handles.append(handle)
+            
+            try:
+                with torch.no_grad():
+                    logits = self._model(image_tensor)
+                    probs = F.softmax(logits, dim=1)
+                    prob_fake = probs[0, 1].item()
+                    pred_int = 1 if prob_fake >= self._threshold else 0
+                
+                # Get attention from hooks
+                attention_list = [stored[0] for stored in all_stored_attns if len(stored) > 0]
+                
+                if attention_list:
+                    # Stack: [num_layers, B, N, N]
+                    attention_stack = torch.stack(attention_list, dim=0)
+                    # Compute rollout - returns (grid_size, grid_size) heatmap
+                    attention_map = attention_rollout(
+                        attention_stack[:, 0],  # [num_layers, N, N]
+                        head_fusion="mean",  # Already averaged
+                        discard_ratio=0.0,
+                        num_prefix_tokens=2  # DeiT has CLS + distillation token
+                    )  # Returns (14, 14) for DeiT-Base
+                    
+                    # Resize to image size
+                    from PIL import Image as PILImage
+                    heatmap_img = PILImage.fromarray(
+                        (attention_map * 255).astype(np.uint8)
+                    ).resize((224, 224), PILImage.BILINEAR)
+                    heatmap = np.array(heatmap_img).astype(np.float32) / 255.0
+                    
+            finally:
+                for handle in handles:
+                    handle.remove()
+        else:
+            with torch.no_grad():
+                # In eval mode, DeiT returns single tensor
+                logits = self._model(image_tensor)
+                probs = F.softmax(logits, dim=1)
+                prob_fake = probs[0, 1].item()
+                pred_int = 1 if prob_fake >= self._threshold else 0
+        
+        result = {
+            "logits": logits[0].cpu().numpy().tolist(),
+            "prob_fake": prob_fake,
+            "pred_int": pred_int
+        }
+        
+        if heatmap is not None:
+            result["heatmap"] = heatmap
+        
+        return result
+    
+    def predict(
+        self,
+        image: Optional[Image.Image] = None,
+        image_bytes: Optional[bytes] = None,
+        explain: bool = False,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run prediction on an image.
+        
+        Args:
+            image: PIL Image object
+            image_bytes: Raw image bytes (will be converted to PIL Image)
+            explain: If True, compute attention rollout heatmap
+            
+        Returns:
+            Standardized prediction dictionary with optional heatmap
+        """
+        if self._model is None or self._transform is None:
+            raise InferenceError(
+                message="Model not loaded",
+                details={"repo_id": self.repo_id}
+            )
+        
+        try:
+            # Convert bytes to PIL Image if needed
+            if image is None and image_bytes is not None:
+                import io
+                image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+            elif image is not None:
+                image = image.convert("RGB")
+            else:
+                raise InferenceError(
+                    message="No image provided",
+                    details={"repo_id": self.repo_id}
+                )
+            
+            # Preprocess
+            image_tensor = self._transform(image).unsqueeze(0).to(self._device)
+            
+            # Run inference
+            result = self._run_inference(image_tensor, explain=explain)
+            
+            # Standardize output
+            class_mapping = self.config.get("class_mapping", {"0": "real", "1": "fake"})
+            pred_int = result["pred_int"]
+            
+            output = {
+                "pred_int": pred_int,
+                "pred": class_mapping.get(str(pred_int), "unknown"),
+                "prob_fake": result["prob_fake"],
+                "meta": {
+                    "model": self.name,
+                    "threshold": self._threshold,
+                    "logits": result["logits"]
+                }
+            }
+            
+            # Add heatmap if requested
+            if explain and "heatmap" in result:
+                heatmap = result["heatmap"]
+                output["heatmap_base64"] = heatmap_to_base64(heatmap)
+                output["explainability_type"] = "attention_rollout"
+                output["focus_summary"] = compute_focus_summary(heatmap)
+            
+            return output
+            
+        except InferenceError:
+            raise
+        except Exception as e:
+            logger.error(f"Prediction failed for {self.repo_id}: {e}")
+            raise InferenceError(
+                message=f"Prediction failed: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )

app/models/wrappers/dummy_majority_fusion_wrapper.py

@@ -0,0 +1,171 @@
+"""
+Wrapper for dummy majority vote fusion model.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+from app.core.errors import FusionError, ConfigurationError
+from app.core.logging import get_logger
+from app.models.wrappers.base_wrapper import BaseFusionWrapper
+
+logger = get_logger(__name__)
+
+
+class DummyMajorityFusionWrapper(BaseFusionWrapper):
+    """
+    Wrapper for dummy majority vote fusion models.
+    
+    These models are hosted on Hugging Face and contain a fusion.py
+    with a predict() function that performs majority voting on submodel outputs.
+    """
+    
+    def __init__(
+        self,
+        repo_id: str,
+        config: Dict[str, Any],
+        local_path: str
+    ):
+        """
+        Initialize the wrapper.
+        
+        Args:
+            repo_id: Hugging Face repository ID (e.g., "DeepFakeDetector/fusion-majority-test")
+            config: Configuration from config.json
+            local_path: Local path where the model files are stored
+        """
+        super().__init__(repo_id, config, local_path)
+        self._submodel_repos: List[str] = config.get("submodels", [])
+        logger.info(f"Initialized DummyMajorityFusionWrapper for {repo_id}")
+        logger.info(f"Submodels: {self._submodel_repos}")
+    
+    @property
+    def submodel_repos(self) -> List[str]:
+        """Get list of submodel repository IDs."""
+        return self._submodel_repos
+    
+    def load(self) -> None:
+        """
+        Load the fusion predict function from the downloaded repository.
+        
+        Dynamically imports predict.py and extracts the predict function.
+        """
+        fusion_path = Path(self.local_path) / "predict.py"
+        
+        if not fusion_path.exists():
+            raise ConfigurationError(
+                message=f"predict.py not found in {self.local_path}",
+                details={"repo_id": self.repo_id, "expected_path": str(fusion_path)}
+            )
+        
+        try:
+            # Create a unique module name to avoid conflicts
+            module_name = f"hf_model_{self.name.replace('-', '_')}_fusion"
+            
+            # Load the module dynamically
+            spec = importlib.util.spec_from_file_location(module_name, fusion_path)
+            if spec is None or spec.loader is None:
+                raise ConfigurationError(
+                    message=f"Could not load spec for {fusion_path}",
+                    details={"repo_id": self.repo_id}
+                )
+            
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)
+            
+            # Get the predict function
+            if not hasattr(module, "predict"):
+                raise ConfigurationError(
+                    message=f"predict.py does not have a 'predict' function",
+                    details={"repo_id": self.repo_id}
+                )
+            
+            self._predict_fn = module.predict
+            logger.info(f"Loaded fusion predict function from {self.repo_id}")
+            
+        except ConfigurationError:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load fusion function from {self.repo_id}: {e}")
+            raise ConfigurationError(
+                message=f"Failed to load fusion model: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def predict(
+        self,
+        submodel_outputs: Dict[str, Dict[str, Any]],
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run fusion prediction on submodel outputs.
+        
+        Args:
+            submodel_outputs: Dictionary mapping submodel name to its prediction output
+            **kwargs: Additional arguments passed to the fusion function
+            
+        Returns:
+            Standardized prediction dictionary with:
+            - pred_int: 0 or 1
+            - pred: "real" or "fake"
+            - prob_fake: float (average of pred_ints)
+            - meta: dict
+        """
+        if self._predict_fn is None:
+            raise FusionError(
+                message="Fusion model not loaded",
+                details={"repo_id": self.repo_id}
+            )
+        
+        try:
+            # Call the actual fusion predict function from the HF repo
+            result = self._predict_fn(submodel_outputs=submodel_outputs, **kwargs)
+            
+            # Validate and standardize the output
+            standardized = self._standardize_output(result)
+            return standardized
+            
+        except FusionError:
+            raise
+        except Exception as e:
+            logger.error(f"Fusion prediction failed for {self.repo_id}: {e}")
+            raise FusionError(
+                message=f"Fusion prediction failed: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def _standardize_output(self, result: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Standardize the fusion output to ensure consistent format.
+        
+        Args:
+            result: Raw fusion output
+            
+        Returns:
+            Standardized dictionary
+        """
+        pred_int = result.get("pred_int", 0)
+        
+        # Ensure pred_int is 0 or 1
+        if pred_int not in (0, 1):
+            pred_int = 1 if pred_int > 0.5 else 0
+        
+        # Generate pred label if not present
+        pred = result.get("pred")
+        if pred is None:
+            pred = "fake" if pred_int == 1 else "real"
+        
+        # Generate prob_fake if not present
+        prob_fake = result.get("prob_fake")
+        if prob_fake is None:
+            prob_fake = float(pred_int)
+        
+        return {
+            "pred_int": pred_int,
+            "pred": pred,
+            "prob_fake": float(prob_fake),
+            "meta": result.get("meta", {})
+        }

app/models/wrappers/dummy_random_wrapper.py

@@ -0,0 +1,168 @@
+"""
+Wrapper for dummy random submodels.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from PIL import Image
+
+from app.core.errors import InferenceError, ConfigurationError
+from app.core.logging import get_logger
+from app.models.wrappers.base_wrapper import BaseSubmodelWrapper
+
+logger = get_logger(__name__)
+
+
+class DummyRandomWrapper(BaseSubmodelWrapper):
+    """
+    Wrapper for dummy random prediction models.
+    
+    These models are hosted on Hugging Face and contain a predict.py
+    with a predict() function that returns random predictions.
+    """
+    
+    def __init__(
+        self,
+        repo_id: str,
+        config: Dict[str, Any],
+        local_path: str
+    ):
+        """
+        Initialize the wrapper.
+        
+        Args:
+            repo_id: Hugging Face repository ID (e.g., "DeepFakeDetector/test-random-a")
+            config: Configuration from config.json
+            local_path: Local path where the model files are stored
+        """
+        super().__init__(repo_id, config, local_path)
+        logger.info(f"Initialized DummyRandomWrapper for {repo_id}")
+    
+    def load(self) -> None:
+        """
+        Load the predict function from the downloaded repository.
+        
+        Dynamically imports predict.py and extracts the predict function.
+        """
+        predict_path = Path(self.local_path) / "predict.py"
+        
+        if not predict_path.exists():
+            raise ConfigurationError(
+                message=f"predict.py not found in {self.local_path}",
+                details={"repo_id": self.repo_id, "expected_path": str(predict_path)}
+            )
+        
+        try:
+            # Create a unique module name to avoid conflicts
+            module_name = f"hf_model_{self.name.replace('-', '_')}_predict"
+            
+            # Load the module dynamically
+            spec = importlib.util.spec_from_file_location(module_name, predict_path)
+            if spec is None or spec.loader is None:
+                raise ConfigurationError(
+                    message=f"Could not load spec for {predict_path}",
+                    details={"repo_id": self.repo_id}
+                )
+            
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)
+            
+            # Get the predict function
+            if not hasattr(module, "predict"):
+                raise ConfigurationError(
+                    message=f"predict.py does not have a 'predict' function",
+                    details={"repo_id": self.repo_id}
+                )
+            
+            self._predict_fn = module.predict
+            logger.info(f"Loaded predict function from {self.repo_id}")
+            
+        except ConfigurationError:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load predict function from {self.repo_id}: {e}")
+            raise ConfigurationError(
+                message=f"Failed to load model: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def predict(
+        self,
+        image: Optional[Image.Image] = None,
+        image_bytes: Optional[bytes] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run prediction on an image.
+        
+        Args:
+            image: PIL Image object (optional for dummy model)
+            image_bytes: Raw image bytes (optional for dummy model)
+            **kwargs: Additional arguments passed to the model
+            
+        Returns:
+            Standardized prediction dictionary with:
+            - pred_int: 0 or 1
+            - pred: "real" or "fake"
+            - prob_fake: float
+            - meta: dict
+        """
+        if self._predict_fn is None:
+            raise InferenceError(
+                message="Model not loaded",
+                details={"repo_id": self.repo_id}
+            )
+        
+        try:
+            # Call the actual predict function from the HF repo
+            result = self._predict_fn(image_bytes=image_bytes, **kwargs)
+            
+            # Validate and standardize the output
+            standardized = self._standardize_output(result)
+            return standardized
+            
+        except InferenceError:
+            raise
+        except Exception as e:
+            logger.error(f"Prediction failed for {self.repo_id}: {e}")
+            raise InferenceError(
+                message=f"Prediction failed: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def _standardize_output(self, result: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Standardize the model output to ensure consistent format.
+        
+        Args:
+            result: Raw model output
+            
+        Returns:
+            Standardized dictionary
+        """
+        pred_int = result.get("pred_int", 0)
+        
+        # Ensure pred_int is 0 or 1
+        if pred_int not in (0, 1):
+            pred_int = 1 if pred_int > 0.5 else 0
+        
+        # Generate pred label if not present
+        pred = result.get("pred")
+        if pred is None:
+            pred = "fake" if pred_int == 1 else "real"
+        
+        # Generate prob_fake if not present
+        prob_fake = result.get("prob_fake")
+        if prob_fake is None:
+            prob_fake = float(pred_int)
+        
+        return {
+            "pred_int": pred_int,
+            "pred": pred,
+            "prob_fake": float(prob_fake),
+            "meta": result.get("meta", {})
+        }

app/models/wrappers/gradfield_cnn_wrapper.py

@@ -0,0 +1,401 @@
+"""
+Wrapper for Gradient Field CNN submodel.
+"""
+
+import json
+import math
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+from PIL import Image
+from torchvision import transforms
+
+from app.core.errors import InferenceError, ConfigurationError
+from app.core.logging import get_logger
+from app.models.wrappers.base_wrapper import BaseSubmodelWrapper
+from app.services.explainability import heatmap_to_base64, compute_focus_summary
+
+logger = get_logger(__name__)
+
+
+class CompactGradientNet(nn.Module):
+    """
+    CNN for gradient field classification with discriminative features.
+    
+    Input: Luminance image (1-channel)
+    Internal: Computes 6-channel gradient field [luminance, Gx, Gy, magnitude, angle, coherence]
+    Output: Logits and embeddings
+    """
+    
+    def __init__(self, depth=4, base_filters=32, dropout=0.3, embedding_dim=128):
+        super().__init__()
+        
+        # Sobel kernels
+        sobel_x = torch.tensor([[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]],
+                               dtype=torch.float32).view(1, 1, 3, 3)
+        sobel_y = torch.tensor([[-1, -2, -1], [0, 0, 0], [1, 2, 1]],
+                               dtype=torch.float32).view(1, 1, 3, 3)
+        self.register_buffer('sobel_x', sobel_x)
+        self.register_buffer('sobel_y', sobel_y)
+        
+        # Gaussian kernel for structure tensor smoothing
+        gaussian = torch.tensor([[1, 4, 6, 4, 1], [4, 16, 24, 16, 4],
+                                 [6, 24, 36, 24, 6], [4, 16, 24, 16, 4],
+                                 [1, 4, 6, 4, 1]], dtype=torch.float32) / 256.0
+        self.register_buffer('gaussian', gaussian.view(1, 1, 5, 5))
+        
+        # Input normalization and channel mixing
+        self.input_norm = nn.BatchNorm2d(6)
+        self.channel_mix = nn.Sequential(
+            nn.Conv2d(6, 6, kernel_size=1),
+            nn.ReLU()
+        )
+        
+        # CNN layers
+        layers = []
+        in_ch = 6
+        for i in range(depth):
+            out_ch = base_filters * (2**i)
+            layers.extend([
+                nn.Conv2d(in_ch, out_ch, kernel_size=3, padding=1),
+                nn.BatchNorm2d(out_ch),
+                nn.ReLU(),
+                nn.MaxPool2d(2)
+            ])
+            if dropout > 0:
+                layers.append(nn.Dropout2d(dropout))
+            in_ch = out_ch
+        
+        self.cnn = nn.Sequential(*layers)
+        self.global_pool = nn.AdaptiveAvgPool2d(1)
+        self.embedding = nn.Linear(out_ch, embedding_dim)
+        self.classifier = nn.Linear(embedding_dim, 1)
+    
+    def compute_gradient_field(self, luminance):
+        """Compute 6-channel gradient field on GPU (includes luminance)."""
+        G_x = F.conv2d(luminance, self.sobel_x, padding=1)
+        G_y = F.conv2d(luminance, self.sobel_y, padding=1)
+        
+        magnitude = torch.sqrt(G_x**2 + G_y**2 + 1e-8)
+        angle = torch.atan2(G_y, G_x) / math.pi
+        
+        # Structure tensor for coherence
+        Gxx, Gxy, Gyy = G_x * G_x, G_x * G_y, G_y * G_y
+        Sxx = F.conv2d(Gxx, self.gaussian, padding=2)
+        Sxy = F.conv2d(Gxy, self.gaussian, padding=2)
+        Syy = F.conv2d(Gyy, self.gaussian, padding=2)
+        
+        trace = Sxx + Syy
+        det_term = torch.sqrt((Sxx - Syy)**2 + 4 * Sxy**2 + 1e-8)
+        lambda1, lambda2 = 0.5 * (trace + det_term), 0.5 * (trace - det_term)
+        coherence = ((lambda1 - lambda2) / (lambda1 + lambda2 + 1e-8))**2
+        
+        magnitude_scaled = torch.log1p(magnitude * 10)
+        
+        return torch.cat([luminance, G_x, G_y, magnitude_scaled, angle, coherence], dim=1)
+    
+    def forward(self, luminance):
+        x = self.compute_gradient_field(luminance)
+        x = self.input_norm(x)
+        x = self.channel_mix(x)
+        x = self.cnn(x)
+        x = self.global_pool(x).flatten(1)
+        emb = self.embedding(x)
+        logit = self.classifier(emb)
+        return logit.squeeze(1), emb
+
+
+class GradfieldCNNWrapper(BaseSubmodelWrapper):
+    """
+    Wrapper for Gradient Field CNN model.
+    
+    Model expects 256x256 luminance images.
+    Internally computes Sobel gradients and other discriminative features.
+    """
+    
+    # BT.709 luminance coefficients
+    R_COEFF = 0.2126
+    G_COEFF = 0.7152
+    B_COEFF = 0.0722
+    
+    def __init__(
+        self,
+        repo_id: str,
+        config: Dict[str, Any],
+        local_path: str
+    ):
+        super().__init__(repo_id, config, local_path)
+        self._model: Optional[nn.Module] = None
+        self._resize: Optional[transforms.Resize] = None
+        self._device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        self._threshold = config.get("threshold", 0.5)
+        logger.info(f"Initialized GradfieldCNNWrapper for {repo_id}")
+    
+    def load(self) -> None:
+        """Load the Gradient Field CNN model with trained weights."""
+        # Try different weight file names
+        weights_path = None
+        for fname in ["gradient_field_cnn_v3_finetuned.pth", "gradient_field_cnn_v2.pth", "weights.pt", "model.pth"]:
+            candidate = Path(self.local_path) / fname
+            if candidate.exists():
+                weights_path = candidate
+                break
+        
+        preprocess_path = Path(self.local_path) / "preprocess.json"
+        
+        if weights_path is None:
+            raise ConfigurationError(
+                message=f"No weights file found in {self.local_path}",
+                details={"repo_id": self.repo_id}
+            )
+        
+        try:
+            # Load preprocessing config
+            preprocess_config = {}
+            if preprocess_path.exists():
+                with open(preprocess_path, "r") as f:
+                    preprocess_config = json.load(f)
+            
+            # Get input size (default 256 for gradient field)
+            input_size = preprocess_config.get("input_size", 256)
+            if isinstance(input_size, list):
+                input_size = input_size[0]
+            
+            self._resize = transforms.Resize((input_size, input_size))
+            
+            # Get model parameters from config
+            model_params = self.config.get("model_parameters", {})
+            depth = model_params.get("depth", 4)
+            base_filters = model_params.get("base_filters", 32)
+            dropout = model_params.get("dropout", 0.3)
+            embedding_dim = model_params.get("embedding_dim", 128)
+            
+            # Create model
+            self._model = CompactGradientNet(
+                depth=depth,
+                base_filters=base_filters,
+                dropout=dropout,
+                embedding_dim=embedding_dim
+            )
+            
+            # Load trained weights
+            # Note: weights_only=False needed because checkpoint contains numpy types
+            state_dict = torch.load(weights_path, map_location=self._device, weights_only=False)
+            
+            # Handle different checkpoint formats
+            if isinstance(state_dict, dict):
+                if "model_state_dict" in state_dict:
+                    state_dict = state_dict["model_state_dict"]
+                elif "state_dict" in state_dict:
+                    state_dict = state_dict["state_dict"]
+                elif "model" in state_dict:
+                    state_dict = state_dict["model"]
+            
+            self._model.load_state_dict(state_dict)
+            self._model.to(self._device)
+            self._model.eval()
+            
+            # Mark as loaded
+            self._predict_fn = self._run_inference
+            logger.info(f"Loaded Gradient Field CNN model from {self.repo_id}")
+            
+        except ConfigurationError:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load Gradient Field CNN model: {e}")
+            raise ConfigurationError(
+                message=f"Failed to load model: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def _rgb_to_luminance(self, img_tensor: torch.Tensor) -> torch.Tensor:
+        """
+        Convert RGB tensor to luminance using BT.709 coefficients.
+        
+        Args:
+            img_tensor: RGB tensor of shape (3, H, W) with values in [0, 1]
+            
+        Returns:
+            Luminance tensor of shape (1, H, W)
+        """
+        luminance = (
+            self.R_COEFF * img_tensor[0] +
+            self.G_COEFF * img_tensor[1] +
+            self.B_COEFF * img_tensor[2]
+        )
+        return luminance.unsqueeze(0)
+    
+    def _run_inference(
+        self,
+        luminance_tensor: torch.Tensor,
+        explain: bool = False
+    ) -> Dict[str, Any]:
+        """Run model inference on preprocessed luminance tensor."""
+        heatmap = None
+        
+        if explain:
+            # Custom GradCAM implementation for single-logit binary model
+            # Using absolute CAM values to capture both positive and negative contributions
+            # Target the last Conv2d layer (cnn[-5])
+            target_layer = self._model.cnn[-5]
+            
+            activations = None
+            gradients = None
+            
+            def forward_hook(module, input, output):
+                nonlocal activations
+                activations = output.detach()
+            
+            def backward_hook(module, grad_input, grad_output):
+                nonlocal gradients
+                gradients = grad_output[0].detach()
+            
+            h_fwd = target_layer.register_forward_hook(forward_hook)
+            h_bwd = target_layer.register_full_backward_hook(backward_hook)
+            
+            try:
+                # Forward pass with gradients
+                input_tensor = luminance_tensor.clone().requires_grad_(True)
+                logits, embedding = self._model(input_tensor)
+                prob_fake = torch.sigmoid(logits).item()
+                pred_int = 1 if prob_fake >= self._threshold else 0
+                
+                # Backward pass
+                self._model.zero_grad()
+                logits.backward()
+                
+                if gradients is not None and activations is not None:
+                    # Compute Grad-CAM weights (global average pooled gradients)
+                    weights = gradients.mean(dim=(2, 3), keepdim=True)  # [1, C, 1, 1]
+                    
+                    # Weighted combination of activation maps
+                    cam = (weights * activations).sum(dim=1, keepdim=True)  # [1, 1, H, W]
+                    
+                    # Use absolute values instead of ReLU to capture all contributions
+                    # This is important for models where negative gradients carry meaning
+                    cam = torch.abs(cam)
+                    
+                    # Normalize to [0, 1]
+                    cam = cam - cam.min()
+                    cam_max = cam.max()
+                    if cam_max > 0:
+                        cam = cam / cam_max
+                    
+                    # Resize to output size (256x256)
+                    cam = F.interpolate(
+                        cam,
+                        size=(256, 256),
+                        mode='bilinear',
+                        align_corners=False
+                    )
+                    
+                    heatmap = cam.squeeze().cpu().numpy()
+                else:
+                    logger.warning("GradCAM: gradients or activations not captured")
+                    heatmap = np.zeros((256, 256), dtype=np.float32)
+                    
+            finally:
+                h_fwd.remove()
+                h_bwd.remove()
+        else:
+            with torch.no_grad():
+                logits, embedding = self._model(luminance_tensor)
+                prob_fake = torch.sigmoid(logits).item()
+                pred_int = 1 if prob_fake >= self._threshold else 0
+        
+        result = {
+            "logits": logits.detach().cpu().numpy().tolist() if hasattr(logits, 'detach') else logits.cpu().numpy().tolist(),
+            "prob_fake": prob_fake,
+            "pred_int": pred_int,
+            "embedding": embedding.detach().cpu().numpy().tolist() if explain else embedding.cpu().numpy().tolist()
+        }
+        
+        if heatmap is not None:
+            result["heatmap"] = heatmap
+        
+        return result
+    
+    def predict(
+        self,
+        image: Optional[Image.Image] = None,
+        image_bytes: Optional[bytes] = None,
+        explain: bool = False,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run prediction on an image.
+        
+        Args:
+            image: PIL Image object
+            image_bytes: Raw image bytes (will be converted to PIL Image)
+            explain: If True, compute GradCAM heatmap
+            
+        Returns:
+            Standardized prediction dictionary with optional heatmap
+        """
+        if self._model is None or self._resize is None:
+            raise InferenceError(
+                message="Model not loaded",
+                details={"repo_id": self.repo_id}
+            )
+        
+        try:
+            # Convert bytes to PIL Image if needed
+            if image is None and image_bytes is not None:
+                import io
+                image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+            elif image is not None:
+                image = image.convert("RGB")
+            else:
+                raise InferenceError(
+                    message="No image provided",
+                    details={"repo_id": self.repo_id}
+                )
+            
+            # Resize
+            image = self._resize(image)
+            
+            # Convert to tensor
+            img_tensor = transforms.functional.to_tensor(image)
+            
+            # Convert to luminance
+            luminance = self._rgb_to_luminance(img_tensor)
+            luminance = luminance.unsqueeze(0).to(self._device)  # Add batch dim
+            
+            # Run inference
+            result = self._run_inference(luminance, explain=explain)
+            
+            # Standardize output
+            labels = self.config.get("labels", {"0": "real", "1": "fake"})
+            pred_int = result["pred_int"]
+            
+            output = {
+                "pred_int": pred_int,
+                "pred": labels.get(str(pred_int), "unknown"),
+                "prob_fake": result["prob_fake"],
+                "meta": {
+                    "model": self.name,
+                    "threshold": self._threshold
+                }
+            }
+            
+            # Add heatmap if requested
+            if explain and "heatmap" in result:
+                heatmap = result["heatmap"]
+                output["heatmap_base64"] = heatmap_to_base64(heatmap)
+                output["explainability_type"] = "grad_cam"
+                output["focus_summary"] = compute_focus_summary(heatmap) + " (edge-based analysis)"
+            
+            return output
+            
+        except InferenceError:
+            raise
+        except Exception as e:
+            logger.error(f"Prediction failed for {self.repo_id}: {e}")
+            raise InferenceError(
+                message=f"Prediction failed: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )

app/models/wrappers/logreg_fusion_wrapper.py

@@ -0,0 +1,161 @@
+"""
+Wrapper for logistic regression stacking fusion model.
+"""
+
+import pickle
+from pathlib import Path
+from typing import Any, Dict, List
+
+import joblib
+import numpy as np
+
+from app.core.errors import FusionError, ConfigurationError
+from app.core.logging import get_logger
+from app.models.wrappers.base_wrapper import BaseFusionWrapper
+
+logger = get_logger(__name__)
+
+
+class LogRegFusionWrapper(BaseFusionWrapper):
+    """
+    Wrapper for probability stacking fusion with logistic regression.
+    
+    This fusion model takes probability outputs from submodels,
+    stacks them into a feature vector, and runs them through a
+    trained logistic regression classifier.
+    """
+    
+    def __init__(
+        self,
+        repo_id: str,
+        config: Dict[str, Any],
+        local_path: str
+    ):
+        """
+        Initialize the wrapper.
+        
+        Args:
+            repo_id: Hugging Face repository ID
+            config: Configuration from config.json
+            local_path: Local path where the model files are stored
+        """
+        super().__init__(repo_id, config, local_path)
+        self._model = None
+        self._submodel_order: List[str] = config.get("submodel_order", [])
+        self._threshold: float = config.get("threshold", 0.5)
+        logger.info(f"Initialized LogRegFusionWrapper for {repo_id}")
+        logger.info(f"Submodel order: {self._submodel_order}")
+    
+    @property
+    def submodel_repos(self) -> List[str]:
+        """Get list of submodel repository IDs."""
+        return self.config.get("submodels", [])
+    
+    def load(self) -> None:
+        """
+        Load the logistic regression model from the downloaded repository.
+        
+        Loads fusion_logreg.pkl using joblib (sklearn models are saved with joblib).
+        """
+        model_path = Path(self.local_path) / "fusion_logreg.pkl"
+        
+        if not model_path.exists():
+            raise ConfigurationError(
+                message=f"fusion_logreg.pkl not found in {self.local_path}",
+                details={"repo_id": self.repo_id, "expected_path": str(model_path)}
+            )
+        
+        try:
+            # Use joblib for sklearn models instead of pickle
+            self._model = joblib.load(model_path)
+            logger.info(f"Loaded logistic regression fusion model from {self.repo_id}")
+            
+        except Exception as e:
+            logger.error(f"Failed to load fusion model from {self.repo_id}: {e}")
+            raise ConfigurationError(
+                message=f"Failed to load fusion model: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def predict(
+        self,
+        submodel_outputs: Dict[str, Dict[str, Any]],
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run fusion prediction on submodel outputs.
+        
+        Stacks submodel probabilities in the correct order and runs
+        through the logistic regression classifier.
+        
+        Args:
+            submodel_outputs: Dictionary mapping submodel name to its prediction output
+                Each output must contain "prob_fake" key
+            **kwargs: Additional arguments (unused)
+            
+        Returns:
+            Standardized prediction dictionary with:
+            - pred_int: 0 or 1
+            - pred: "real" or "fake"
+            - prob_fake: float probability of being fake
+            - meta: dict with submodel probabilities
+        """
+        if self._model is None:
+            raise FusionError(
+                message="Fusion model not loaded",
+                details={"repo_id": self.repo_id}
+            )
+        
+        try:
+            # Stack submodel probabilities in the correct order
+            probs = []
+            for submodel_name in self._submodel_order:
+                if submodel_name not in submodel_outputs:
+                    raise FusionError(
+                        message=f"Missing output from submodel: {submodel_name}",
+                        details={
+                            "repo_id": self.repo_id,
+                            "missing_submodel": submodel_name,
+                            "available_submodels": list(submodel_outputs.keys())
+                        }
+                    )
+                
+                output = submodel_outputs[submodel_name]
+                if "prob_fake" not in output:
+                    raise FusionError(
+                        message=f"Submodel output missing 'prob_fake': {submodel_name}",
+                        details={
+                            "repo_id": self.repo_id,
+                            "submodel": submodel_name,
+                            "output_keys": list(output.keys())
+                        }
+                    )
+                
+                probs.append(output["prob_fake"])
+            
+            # Convert to numpy array and reshape for sklearn
+            X = np.array(probs).reshape(1, -1)
+            
+            # Get prediction and probability
+            prob_fake = float(self._model.predict_proba(X)[0, 1])
+            pred_int = 1 if prob_fake >= self._threshold else 0
+            pred = "fake" if pred_int == 1 else "real"
+            
+            return {
+                "pred_int": pred_int,
+                "pred": pred,
+                "prob_fake": prob_fake,
+                "meta": {
+                    "submodel_probs": dict(zip(self._submodel_order, probs)),
+                    "threshold": self._threshold
+                }
+            }
+            
+        except FusionError:
+            raise
+        except Exception as e:
+            logger.error(f"Fusion prediction failed for {self.repo_id}: {e}")
+            raise FusionError(
+                message=f"Fusion prediction failed: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )

app/models/wrappers/vit_base_wrapper.py

@@ -0,0 +1,331 @@
+"""
+Wrapper for ViT Base submodel.
+"""
+
+import json
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from PIL import Image
+from torchvision import transforms
+
+try:
+    import timm
+    TIMM_AVAILABLE = True
+except ImportError:
+    TIMM_AVAILABLE = False
+
+from app.core.errors import InferenceError, ConfigurationError
+from app.core.logging import get_logger
+from app.models.wrappers.base_wrapper import BaseSubmodelWrapper
+from app.services.explainability import attention_rollout, heatmap_to_base64, compute_focus_summary
+
+logger = get_logger(__name__)
+
+
+class ViTWithMLPHead(nn.Module):
+    """
+    ViT model wrapper matching the training checkpoint format.
+    
+    The checkpoint was saved with:
+    - self.vit = timm ViT backbone (num_classes=0)
+    - self.fc1 = Linear(768, hidden)
+    - self.fc2 = Linear(hidden, num_classes)
+    """
+    
+    def __init__(self, arch: str = "vit_base_patch16_224", num_classes: int = 2, hidden_dim: int = 512):
+        super().__init__()
+        # Create backbone without classification head
+        self.vit = timm.create_model(arch, pretrained=False, num_classes=0)
+        embed_dim = self.vit.embed_dim  # 768 for ViT-Base
+        self.fc1 = nn.Linear(embed_dim, hidden_dim)
+        self.fc2 = nn.Linear(hidden_dim, num_classes)
+    
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        features = self.vit(x)  # [B, embed_dim]
+        x = F.relu(self.fc1(features))
+        logits = self.fc2(x)
+        return logits
+
+
+class ViTBaseWrapper(BaseSubmodelWrapper):
+    """
+    Wrapper for ViT Base model (Vision Transformer).
+    
+    Model expects 224x224 RGB images with ImageNet normalization.
+    """
+    
+    def __init__(
+        self,
+        repo_id: str,
+        config: Dict[str, Any],
+        local_path: str
+    ):
+        super().__init__(repo_id, config, local_path)
+        self._model: Optional[nn.Module] = None
+        self._transform: Optional[transforms.Compose] = None
+        self._device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        self._threshold = config.get("threshold", 0.5)
+        logger.info(f"Initialized ViTBaseWrapper for {repo_id}")
+    
+    def load(self) -> None:
+        """Load the ViT Base model with trained weights."""
+        if not TIMM_AVAILABLE:
+            raise ConfigurationError(
+                message="timm package not installed. Run: pip install timm",
+                details={"repo_id": self.repo_id}
+            )
+        
+        weights_path = Path(self.local_path) / "deepfake_vit_finetuned_wildfake.pth"
+        preprocess_path = Path(self.local_path) / "preprocess.json"
+        
+        if not weights_path.exists():
+            raise ConfigurationError(
+                message=f"deepfake_vit_finetuned_wildfake.pth not found in {self.local_path}",
+                details={"repo_id": self.repo_id, "expected_path": str(weights_path)}
+            )
+        
+        try:
+            # Load preprocessing config
+            preprocess_config = {}
+            if preprocess_path.exists():
+                with open(preprocess_path, "r") as f:
+                    preprocess_config = json.load(f)
+            
+            # Build transform pipeline
+            input_size = preprocess_config.get("input_size", 224)
+            if isinstance(input_size, list):
+                input_size = input_size[0]
+            
+            normalize_config = preprocess_config.get("normalize", {})
+            mean = normalize_config.get("mean", [0.485, 0.456, 0.406])
+            std = normalize_config.get("std", [0.229, 0.224, 0.225])
+            
+            # Use bicubic interpolation as specified
+            interpolation = preprocess_config.get("interpolation", "bicubic")
+            interp_mode = transforms.InterpolationMode.BICUBIC if interpolation == "bicubic" else transforms.InterpolationMode.BILINEAR
+            
+            self._transform = transforms.Compose([
+                transforms.Resize((input_size, input_size), interpolation=interp_mode),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std)
+            ])
+            
+            # Create model architecture matching the training checkpoint format
+            arch = self.config.get("arch", "vit_base_patch16_224")
+            num_classes = self.config.get("num_classes", 2)
+            # MLP hidden dim is 512 per training notebook (fc1: 768->512, fc2: 512->2)
+            # Note: config.hidden_dim (768) is ViT embedding dim, not MLP hidden dim
+            mlp_hidden_dim = self.config.get("mlp_hidden_dim", 512)
+            
+            # Use custom wrapper that matches checkpoint structure (vit.* + fc1/fc2)
+            self._model = ViTWithMLPHead(arch=arch, num_classes=num_classes, hidden_dim=mlp_hidden_dim)
+            
+            # Load trained weights
+            checkpoint = torch.load(weights_path, map_location=self._device, weights_only=False)
+            
+            # Handle training checkpoint format (has "model", "optimizer_state", "epoch" keys)
+            if isinstance(checkpoint, dict) and "model" in checkpoint:
+                state_dict = checkpoint["model"]
+            else:
+                state_dict = checkpoint
+            
+            self._model.load_state_dict(state_dict)
+            self._model.to(self._device)
+            self._model.eval()
+            
+            # Mark as loaded
+            self._predict_fn = self._run_inference
+            logger.info(f"Loaded ViT Base model from {self.repo_id}")
+            
+        except ConfigurationError:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load ViT Base model: {e}")
+            raise ConfigurationError(
+                message=f"Failed to load model: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )
+    
+    def _run_inference(
+        self,
+        image_tensor: torch.Tensor,
+        explain: bool = False
+    ) -> Dict[str, Any]:
+        """Run model inference on preprocessed tensor."""
+        heatmap = None
+        
+        if explain:
+            # Collect attention weights from all blocks
+            attentions: List[torch.Tensor] = []
+            handles = []
+            
+            def get_attention_hook(module, input, output):
+                # For timm ViT, the attention forward returns (attn @ v)
+                # We need to hook into the softmax to get raw attention weights
+                # Alternative: access module's internal attn variable if available
+                pass
+            
+            # Hook into attention modules to capture weights
+            # timm ViT blocks structure: blocks[i].attn
+            # We'll use a forward hook that computes attention manually
+            def create_attn_hook():
+                stored_attn = []
+                
+                def hook(module, inputs, outputs):
+                    # Get q, k from the module's forward computation
+                    # inputs[0] is x of shape [B, N, C]
+                    x = inputs[0]
+                    B, N, C = x.shape
+                    
+                    # Access the attention module's parameters
+                    qkv = module.qkv(x)  # [B, N, 3*dim]
+                    qkv = qkv.reshape(B, N, 3, module.num_heads, C // module.num_heads)
+                    qkv = qkv.permute(2, 0, 3, 1, 4)  # [3, B, heads, N, dim_head]
+                    q, k, v = qkv[0], qkv[1], qkv[2]
+                    
+                    # Compute attention weights
+                    scale = (C // module.num_heads) ** -0.5
+                    attn = (q @ k.transpose(-2, -1)) * scale
+                    attn = attn.softmax(dim=-1)  # [B, heads, N, N]
+                    
+                    # Average over heads
+                    attn_avg = attn.mean(dim=1)  # [B, N, N]
+                    stored_attn.append(attn_avg.detach())
+                
+                return hook, stored_attn
+            
+            all_stored_attns = []
+            for block in self._model.vit.blocks:
+                hook_fn, stored = create_attn_hook()
+                all_stored_attns.append(stored)
+                handle = block.attn.register_forward_hook(hook_fn)
+                handles.append(handle)
+            
+            try:
+                with torch.no_grad():
+                    logits = self._model(image_tensor)
+                    probs = F.softmax(logits, dim=1)
+                    prob_fake = probs[0, 1].item()
+                    pred_int = 1 if prob_fake >= self._threshold else 0
+                
+                # Get attention from hooks
+                attention_list = [stored[0] for stored in all_stored_attns if len(stored) > 0]
+                
+                if attention_list:
+                    # Stack: [num_layers, B, N, N]
+                    attention_stack = torch.stack(attention_list, dim=0)
+                    # Compute rollout - returns (grid_size, grid_size) heatmap
+                    attention_map = attention_rollout(
+                        attention_stack[:, 0],  # [num_layers, N, N]
+                        head_fusion="mean",  # Already averaged
+                        discard_ratio=0.0,
+                        num_prefix_tokens=1  # ViT has 1 CLS token
+                    )  # Returns (14, 14) for ViT-Base
+                    
+                    # Resize to image size
+                    from PIL import Image as PILImage
+                    heatmap_img = PILImage.fromarray(
+                        (attention_map * 255).astype(np.uint8)
+                    ).resize((224, 224), PILImage.BILINEAR)
+                    heatmap = np.array(heatmap_img).astype(np.float32) / 255.0
+                    
+            finally:
+                for handle in handles:
+                    handle.remove()
+        else:
+            with torch.no_grad():
+                logits = self._model(image_tensor)
+                probs = F.softmax(logits, dim=1)
+                prob_fake = probs[0, 1].item()
+                pred_int = 1 if prob_fake >= self._threshold else 0
+        
+        result = {
+            "logits": logits[0].cpu().numpy().tolist(),
+            "prob_fake": prob_fake,
+            "pred_int": pred_int
+        }
+        
+        if heatmap is not None:
+            result["heatmap"] = heatmap
+        
+        return result
+    
+    def predict(
+        self,
+        image: Optional[Image.Image] = None,
+        image_bytes: Optional[bytes] = None,
+        explain: bool = False,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Run prediction on an image.
+        
+        Args:
+            image: PIL Image object
+            image_bytes: Raw image bytes (will be converted to PIL Image)
+            explain: If True, compute attention rollout heatmap
+            
+        Returns:
+            Standardized prediction dictionary with optional heatmap
+        """
+        if self._model is None or self._transform is None:
+            raise InferenceError(
+                message="Model not loaded",
+                details={"repo_id": self.repo_id}
+            )
+        
+        try:
+            # Convert bytes to PIL Image if needed
+            if image is None and image_bytes is not None:
+                import io
+                image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+            elif image is not None:
+                image = image.convert("RGB")
+            else:
+                raise InferenceError(
+                    message="No image provided",
+                    details={"repo_id": self.repo_id}
+                )
+            
+            # Preprocess
+            image_tensor = self._transform(image).unsqueeze(0).to(self._device)
+            
+            # Run inference
+            result = self._run_inference(image_tensor, explain=explain)
+            
+            # Standardize output
+            labels = self.config.get("labels", {"0": "real", "1": "fake"})
+            pred_int = result["pred_int"]
+            
+            output = {
+                "pred_int": pred_int,
+                "pred": labels.get(str(pred_int), "unknown"),
+                "prob_fake": result["prob_fake"],
+                "meta": {
+                    "model": self.name,
+                    "threshold": self._threshold,
+                    "logits": result["logits"]
+                }
+            }
+            
+            # Add heatmap if requested
+            if explain and "heatmap" in result:
+                heatmap = result["heatmap"]
+                output["heatmap_base64"] = heatmap_to_base64(heatmap)
+                output["explainability_type"] = "attention_rollout"
+                output["focus_summary"] = compute_focus_summary(heatmap)
+            
+            return output
+            
+        except InferenceError:
+            raise
+        except Exception as e:
+            logger.error(f"Prediction failed for {self.repo_id}: {e}")
+            raise InferenceError(
+                message=f"Prediction failed: {e}",
+                details={"repo_id": self.repo_id, "error": str(e)}
+            )

app/schemas/__init__.py

@@ -0,0 +1 @@
+# Schemas module

app/schemas/models.py

@@ -0,0 +1,53 @@
+"""
+Pydantic schemas for model-related endpoints.
+"""
+
+from typing import Dict, List, Literal, Optional, Any
+from pydantic import BaseModel, Field
+
+
+class ModelInfo(BaseModel):
+    """Information about a loaded model."""
+    
+    repo_id: str = Field(..., description="Hugging Face repository ID")
+    name: str = Field(..., description="Short name of the model")
+    model_type: Literal["submodel", "fusion"] = Field(
+        ...,
+        description="Type of model"
+    )
+    config: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Model configuration from config.json"
+    )
+
+
+class ModelsListResponse(BaseModel):
+    """Response schema for listing models."""
+    
+    fusion: Optional[ModelInfo] = Field(
+        None,
+        description="Fusion model information"
+    )
+    submodels: List[ModelInfo] = Field(
+        default_factory=list,
+        description="List of loaded submodels"
+    )
+    total_count: int = Field(..., description="Total number of loaded models")
+
+
+class HealthResponse(BaseModel):
+    """Response schema for health check."""
+    
+    status: Literal["ok", "error"] = Field(..., description="Health status")
+
+
+class ReadyResponse(BaseModel):
+    """Response schema for readiness check."""
+    
+    status: Literal["ready", "not_ready"] = Field(..., description="Readiness status")
+    models_loaded: bool = Field(..., description="Whether models are loaded")
+    fusion_repo: Optional[str] = Field(None, description="Fusion repository ID")
+    submodels: List[str] = Field(
+        default_factory=list,
+        description="List of loaded submodel repository IDs"
+    )