README.md

---
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)

```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
```

API docs:

- `http://localhost:8000/docs`
- `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: `/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](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:

```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 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:

```bash
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](.env) from [backend/.env.example](.env.example)
2. Ensure `HF_SPACE_URL` and related deploy variables are set
3. Run from the repo root:

```bash
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:

```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:

```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

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

## License

MIT