Deploy DeepFake Detector API - 2026-04-19 23:51:12

Dockerfile

@@ -1,47 +1,47 @@
-# 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
-
-# Switch to root to create cache directory and set permissions
-USER root
-RUN mkdir -p /app/.hf_cache && chown -R user:user /app/.hf_cache && chmod +x /app/start.sh
-
-# Switch back to user
-USER user
-
-# Expose HF Spaces port
-EXPOSE 7860
-
-# Run the application (start.sh already defaults to port 7860)
-CMD ["./start.sh"]
+# 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
+
+# Switch to root to create cache directory and set permissions
+USER root
+RUN mkdir -p /app/.hf_cache && chown -R user:user /app/.hf_cache && chmod +x /app/start.sh
+
+# Switch back to user
+USER user
+
+# Expose HF Spaces port
+EXPOSE 7860
+
+# Run the application (start.sh already defaults to port 7860)
+CMD ["./start.sh"]

Dockerfile.huggingface

@@ -1,47 +1,47 @@
-# 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
-
-# Switch to root to create cache directory and set permissions
-USER root
-RUN mkdir -p /app/.hf_cache && chown -R user:user /app/.hf_cache && chmod +x /app/start.sh
-
-# Switch back to user
-USER user
-
-# Expose HF Spaces port
-EXPOSE 7860
-
-# Run the application (start.sh already defaults to port 7860)
-CMD ["./start.sh"]
+# 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
+
+# Switch to root to create cache directory and set permissions
+USER root
+RUN mkdir -p /app/.hf_cache && chown -R user:user /app/.hf_cache && chmod +x /app/start.sh
+
+# Switch back to user
+USER user
+
+# Expose HF Spaces port
+EXPOSE 7860
+
+# Run the application (start.sh already defaults to port 7860)
+CMD ["./start.sh"]

README.md

@@ -1,182 +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**
+---
+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**

README_HF.md

@@ -1,182 +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**
+---
+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**