Deploy DeepFake Detector API - 2026-04-20 00:17:18

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 - Docker Image
+# Unified Dockerfile for local, Railway, and HF Spaces
+
+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 default app port
+EXPOSE 7860
+
+# Run the application (start.sh uses PORT env var)
+CMD ["./start.sh"]

README.md

@@ -1,182 +1,130 @@
----
-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**
+# DeepFake Detector Backend
+
+FastAPI backend for detecting AI-generated (deepfake) images using a multi-model fusion pipeline.
+
+## Features
+
+- Multi-model ensemble: CNN Transfer, ViT Base, DeiT Distilled, Gradient Field CNN
+- Fusion prediction: Logistic Regression and meta-classifier variants
+- Explainability: Grad-CAM and attention-based heatmaps
+- Optional Gemini-powered interpretation layer
+- Hugging Face Hub model download/caching
+
+## Prerequisites
+
+- Python 3.11+
+- pip
+
+## Quick Start (Local)
+docker run -p 7860:7860 deepfake-detector-api
+```bash
+cd backend
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows PowerShell: .\\venv\\Scripts\\Activate.ps1
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Configure env
+cp .env.example .env  # Windows PowerShell: Copy-Item .env.example .env
+
+# Run API
+uvicorn app.main:app --reload
+- copy backend files as-is (single `Dockerfile` setup)
+- `http://localhost:8000/redoc`
+
+## Environment Configuration
+
+Use [backend/.env.example](.env.example) as the source of truth.
+
+Common runtime variables:
+- `HF_FUSION_REPO_ID` (default: `DeepFakeDetector/fusion-logreg-final`)
+- `HF_CACHE_DIR` (default: `.hf_cache`)
+- `HF_TOKEN` (optional; required for private model repos or non-interactive HF auth)
+- `GOOGLE_API_KEY` (optional; required for Gemini explanations)
+- `HOST` (default: `0.0.0.0`)
+- `PORT` (default: `8000`)
+- `CORS_ORIGINS` (comma-separated origins)
+- `ENABLE_DEBUG`, `LOG_LEVEL`
+
+HF Spaces deploy variables (used by [backend/deploy-to-hf.sh](deploy-to-hf.sh)):
+
+- `HF_SPACE_URL`
+- `HF_SPACE_WEB_URL`
+- `HF_SPACE_APP_URL`
+- `HF_DEPLOY_DIR`
+
+## API Endpoints
+
+- `GET /health` - service health
+- `GET /ready` - readiness (includes model load state)
+- `GET /models` - loaded model metadata
+- `POST /predict` - real/fake prediction
+- `GET /docs` - Swagger UI
+
+Example:
+
+```bash
+curl -X POST "http://localhost:8000/predict" \
+  -F "image=@/path/to/image.jpg"
+```
+
+## Docker
+
+Build and run locally:
+
+```bash
+docker build -t deepfake-detector-api .
+docker run -p 8000:8000 deepfake-detector-api
+```
+
+## Deploy to Hugging Face Spaces
+
+Recommended path is the Bash deploy script:
+
+1. Configure [backend/.env](.env) from [backend/.env.example](.env.example)
+2. Ensure `HF_SPACE_URL` and related deploy variables are set
+3. Run from repo root:
+
+```bash
+bash ./deploy-to-hf.sh
+```
+
+The script will:
+
+- install Hugging Face CLI if needed
+- prompt/authenticate with HF (`hf auth login`) when required
+- clone Space repo into a separate temp deploy directory
+- commit and push to the HF Space
+
+After deploy, set Space secrets in Hugging Face:
+
+- `GOOGLE_API_KEY` (if using explanation endpoints)
+- `CORS_ORIGINS` (frontend domains)
+
+## Troubleshooting
+
+- Build fails: inspect Space/Railway logs first
+- HF auth fails: run `hf auth login` and/or set `HF_TOKEN` in `.env`
+- Model loading issues: verify fusion/submodel repo IDs and access
+- CORS issues: ensure frontend domains are in `CORS_ORIGINS`
+
+## Project Structure
+
+```text
+backend/
+├── app/
+├── tests/
+├── Dockerfile
+├── Dockerfile.huggingface
+├── deploy-to-hf.sh
+├── deploy-to-hf.ps1
+├── requirements.txt
+└── README.md
+```
+
+## License
+
+MIT