README.md

metadata

title: DeepFake Detector API
emoji: 🎭
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

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)

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

API docs:

• http://localhost:8000/docs
• http://localhost:8000/redoc

Environment Configuration

Use backend/.env.example as the source of truth.

Common runtime variables:

• HF_FUSION_REPO_ID (default: DeepFakeDetector/fusion-logreg-final)
• HF_CACHE_DIR (default: /app/.hf_cache, auto-switched to /data/.hf_cache on Spaces when mounted)
• HF_HOME (default: /app/.cache/huggingface, auto-switched to /data/.cache/huggingface on Spaces)
• HF_PERSISTENT_CACHE (default: true)
• HF_PERSISTENT_CACHE_ROOT (default: /data)
• 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 locally, 7860 in Space by default)
• CORS_ORIGINS (comma-separated origins)
• ENABLE_DEBUG, LOG_LEVEL

HF Spaces deploy variables (used by backend/deploy-to-hf.sh):

• HF_SPACE_URL
• HF_SPACE_WEB_URL
• HF_SPACE_APP_URL
• HF_DEPLOY_DIR
• INSTALL_OPTIONAL_DEPS (true/false, default false)
• HF_BUCKET_SYNC_ON_DEPLOY (default: true)

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:

curl -X POST "http://localhost:8000/predict" \
  -F "image=@/path/to/image.jpg"

Docker

Build and run locally:

docker build -t deepfake-detector-api .
docker run -p 7860:7860 deepfake-detector-api

Image defaults:

• Installs requirements-runtime.txt (inference + explainability + LLM)
• Skips build-time model prefetch (first boot fills /data cache)
• POST /predict defaults to explain=true

Enable optional test dependencies at build time:

docker build --build-arg INSTALL_OPTIONAL_DEPS=true -t deepfake-detector-api .

Deploy to Hugging Face Spaces

Recommended path is the Bash deploy script.

1. Configure backend/.env from backend/.env.example
2. Ensure HF_SPACE_URL and related deploy variables are set
3. Run from the repo root:

bash ./backend/deploy-to-hf.sh

The script will:

• sync backend/data to your HF bucket first (when configured)
• install Hugging Face CLI if needed
• prompt/authenticate with HF (hf auth login) when required
• clone Space repo into a separate temp deploy directory
• copy backend files as-is (single Dockerfile setup)
• commit and push to the HF Space

If bucket sync should be skipped for a deploy, set:

• HF_BUCKET_SYNC_ON_DEPLOY=false

After deploy, set Space secrets in Hugging Face:

• GOOGLE_API_KEY (if using explanation endpoints)
• CORS_ORIGINS (frontend domains)

Persistent Bucket Cache on Spaces

The backend now prefers persistent cache paths when a bucket is mounted read/write at /data.

Recommended bucket mount settings in Space:

• Mount path: /data
• Access mode: Read & Write

At runtime, start.sh will auto-select:

• HF_HOME=/data/.cache/huggingface
• HF_CACHE_DIR=/data/.hf_cache

If /data is unavailable, it falls back to /app/.cache/huggingface and /app/.hf_cache.

Bucket Upload / Sync (Reproducible)

Set these optional values in backend/.env:

• HF_BUCKET_URI=hf://buckets/lukhsaankumar/DeepFakeDetectorBackend-storage
• HF_BUCKET_LOCAL_DIR=./data
• HF_BUCKET_DELETE=false
• HF_BUCKET_SYNC_ON_DEPLOY=true

Bash:

cd backend
chmod +x ./sync-bucket.sh
./sync-bucket.sh              # uses HF_BUCKET_LOCAL_DIR or ./data
./sync-bucket.sh ./data       # explicit local path

PowerShell:

cd backend
./sync-bucket.ps1             # uses HF_BUCKET_LOCAL_DIR or ./data
./sync-bucket.ps1 .\data      # explicit local path

Notes:

• Scripts require authenticated HF CLI (hf auth login).
• Set HF_BUCKET_DELETE=true to mirror local to remote (deletes remote files not present locally).

Deploy to Railway

• Set service root to backend
• Configure required env vars (CORS_ORIGINS, HF_FUSION_REPO_ID, HF_CACHE_DIR, PORT)
• Push to main branch to trigger deployment

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

backend/
├── app/
├── data/
├── tests/
├── Dockerfile
├── deploy-to-hf.sh
├── sync-bucket.sh
├── sync-bucket.ps1
├── requirements.txt
└── README.md

License

MIT