README.md

---
title: DEEPFYND Intelligence Plane
emoji: 🔍
colorFrom: green
colorTo: gray
sdk: gradio
app_file: app.py
pinned: false
license: mit
short_description: Explainable deepfake detection API for the DEEPFYND platform
sdk_version: 6.20.0
---

# DEEPFYND — Intelligence Plane

The analytical core of the DEEPFYND platform (MSc Digital Forensics & Cybersecurity).
Serves both a demo UI and the REST API consumed by the platform's web, Android and
Telegram channels.

## API contract

`POST /analyze`

```json
{ "file_url": "https://...", "media_type": "image|audio|video", "scan_id": "rec..." }
```

Response:

```json
{
  "verdict": "authentic|suspicious|likely_deepfake",
  "confidence": 87.4,
  "insights": "• ...",
  "heatmap_url": "https://.../heatmaps/rec....jpg",
  "file_hash": "sha256:...",
  "raw_scores": {}
}
```

`GET /health` — liveness check.
`GET /heatmaps/{name}` — serves generated explanation heatmaps.

## Layered architecture

- **Layer 1 — Media forensics:** EXIF/metadata inspection, generator-typical dimension checks.
- **Layer 2 — AI detection:** ViT image detector; wav2vec2 audio detector; frame-sampled video.
- **Layer 3 — Risk scoring:** three-band verdict (authentic / suspicious / likely deepfake) with confidence.
- **Layer 4 — Explainability:** gradient-based saliency heatmaps and plain-language reasons.

## Fail-honestly design

If media cannot be fetched, decoded, or analysed, the service returns an HTTP error.
It never fabricates a verdict. The upstream orchestration then records `Status=failed`
with a plain-language message, and users are told nothing was assessed.

## Configuration

Set in **Settings → Variables and secrets**:

- `SPACE_URL` = the public URL of this Space
  (e.g. `https://lericsg-deepfynd-intelligence.hf.space`).
  Required so that generated heatmap URLs are publicly addressable.

## Baseline models

This deployment uses publicly available pretrained detectors as a **baseline**:

- Image/video: `prithivMLmods/Deep-Fake-Detector-v2-Model`
- Audio: `Heem2/wav2vec2-based-Deepfake-Audio-Detection-V3`

Fine-tuning on Ghana-relevant data is scoped as future work.

## Disclaimer

Results are decision support, not proof. Verify important content with a professional fact-checker.