Initial commit

.dockerignore

@@ -0,0 +1,28 @@
+.git
+.gitignore
+.venv
+venv
+env
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.tmp
+tmp*
+pytest_tmp
+node_modules
+frontend/node_modules
+frontend/.next
+frontend/out
+.vscode
+.idea
+data
+models
+training
+tests
+*.log
+.env
+.env.local
+.env.*.local

.github/instructions/copilot-instructions.md

@@ -0,0 +1,61 @@
+# GitHub Copilot Instructions — GenAI-DeepDetect
+
+Read CLAUDE.md first. This file adds IDE-specific context.
+
+## Critical rules (never violate)
+
+- `src/types.py` is frozen. Never modify `EngineResult`, `DetectionResponse`, or `GeneratorLabel`.
+- `NUM_GENERATOR_CLASSES = 8` everywhere. If you see 5 anywhere, fix it to 8.
+- SSTGNN checkpoints load with `model.load_state_dict()` only. Never `torch.jit.load`.
+- Do not use `torch.jit.script` or `torch.jit.trace` on any PyG model.
+- Frontend: pages router only. No `app/` directory. No `src/` wrapper inside `frontend/`.
+- All Kaggle training cells call `scripts/train_image_baseline.py`. Not `training/phase1.../train.py` directly.
+- `min_detection_confidence=0.3` in all MediaPipe calls. Not 0.5.
+
+## Generator label index (memorise this)
+
+```
+0 = real            4 = dall_e
+1 = unknown_gan     5 = flux
+2 = stable_diffusion 6 = firefly
+3 = midjourney      7 = imagen
+```
+
+## Path conventions
+
+```
+src/              library code — no sys.exit(), logging only via logging module
+scripts/          Kaggle entrypoints — one file per task
+training/phase*/  per-phase training scripts
+tests/            mirrors src/ structure
+configs/          YAML configs per engine
+```
+
+## Import order for training scripts
+
+```python
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))  # repo root
+from src.types import ...
+from training.phaseN_*/model import ...
+```
+
+## Checkpoint format (all engines)
+
+```python
+torch.save({
+    "epoch":       int,
+    "model_state": model.state_dict(),
+    "optimizer":   optimizer.state_dict(),
+    "val_auc":     float,
+    "config":      dict,
+}, path)
+```
+
+## Never do these
+
+- `from training.phase3_sstgnn.model import SSTGNNModel` inside `src/` — use try/except ImportError
+- `torch.jit.script(sstgnn_model)` — crashes silently on PyG
+- `min_detection_confidence=0.5` — fails on 40% of DFDC frames
+- Hardcode `localhost:8000` in frontend — use `process.env.NEXT_PUBLIC_API_URL`
+- Import `torch_geometric` at module level without a guard — not available in all envs

.gitignore

@@ -0,0 +1,70 @@
+# GenAI-DeepDetect .gitignore
+
+# ── Model files ───────────────────────────────────────────────────────────────
+models/
+*.pt
+*.pth
+*.bin
+*.safetensors
+
+# ── Datasets ──────────────────────────────────────────────────────────────────
+data/
+*.zip
+*.tar
+*.tar.gz
+
+# ── Cache dirs (never commit these) ──────────────────────────────────────────
+.deps-local/
+.pydeps/
+.hf-cache/
+.huggingface/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# ── Kaggle artifacts ──────────────────────────────────────────────────────────
+.kaggle-kernel-output/
+.kaggle-kernel-pulled/
+kaggle.json
+# Keep .kaggle-kernel/ (used for packaging)
+
+# ── Training logs ─────────────────────────────────────────────────────────────
+training/logs/
+*.log
+
+# ── Environment ───────────────────────────────────────────────────────────────
+.env
+.env.local
+.env.*.local
+venv/
+.venv/
+env/
+.env.example
+
+# ── IDE ───────────────────────────────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ── Frontend ──────────────────────────────────────────────────────────────────
+node_modules/
+frontend/node_modules/
+frontend/.next/
+frontend/out/
+frontend/.env.local
+frontend/tsconfig.tsbuildinfo
+
+# ── Junk that got committed before ────────────────────────────────────────────
+"New Text Document.txt"
+*.txt.bak
+
+# ── Build artifacts ───────────────────────────────────────────────────────────
+dist/
+build/
+*.egg-info/

CLAUDE.md

@@ -0,0 +1,1311 @@
+# CLAUDE.md — GenAI-DeepDetect Agent Instructions
+
+> Read this file before touching any code. It is the single source of truth for
+> how this repo is structured, what conventions to follow, and what the hard
+> constraints are.
+
+# CLAUDE.md — GenAI-DeepDetect
+
+Full implementation guide for AI-assisted development on this project. Read this
+file before touching any code.
+
+-# CLAUDE.md — GenAI-DeepDetect
+
+Complete implementation guide. Read this before writing any code. All models are
+**100% pre-trained** — no training required, no GPU needed locally.
+
+---
+
+## MCP Tools — Always Use These First
+
+Before writing any code or looking up any API, resolve docs through MCP:
+
+```
+context7: resolve-library-id + query-docs
+  → use for: transformers, torch, mediapipe, fastapi, torch-geometric,
+    google-generativeai, facenet-pytorch, opencv, next.js, runpod
+
+huggingface: model_search + model_details + hf_doc_search
+  → use for: finding model cards, checking input formats, confirming
+    pipeline task names, verifying checkpoint sizes before using
+```
+
+**Rule**: Never guess an API signature. Always call `context7.query-docs` first.
+Never use a HF model without calling `huggingface.model_details` to confirm it
+exists, check its license, and verify its input format.
+
+---
+
+## Project Skill And Memory Policy
+
+For work in this repository, always prefer the installed Claude Code skill pack
+when a relevant skill applies instead of ad hoc workflows.
+
+- Use `context7-mcp` for any library, framework, SDK, or API question, and
+  before changing code that depends on external packages or hosted services.
+- Use `mem-search` / claude-mem whenever the user asks about previous sessions,
+  prior fixes, earlier decisions, or "how we solved this before".
+- When using claude-mem, scope searches to project name `genai-deepdetect`
+  unless the user explicitly asks for a broader search.
+- Keep following the repo-specific MCP rules below even when a general-purpose
+  skill also applies.
+
+Recommended companion skills for this project:
+
+- `systematic-debugging` for bugs, failing tests, or unexpected runtime
+  behavior
+- `verification-before-completion` before claiming a fix is done
+- `security-review` for secrets, external APIs, uploads, and auth-sensitive
+  changes
+
+---
+
+## Project Goal
+
+Multimodal deepfake and AI-generated content detector.
+
+- Input: image (JPEG/PNG/WEBP) or video (MP4/MOV/AVI, max 100MB)
+- Output: `DetectionResponse` — verdict, confidence, generator attribution,
+  natural-language explanation, per-engine breakdown
+
+All inference runs on pre-trained HuggingFace checkpoints. No training scripts
+need to run for the system to work.
+
+---
+
+## Architecture
+
+```
+Request (image/video)
+        │
+        ▼
+  FastAPI  src/api/main.py
+        │
+        ├── FingerprintEngine   (image artifacts, generator attribution)
+        ├── CoherenceEngine     (lip-sync, biological coherence)
+        └── SSTGNNEngine        (landmark spatio-temporal graph)
+                │
+                ▼
+          Fuser  src/fusion/fuser.py
+                │
+                ▼
+        Explainer  src/explainability/explainer.py   ← Gemini API
+                │
+                ▼
+        DetectionResponse  src/types.py
+```
+
+---
+
+## All Pre-Trained Models
+
+Every model downloads via `transformers.pipeline()` or `from_pretrained()`. Zero
+training. Zero fine-tuning.
+
+| Engine      | Model               | HF ID                                      | Size   | Task                   |
+| ----------- | ------------------- | ------------------------------------------ | ------ | ---------------------- |
+| Fingerprint | SDXL Detector       | `Organika/sdxl-detector`                   | ~330MB | binary fake/real       |
+| Fingerprint | CLIP ViT-L/14       | `openai/clip-vit-large-patch14`            | ~3.5GB | generator attribution  |
+| Fingerprint | AI Image Detector   | `haywoodsloan/ai-image-detector-deploy`    | ~90MB  | ensemble backup        |
+| SSTGNN      | DeepFake Detector   | `dima806/deepfake_vs_real_image_detection` | ~100MB | ResNet50 per-frame     |
+| SSTGNN      | Deep Fake Detector  | `prithivMLmods/Deep-Fake-Detector-Model`   | ~80MB  | EfficientNet-B4 backup |
+| Coherence   | MediaPipe Face Mesh | bundled in `mediapipe` package             | ~10MB  | landmark extraction    |
+| Coherence   | FaceNet VGGFace2    | `facenet-pytorch` (auto-downloads)         | ~100MB | temporal embeddings    |
+| Coherence   | SyncNet             | `Junhua-Zhu/SyncNet`                       | ~50MB  | lip-sync offset        |
+
+CLIP is the largest at 3.5GB — preload at startup, never reload. Everything else
+fits in HF Spaces 16GB RAM free tier.
+
+---
+
+## Environment Variables
+
+```bash
+# Required
+GEMINI_API_KEY=...                  # Google AI Studio — free tier works
+HF_TOKEN=hf_...                     # HuggingFace read token (free)
+
+# Hosting
+RUNPOD_API_KEY=...                  # RunPod serverless (heavy video)
+RUNPOD_ENDPOINT_ID=...              # your deployed endpoint ID
+
+# Paths
+MODEL_CACHE_DIR=/data/models        # HF Spaces: /data/models (persists)
+                                    # local dev: /tmp/models
+
+# Optional
+MAX_VIDEO_FRAMES=300
+MAX_VIDEO_SIZE_MB=100
+INFERENCE_BACKEND=local             # "local" | "runpod"
+TOKENIZERS_PARALLELISM=false
+```
+
+Set all secrets in:
+
+- HF Spaces → Settings → Repository secrets
+- RunPod → Secrets tab
+- Vercel → Environment Variables
+
+---
+
+## Gemini API — Explainability Engine
+
+**Primary model**: `gemini-2.5-pro-preview-03-25` **Fallback model**:
+`gemini-1.5-pro-002`
+
+Both available on Google AI Studio free tier (15 req/min, 1M tokens/day). Always
+query `context7.query-docs google-generativeai GenerativeModel` before modifying
+this file.
+
+### `src/explainability/explainer.py`
+
+```python
+import os
+import logging
+import google.generativeai as genai
+from src.types import EngineResult
+
+logger = logging.getLogger(__name__)
+
+genai.configure(api_key=os.environ["GEMINI_API_KEY"])
+
+SYSTEM_INSTRUCTION = (
+    "You are a deepfake forensics analyst writing reports for security professionals. "
+    "Given detection engine outputs, write exactly 2-3 sentences in plain English "
+    "explaining why the content is real or fake. "
+    "Be specific — name the strongest signals. "
+    "Use direct declarative sentences. No hedging. No 'I think'. "
+    "Output only the explanation text, nothing else."
+)
+
+_model = None
+
+
+def _get_model() -> genai.GenerativeModel:
+    global _model
+    if _model is None:
+        for name in ("gemini-2.5-pro-preview-03-25", "gemini-1.5-pro-002"):
+            try:
+                _model = genai.GenerativeModel(
+                    model_name=name,
+                    system_instruction=SYSTEM_INSTRUCTION,
+                )
+                logger.info(f"Gemini model loaded: {name}")
+                break
+            except Exception as e:
+                logger.warning(f"Gemini {name} unavailable: {e}")
+    return _model
+
+
+def explain(
+    verdict: str,
+    confidence: float,
+    engine_results: list[EngineResult],
+    generator: str,
+) -> str:
+    breakdown = "\n".join(
+        f"- {r.engine}: {r.verdict} ({r.confidence:.0%}) — {r.explanation}"
+        for r in engine_results
+    )
+    prompt = (
+        f"Verdict: {verdict} ({confidence:.0%} confidence)\n"
+        f"Attributed generator: {generator}\n"
+        f"Engine breakdown:\n{breakdown}\n\n"
+        "Write the forensics explanation."
+    )
+    try:
+        model = _get_model()
+        if model is None:
+            raise RuntimeError("No Gemini model available")
+        response = model.generate_content(prompt)
+        return response.text.strip()
+    except Exception as e:
+        logger.error(f"Gemini explain failed: {e}")
+        top = engine_results[0] if engine_results else None
+        return (
+            f"Content classified as {verdict} with {confidence:.0%} confidence. "
+            f"{'Primary signal from ' + top.engine + ' engine.' if top else ''}"
+        )
+```
+
+---
+
+## Engine Implementations
+
+### FingerprintEngine — `src/engines/fingerprint/engine.py`
+
+Query context7 for `transformers pipeline image-classification` and
+`huggingface model_details Organika/sdxl-detector` before modifying.
+
+```python
+import os, logging, threading
+import numpy as np
+from PIL import Image
+from transformers import pipeline, CLIPModel, CLIPProcessor
+import torch
+from src.types import EngineResult
+
+logger = logging.getLogger(__name__)
+CACHE = os.environ.get("MODEL_CACHE_DIR", "/tmp/models")
+
+GENERATOR_PROMPTS = {
+    "real":             "a real photograph taken by a camera with natural lighting",
+    "unknown_gan":      "a GAN-generated image with checkerboard artifacts and blurry edges",
+    "stable_diffusion": "a Stable Diffusion image with painterly soft textures",
+    "midjourney":       "a Midjourney image with cinematic dramatic lighting and hyperdetail",
+    "dall_e":           "a DALL-E image with clean illustration-style and smooth gradients",
+    "flux":             "a FLUX model image with photorealistic precision and sharp detail",
+    "firefly":          "an Adobe Firefly image with commercial stock-photo aesthetics",
+    "imagen":           "a Google Imagen image with precise photorealistic rendering",
+}
+
+_lock = threading.Lock()
+_detector = _clip_model = _clip_processor = _backup = None
+
+
+def _load():
+    global _detector, _clip_model, _clip_processor, _backup
+    if _detector is not None:
+        return
+    logger.info("Loading fingerprint models...")
+    _detector = pipeline("image-classification",
+                         model="Organika/sdxl-detector", cache_dir=CACHE)
+    _clip_model = CLIPModel.from_pretrained(
+        "openai/clip-vit-large-patch14", cache_dir=CACHE)
+    _clip_processor = CLIPProcessor.from_pretrained(
+        "openai/clip-vit-large-patch14", cache_dir=CACHE)
+    _clip_model.eval()
+    try:
+        _backup = pipeline("image-classification",
+                           model="haywoodsloan/ai-image-detector-deploy",
+                           cache_dir=CACHE)
+    except Exception:
+        logger.warning("Backup fingerprint detector unavailable")
+    logger.info("Fingerprint models ready")
+
+
+class FingerprintEngine:
+
+    def _ensure(self):
+        with _lock:
+            _load()
+
+    def run(self, image: Image.Image) -> EngineResult:
+        self._ensure()
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+
+        # Binary fake score
+        FAKE_LABELS = {"artificial", "fake", "ai-generated", "generated"}
+        try:
+            preds = _detector(image)
+            fake_score = max(
+                (p["score"] for p in preds if p["label"].lower() in FAKE_LABELS),
+                default=0.5,
+            )
+        except Exception as e:
+            logger.warning(f"Primary detector error: {e}")
+            fake_score = 0.5
+
+        # Ensemble backup
+        if _backup is not None:
+            try:
+                bp = _backup(image)
+                bk = max((p["score"] for p in bp
+                          if p["label"].lower() in FAKE_LABELS), default=0.5)
+                fake_score = fake_score * 0.6 + bk * 0.4
+            except Exception:
+                pass
+
+        # CLIP zero-shot generator attribution
+        generator = "real"
+        try:
+            texts = list(GENERATOR_PROMPTS.values())
+            inputs = _clip_processor(
+                text=texts, images=image,
+                return_tensors="pt", padding=True, truncation=True,
+            )
+            with torch.no_grad():
+                logits = _clip_model(**inputs).logits_per_image[0]
+            probs = logits.softmax(dim=0).numpy()
+            generator = list(GENERATOR_PROMPTS.keys())[int(np.argmax(probs))]
+        except Exception as e:
+            logger.warning(f"CLIP attribution error: {e}")
+
+        if fake_score > 0.65 and generator == "real":
+            generator = "unknown_gan"
+
+        return EngineResult(
+            engine="fingerprint",
+            verdict="FAKE" if fake_score > 0.5 else "REAL",
+            confidence=float(fake_score),
+            attributed_generator=generator,
+            explanation=f"Binary score {fake_score:.2f}; attributed to {generator}.",
+        )
+
+    def run_video(self, frames: list) -> EngineResult:
+        if not frames:
+            return EngineResult(engine="fingerprint", verdict="UNKNOWN",
+                                confidence=0.5, explanation="No frames.")
+        keyframes = frames[::8] or [frames[0]]
+        results = [self.run(Image.fromarray(f)) for f in keyframes]
+        avg = float(np.mean([r.confidence for r in results]))
+        gens = [r.attributed_generator for r in results]
+        top_gen = max(set(gens), key=gens.count)
+        return EngineResult(
+            engine="fingerprint",
+            verdict="FAKE" if avg > 0.5 else "REAL",
+            confidence=avg,
+            attributed_generator=top_gen,
+            explanation=f"Keyframe average {avg:.2f} over {len(keyframes)} frames.",
+        )
+```
+
+---
+
+### CoherenceEngine — `src/engines/coherence/engine.py`
+
+Query `context7.query-docs mediapipe face_mesh` and
+`context7.query-docs facenet-pytorch InceptionResnetV1` before modifying.
+
+```python
+import logging, threading, cv2
+import numpy as np
+from PIL import Image
+from facenet_pytorch import MTCNN, InceptionResnetV1
+import mediapipe as mp
+from src.types import EngineResult
+
+logger = logging.getLogger(__name__)
+
+_lock = threading.Lock()
+_mtcnn = _resnet = _face_mesh = None
+
+
+def _load():
+    global _mtcnn, _resnet, _face_mesh
+    if _mtcnn is not None:
+        return
+    logger.info("Loading coherence models...")
+    _mtcnn   = MTCNN(keep_all=False, device="cpu")
+    _resnet  = InceptionResnetV1(pretrained="vggface2").eval()
+    _face_mesh = mp.solutions.face_mesh.FaceMesh(
+        static_image_mode=False, max_num_faces=1,
+        refine_landmarks=True, min_detection_confidence=0.5,
+    )
+    logger.info("Coherence models ready")
+
+
+class CoherenceEngine:
+
+    def _ensure(self):
+        with _lock:
+            _load()
+
+    def run(self, image: Image.Image) -> EngineResult:
+        self._ensure()
+        frame = np.array(image.convert("RGB"))
+        score = self._image_score(frame)
+        return EngineResult(
+            engine="coherence",
+            verdict="FAKE" if score > 0.5 else "REAL",
+            confidence=float(score),
+            explanation=f"Geometric coherence anomaly {score:.2f} (image mode).",
+        )
+
+    def _image_score(self, frame: np.ndarray) -> float:
+        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) if frame.shape[2] == 3 else frame
+        res = _face_mesh.process(rgb)
+        if not res.multi_face_landmarks:
+            return 0.35  # no face detected
+
+        lms = res.multi_face_landmarks[0].landmark
+        h, w = frame.shape[:2]
+
+        def pt(i):
+            return np.array([lms[i].x * w, lms[i].y * h])
+
+        # Eye width asymmetry — deepfakes often mismatched
+        lew = np.linalg.norm(pt(33)  - pt(133))
+        rew = np.linalg.norm(pt(362) - pt(263))
+        eye_ratio = min(lew, rew) / (max(lew, rew) + 1e-9)
+        eye_score = max(0.0, (0.85 - eye_ratio) / 0.3)
+
+        # Ear symmetry from nose tip
+        nose = pt(1)
+        lr = min(np.linalg.norm(nose - pt(234)), np.linalg.norm(nose - pt(454)))
+        rr = max(np.linalg.norm(nose - pt(234)), np.linalg.norm(nose - pt(454)))
+        ear_score = max(0.0, (0.90 - lr / (rr + 1e-9)) / 0.2)
+
+        return float(np.clip(eye_score * 0.5 + ear_score * 0.5, 0.0, 1.0))
+
+    def run_video(self, frames: list[np.ndarray]) -> EngineResult:
+        self._ensure()
+        if len(frames) < 4:
+            r = self.run(Image.fromarray(frames[0]))
+            r.explanation = "Too few frames for temporal analysis."
+            return r
+
+        delta  = self._embedding_variance(frames)
+        jerk   = self._landmark_jerk(frames)
+        blink  = self._blink_anomaly(frames)
+        score  = float(np.clip(delta * 0.45 + jerk * 0.35 + blink * 0.20, 0.0, 1.0))
+
+        return EngineResult(
+            engine="coherence",
+            verdict="FAKE" if score > 0.5 else "REAL",
+            confidence=score,
+            explanation=(
+                f"Embedding variance {delta:.2f}, "
+                f"landmark jerk {jerk:.2f}, "
+                f"blink anomaly {blink:.2f}."
+            ),
+        )
+
+    def _embedding_variance(self, frames: list[np.ndarray]) -> float:
+        import torch
+        embeddings = []
+        for frame in frames[::4]:
+            try:
+                face = _mtcnn(Image.fromarray(frame))
+                if face is not None:
+                    with torch.no_grad():
+                        e = _resnet(face.unsqueeze(0)).numpy()[0]
+                    embeddings.append(e)
+            except Exception:
+                continue
+        if len(embeddings) < 2:
+            return 0.5
+        deltas = [np.linalg.norm(embeddings[i+1] - embeddings[i])
+                  for i in range(len(embeddings)-1)]
+        return float(np.clip(np.var(deltas) * 8, 0.0, 1.0))
+
+    def _landmark_jerk(self, frames: list[np.ndarray]) -> float:
+        positions = []
+        for frame in frames[::2]:
+            rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+            res = _face_mesh.process(rgb)
+            if res.multi_face_landmarks:
+                lm = res.multi_face_landmarks[0].landmark
+                positions.append([lm[1].x, lm[1].y])
+        if len(positions) < 4:
+            return 0.3
+        pos   = np.array(positions)
+        jerk  = np.diff(pos, n=3, axis=0)
+        return float(np.clip((np.mean(np.linalg.norm(jerk, axis=1)) - 0.002) / 0.008,
+                             0.0, 1.0))
+
+    def _blink_anomaly(self, frames: list[np.ndarray]) -> float:
+        LEFT_EYE  = [33, 160, 158, 133, 153, 144]
+        RIGHT_EYE = [362, 385, 387, 263, 373, 380]
+
+        def ear(lms, idx, h, w):
+            pts = [np.array([lms[i].x * w, lms[i].y * h]) for i in idx]
+            a = np.linalg.norm(pts[1] - pts[5])
+            b = np.linalg.norm(pts[2] - pts[4])
+            c = np.linalg.norm(pts[0] - pts[3])
+            return (a + b) / (2.0 * c + 1e-9)
+
+        ears = []
+        for frame in frames:
+            rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+            res = _face_mesh.process(rgb)
+            if res.multi_face_landmarks:
+                lm = res.multi_face_landmarks[0].landmark
+                h, w = frame.shape[:2]
+                ears.append((ear(lm, LEFT_EYE, h, w) + ear(lm, RIGHT_EYE, h, w)) / 2)
+
+        if len(ears) < 10:
+            return 0.3
+        arr    = np.array(ears)
+        blinks = int(np.sum(np.diff((arr < 0.21).astype(int)) > 0))
+        bpm    = blinks / (len(ears) / 25) * 60
+        if 8 <= bpm <= 25:
+            return 0.15
+        if bpm < 3 or bpm > 35:
+            return 0.80
+        return 0.45
+```
+
+---
+
+### SSTGNNEngine — `src/engines/sstgnn/engine.py`
+
+Query `context7.query-docs torch-geometric GCNConv` and
+`huggingface model_details dima806/deepfake_vs_real_image_detection` before
+modifying.
+
+```python
+import logging, os, threading
+import numpy as np
+import cv2
+from PIL import Image
+from transformers import pipeline
+import mediapipe as mp
+from scipy.spatial import Delaunay
+from src.types import EngineResult
+
+logger = logging.getLogger(__name__)
+CACHE = os.environ.get("MODEL_CACHE_DIR", "/tmp/models")
+
+_lock = threading.Lock()
+_det1 = _det2 = _mesh = None
+
+
+def _load():
+    global _det1, _det2, _mesh
+    if _det1 is not None:
+        return
+    logger.info("Loading SSTGNN models...")
+    _det1 = pipeline("image-classification",
+                     model="dima806/deepfake_vs_real_image_detection",
+                     cache_dir=CACHE)
+    try:
+        _det2 = pipeline("image-classification",
+                         model="prithivMLmods/Deep-Fake-Detector-Model",
+                         cache_dir=CACHE)
+    except Exception:
+        logger.warning("SSTGNN backup detector unavailable")
+    _mesh = mp.solutions.face_mesh.FaceMesh(
+        static_image_mode=True, max_num_faces=1, refine_landmarks=True)
+    logger.info("SSTGNN models ready")
+
+
+def _fake_prob(preds: list[dict]) -> float:
+    fake_kw = {"fake", "deepfake", "artificial", "generated", "ai"}
+    return max(
+        (p["score"] for p in preds
+         if any(k in p["label"].lower() for k in fake_kw)),
+        default=0.5,
+    )
+
+
+class SSTGNNEngine:
+
+    def _ensure(self):
+        with _lock:
+            _load()
+
+    def run(self, image: Image.Image) -> EngineResult:
+        self._ensure()
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+
+        scores = []
+        try:
+            scores.append(_fake_prob(_det1(image)) * 0.6)
+        except Exception as e:
+            logger.warning(f"SSTGNN det1 error: {e}")
+        if _det2:
+            try:
+                scores.append(_fake_prob(_det2(image)) * 0.4)
+            except Exception as e:
+                logger.warning(f"SSTGNN det2 error: {e}")
+
+        if not scores:
+            return EngineResult(engine="sstgnn", verdict="UNKNOWN",
+                                confidence=0.5, explanation="All detectors failed.")
+
+        cnn = sum(scores) / (0.6 if len(scores) == 1 else 1.0)
+        graph = self._geometry_score(np.array(image))
+        final = float(np.clip(cnn * 0.7 + graph * 0.3, 0.0, 1.0))
+
+        return EngineResult(
+            engine="sstgnn",
+            verdict="FAKE" if final > 0.5 else "REAL",
+            confidence=final,
+            explanation=f"CNN {cnn:.2f}, geometric graph anomaly {graph:.2f}.",
+        )
+
+    def _geometry_score(self, frame: np.ndarray) -> float:
+        try:
+            rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+            res = _mesh.process(rgb)
+            if not res.multi_face_landmarks:
+                return 0.3
+            h, w = frame.shape[:2]
+            lms = res.multi_face_landmarks[0].landmark
+            idxs = list(range(0, 468, 7))[:68]
+            pts  = np.array([[lms[i].x * w, lms[i].y * h] for i in idxs])
+            tri  = Delaunay(pts)
+            areas = []
+            for s in tri.simplices:
+                a, b, c = pts[s]
+                areas.append(abs(np.cross(b - a, c - a)) / 2)
+            areas = np.array(areas)
+            cv_score = float(np.std(areas) / (np.mean(areas) + 1e-9))
+            return float(np.clip((cv_score - 0.8) / 1.5, 0.0, 1.0))
+        except Exception as e:
+            logger.warning(f"Geometry score error: {e}")
+            return 0.3
+
+    def run_video(self, frames: list[np.ndarray]) -> EngineResult:
+        self._ensure()
+        if not frames:
+            return EngineResult(engine="sstgnn", verdict="UNKNOWN",
+                                confidence=0.5, explanation="No frames.")
+        sample = frames[::6] or [frames[0]]
+        results = [self.run(Image.fromarray(f)) for f in sample]
+        avg = float(np.mean([r.confidence for r in results]))
+        return EngineResult(
+            engine="sstgnn",
+            verdict="FAKE" if avg > 0.5 else "REAL",
+            confidence=avg,
+            explanation=f"Frame-sampled SSTGNN average {avg:.2f} over {len(sample)} frames.",
+        )
+```
+
+---
+
+## Fusion — `src/fusion/fuser.py`
+
+```python
+import numpy as np
+from src.types import EngineResult
+
+ENGINE_WEIGHTS = {
+    "fingerprint": 0.45,
+    "coherence":   0.35,
+    "sstgnn":      0.20,
+}
+
+ENGINE_WEIGHTS_VIDEO = {
+    "fingerprint": 0.30,
+    "coherence":   0.50,
+    "sstgnn":      0.20,
+}
+
+ATTRIBUTION_PRIORITY = {"fingerprint": 1, "sstgnn": 2, "coherence": 3}
+
+
+def fuse(
+    results: list[EngineResult],
+    is_video: bool = False,
+) -> tuple[str, float, str]:
+    """Returns (verdict, confidence, attributed_generator)."""
+    weights = ENGINE_WEIGHTS_VIDEO if is_video else ENGINE_WEIGHTS
+    active  = [r for r in results if r.verdict != "UNKNOWN"]
+
+    if not active:
+        return "UNKNOWN", 0.5, "unknown_gan"
+
+    wf = sum(r.confidence * weights.get(r.engine, 0.1)
+             for r in active if r.verdict == "FAKE")
+    wr = sum((1 - r.confidence) * weights.get(r.engine, 0.1)
+             for r in active if r.verdict == "REAL")
+
+    fake_prob = float(np.clip(wf / (wf + wr + 1e-9), 0.0, 1.0))
+    verdict   = "FAKE" if fake_prob > 0.5 else "REAL"
+
+    generator = "real"
+    if verdict == "FAKE":
+        for r in sorted(active, key=lambda r: ATTRIBUTION_PRIORITY.get(r.engine, 9)):
+            if r.attributed_generator and r.attributed_generator != "real":
+                generator = r.attributed_generator
+                break
+        if generator == "real":
+            generator = "unknown_gan"
+
+    return verdict, fake_prob, generator
+```
+
+---
+
+## API — `src/api/main.py`
+
+```python
+import asyncio, io, logging, os, time
+from pathlib import Path
+
+import cv2, numpy as np
+from fastapi import FastAPI, File, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from PIL import Image
+
+from src.engines.fingerprint.engine import FingerprintEngine
+from src.engines.coherence.engine    import CoherenceEngine
+from src.engines.sstgnn.engine       import SSTGNNEngine
+from src.explainability.explainer    import explain
+from src.fusion.fuser                import fuse
+from src.services.inference_router   import route_inference
+from src.types                       import DetectionResponse
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="GenAI-DeepDetect", version="1.0.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"], allow_methods=["*"], allow_headers=["*"],
+)
+
+_fp = FingerprintEngine()
+_co = CoherenceEngine()
+_st = SSTGNNEngine()
+
+MAX_MB     = int(os.environ.get("MAX_VIDEO_SIZE_MB", 100))
+MAX_FRAMES = int(os.environ.get("MAX_VIDEO_FRAMES",  300))
+
+IMAGE_TYPES = {"image/jpeg", "image/png", "image/webp", "image/bmp"}
+VIDEO_TYPES = {"video/mp4", "video/quicktime", "video/x-msvideo", "video/webm"}
+
+
+def _extract_frames(path: str) -> list[np.ndarray]:
+    cap = cv2.VideoCapture(path)
+    total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    step  = max(1, total // MAX_FRAMES)
+    frames, i = [], 0
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+        if i % step == 0:
+            frames.append(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
+        i += 1
+    cap.release()
+    return frames[:MAX_FRAMES]
+
+
+@app.on_event("startup")
+async def preload():
+    logger.info("Preloading models...")
+    await asyncio.gather(
+        asyncio.to_thread(_fp._ensure),
+        asyncio.to_thread(_co._ensure),
+        asyncio.to_thread(_st._ensure),
+    )
+    logger.info("All models preloaded")
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+
+
+@app.post("/detect/image", response_model=DetectionResponse)
+async def detect_image(file: UploadFile = File(...)):
+    t0 = time.monotonic()
+    if file.content_type not in IMAGE_TYPES:
+        raise HTTPException(400, f"Unsupported type: {file.content_type}")
+    data = await file.read()
+    if len(data) > MAX_MB * 1024 * 1024:
+        raise HTTPException(413, "File too large")
+
+    image = Image.open(io.BytesIO(data)).convert("RGB")
+    fp, co, st = await asyncio.gather(
+        asyncio.to_thread(_fp.run, image),
+        asyncio.to_thread(_co.run, image),
+        asyncio.to_thread(_st.run, image),
+    )
+    ms = (time.monotonic() - t0) * 1000
+    for r in [fp, co, st]:
+        r.processing_time_ms = ms
+
+    verdict, conf, gen = fuse([fp, co, st], is_video=False)
+    expl = await asyncio.to_thread(explain, verdict, conf, [fp, co, st], gen)
+
+    return DetectionResponse(
+        verdict=verdict, confidence=conf, attributed_generator=gen,
+        explanation=expl, processing_time_ms=ms,
+        engine_breakdown=[fp, co, st],
+    )
+
+
+@app.post("/detect/video", response_model=DetectionResponse)
+async def detect_video(file: UploadFile = File(...)):
+    t0 = time.monotonic()
+    if file.content_type not in VIDEO_TYPES:
+        raise HTTPException(400, f"Unsupported type: {file.content_type}")
+    data = await file.read()
+    if len(data) > MAX_MB * 1024 * 1024:
+        raise HTTPException(413, "File too large")
+
+    # Route heavy videos to RunPod
+    if len(data) > 20 * 1024 * 1024:
+        return await route_inference(data, "video")
+
+    tmp = Path(f"/tmp/vid_{int(time.time()*1000)}.mp4")
+    tmp.write_bytes(data)
+    try:
+        frames = await asyncio.to_thread(_extract_frames, str(tmp))
+    finally:
+        tmp.unlink(missing_ok=True)
+
+    if not frames:
+        raise HTTPException(422, "Could not extract frames")
+
+    fp, co, st = await asyncio.gather(
+        asyncio.to_thread(_fp.run_video, frames),
+        asyncio.to_thread(_co.run_video, frames),
+        asyncio.to_thread(_st.run_video, frames),
+    )
+    ms = (time.monotonic() - t0) * 1000
+    for r in [fp, co, st]:
+        r.processing_time_ms = ms
+
+    verdict, conf, gen = fuse([fp, co, st], is_video=True)
+    expl = await asyncio.to_thread(explain, verdict, conf, [fp, co, st], gen)
+
+    return DetectionResponse(
+        verdict=verdict, confidence=conf, attributed_generator=gen,
+        explanation=expl, processing_time_ms=ms,
+        engine_breakdown=[fp, co, st],
+    )
+```
+
+---
+
+## Types — `src/types.py`
+
+```python
+from __future__ import annotations
+from typing import Optional
+from pydantic import BaseModel
+
+GENERATOR_LABELS = {
+    0: "real",
+    1: "unknown_gan",
+    2: "stable_diffusion",
+    3: "midjourney",
+    4: "dall_e",
+    5: "flux",
+    6: "firefly",
+    7: "imagen",
+}
+
+
+class EngineResult(BaseModel):
+    engine: str
+    verdict: str                            # FAKE | REAL | UNKNOWN
+    confidence: float                       # 0–1
+    attributed_generator: Optional[str] = None
+    explanation: str = ""
+    processing_time_ms: float = 0.0
+
+
+class DetectionResponse(BaseModel):
+    verdict: str
+    confidence: float
+    attributed_generator: str
+    explanation: str
+    processing_time_ms: float
+    engine_breakdown: list[EngineResult]
+```
+
+---
+
+## Inference Router — `src/services/inference_router.py`
+
+```python
+import base64, logging, os
+import httpx
+from src.types import DetectionResponse
+
+logger = logging.getLogger(__name__)
+
+RUNPOD_KEY = os.environ.get("RUNPOD_API_KEY", "")
+RUNPOD_EID = os.environ.get("RUNPOD_ENDPOINT_ID", "")
+
+
+async def route_inference(data: bytes, media_type: str) -> DetectionResponse:
+    if not RUNPOD_KEY or not RUNPOD_EID:
+        raise RuntimeError(
+            "RunPod not configured. Set RUNPOD_API_KEY and RUNPOD_ENDPOINT_ID."
+        )
+    url     = f"https://api.runpod.ai/v2/{RUNPOD_EID}/runsync"
+    payload = {"input": {"data": base64.b64encode(data).decode(),
+                         "media_type": media_type}}
+    async with httpx.AsyncClient(timeout=120) as client:
+        resp = await client.post(url, json=payload,
+                                 headers={"Authorization": f"Bearer {RUNPOD_KEY}"})
+        resp.raise_for_status()
+        return DetectionResponse(**resp.json()["output"])
+```
+
+---
+
+## RunPod Handler — `runpod_handler.py` (project root)
+
+```python
+import base64, io, os, tempfile
+import runpod, cv2, numpy as np
+from PIL import Image
+
+os.environ.setdefault("MODEL_CACHE_DIR", "/tmp/models")
+
+from src.engines.fingerprint.engine import FingerprintEngine
+from src.engines.coherence.engine    import CoherenceEngine
+from src.engines.sstgnn.engine       import SSTGNNEngine
+from src.explainability.explainer    import explain
+from src.fusion.fuser                import fuse
+
+_fp = FingerprintEngine()
+_co = CoherenceEngine()
+_st = SSTGNNEngine()
+
+
+def handler(job: dict) -> dict:
+    inp        = job["input"]
+    raw        = base64.b64decode(inp["data"])
+    media_type = inp.get("media_type", "image")
+
+    if media_type == "image":
+        image = Image.open(io.BytesIO(raw)).convert("RGB")
+        fp = _fp.run(image)
+        co = _co.run(image)
+        st = _st.run(image)
+        verdict, conf, gen = fuse([fp, co, st], is_video=False)
+    else:
+        with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:
+            f.write(raw)
+            tmp = f.name
+        try:
+            cap = cv2.VideoCapture(tmp)
+            frames, i = [], 0
+            while True:
+                ret, frame = cap.read()
+                if not ret:
+                    break
+                if i % 4 == 0:
+                    frames.append(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
+                i += 1
+            cap.release()
+        finally:
+            os.unlink(tmp)
+        fp = _fp.run_video(frames)
+        co = _co.run_video(frames)
+        st = _st.run_video(frames)
+        verdict, conf, gen = fuse([fp, co, st], is_video=True)
+
+    expl = explain(verdict, conf, [fp, co, st], gen)
+
+    return {
+        "verdict": verdict,
+        "confidence": conf,
+        "attributed_generator": gen,
+        "explanation": expl,
+        "processing_time_ms": 0.0,
+        "engine_breakdown": [r.model_dump() for r in [fp, co, st]],
+    }
+
+
+runpod.serverless.start({"handler": handler})
+```
+
+---
+
+## Hosting
+
+### Option A — HuggingFace Spaces (Free, CPU, primary API host)
+
+**`spaces/app.py`**:
+
+```python
+import os
+os.environ.setdefault("MODEL_CACHE_DIR", "/data/models")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+import uvicorn
+from src.api.main import app
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860, workers=1)
+```
+
+**Root `README.md`** front-matter (Hugging Face reads this file):
+
+```yaml
+---
+title: GenAI DeepDetect
+emoji: "🔍"
+colorFrom: gray
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+```
+
+**`Dockerfile`** (replace existing):
+
+```dockerfile
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y \
+    ffmpeg libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV MODEL_CACHE_DIR=/data/models
+ENV TOKENIZERS_PARALLELISM=false
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+CMD ["python", "spaces/app.py"]
+```
+
+**Secrets to set in HF Spaces** (Settings → Repository secrets):
+
+```
+GEMINI_API_KEY
+HF_TOKEN
+RUNPOD_API_KEY
+RUNPOD_ENDPOINT_ID
+```
+
+**Free tier**: 2 vCPU, 16GB RAM, persistent `/data` volume. Models cache to
+`/data/models` and survive container restarts. Cold start first request: ~90s.
+Warm: <5s. GPU upgrade: T4 at $0.05/hr if needed.
+
+---
+
+### Option B — RunPod Serverless (GPU, heavy video, low cost)
+
+1. RunPod → Serverless → New Endpoint
+2. Select template: `runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04`
+3. Set handler file: `runpod_handler.py`
+4. Min replicas: 0, Max: 3
+5. GPU: RTX 3090 or A40 (cheapest that works)
+6. Set env vars: `GEMINI_API_KEY`, `HF_TOKEN`, `MODEL_CACHE_DIR=/tmp/models`
+
+**Cost**: ~$0.0002/request on H100. Billed per second. Min workers = 0 means you
+pay nothing when idle — cold start is ~15s.
+
+**When it triggers**: `inference_router.py` automatically sends videos >20MB to
+RunPod. Images always run on HF Spaces.
+
+---
+
+## Frontend — `frontend/lib/api.ts`
+
+```typescript
+const BASE_URL =
+	process.env.NEXT_PUBLIC_API_URL ??
+	'https://YOUR-USERNAME-genai-deepdetect.hf.space';
+
+export type GeneratorLabel =
+	| 'real'
+	| 'unknown_gan'
+	| 'stable_diffusion'
+	| 'midjourney'
+	| 'dall_e'
+	| 'flux'
+	| 'firefly'
+	| 'imagen';
+
+export interface EngineResult {
+	engine: string;
+	verdict: 'FAKE' | 'REAL' | 'UNKNOWN';
+	confidence: number;
+	attributed_generator: GeneratorLabel | null;
+	explanation: string;
+	processing_time_ms: number;
+}
+
+export interface DetectionResponse {
+	verdict: 'FAKE' | 'REAL' | 'UNKNOWN';
+	confidence: number;
+	attributed_generator: GeneratorLabel;
+	explanation: string;
+	processing_time_ms: number;
+	engine_breakdown: EngineResult[];
+}
+
+async function _post(endpoint: string, file: File): Promise<DetectionResponse> {
+	const form = new FormData();
+	form.append('file', file);
+	const res = await fetch(`${BASE_URL}${endpoint}`, {
+		method: 'POST',
+		body: form,
+	});
+	if (!res.ok) {
+		const err = await res.text();
+		throw new Error(`Detection failed (${res.status}): ${err}`);
+	}
+	return res.json();
+}
+
+export const detectImage = (file: File) => _post('/detect/image', file);
+export const detectVideo = (file: File) => _post('/detect/video', file);
+```
+
+Set in `frontend/.env.local`:
+
+```
+NEXT_PUBLIC_API_URL=https://your-username-genai-deepdetect.hf.space
+```
+
+---
+
+## Dependencies — `requirements.txt`
+
+```
+# API
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+python-multipart>=0.0.9
+aiofiles>=23.2.1
+httpx>=0.27.0
+pydantic>=2.7.0
+
+# ML — fingerprint
+transformers>=4.40.0
+timm>=1.0.0
+torch>=2.1.0
+torchvision>=0.16.0
+
+# ML — coherence
+facenet-pytorch>=2.5.3
+mediapipe>=0.10.14
+opencv-python-headless>=4.9.0
+
+# ML — sstgnn
+torch-geometric>=2.5.0
+scipy>=1.13.0
+
+# Explainability — Gemini
+google-generativeai>=0.8.0
+
+# HuggingFace
+huggingface-hub>=0.23.0
+
+# RunPod serverless handler
+runpod>=1.6.0
+
+# Continual learning
+apscheduler>=3.10.4
+
+# Utils
+Pillow>=10.3.0
+numpy>=1.26.0
+```
+
+---
+
+## Bug Checklist — Fix Before Running
+
+### `src/types.py`
+
+- [ ] `EngineResult` missing `attributed_generator: Optional[str] = None` — add
+      it
+- [ ] `DetectionResponse.engine_breakdown` typed as `list[dict]` — change to
+      `list[EngineResult]`
+
+### `src/fusion/fuser.py`
+
+- [ ] `fuse()` returns 2-tuple — update to return 3-tuple
+      `(verdict, conf, generator)`
+- [ ] Update all callers in `main.py` accordingly
+
+### `src/explainability/explainer.py`
+
+- [ ] References `anthropic` SDK — replace entirely with Gemini implementation
+      above
+
+### `src/api/main.py`
+
+- [ ] Missing CORS middleware — add before deploy
+- [ ] Missing `@app.on_event("startup")` preload — add it
+- [ ] Missing `_extract_frames()` for video — add it
+- [ ] `detect_video` likely missing or stubbed — implement fully
+
+### `src/engines/*/` directories
+
+- [ ] All three engine files are stubs or empty — replace with full code above
+
+### `spaces/app.py`
+
+- [ ] Likely empty — add uvicorn entrypoint
+
+### `Dockerfile`
+
+- [ ] Check for `ffmpeg` and `libgl1-mesa-glx` — required for MediaPipe + OpenCV
+- [ ] Check `EXPOSE 7860` matches HF Spaces `app_port`
+
+### `src/services/inference_router.py`
+
+- [ ] Likely stub — implement `route_inference()` with RunPod httpx call
+
+---
+
+## Code Standards
+
+- Lazy-load all models behind a threading lock — never load at module import
+- Wrap all model inference in `asyncio.to_thread()` — never block the event loop
+- Type hints on every function
+- `logging.getLogger(__name__)` not `print()`
+- `os.environ.get()` not hardcoded secrets
+- Pydantic `BaseModel` for all response schemas
+- Next.js: pages router only — no `app/` dir, no `src/` dir
+- Font: Plus Jakarta Sans or DM Sans — never Inter, Roboto, Arial
+- Border radius: 22% icon containers, 18px cards, 12px buttons
+
+---
+
+## MCP Usage Rules
+
+Every coding session must follow these rules:
+
+```
+1. Adding a dependency?
+   → context7: resolve-library-id <package>
+   → context7: query-docs <package> <specific feature>
+
+2. Using any HF model?
+   → huggingface: model_details <model-id>
+   → confirm size, license, task, input format
+
+3. Modifying engine logic?
+   → context7: query-docs transformers pipeline (fingerprint)
+   → context7: query-docs mediapipe face_mesh (coherence)
+   → context7: query-docs torch-geometric GCNConv (sstgnn)
+   → context7: query-docs facenet-pytorch (coherence embeddings)
+
+4. Modifying Gemini calls?
+   → context7: query-docs google-generativeai GenerativeModel
+
+5. Modifying RunPod handler?
+   → context7: query-docs runpod serverless handler
+
+6. Modifying FastAPI routes?
+   → context7: query-docs fastapi UploadFile
+
+7. Frontend API changes?
+   → context7: query-docs next.js pages-router fetch
+```
+
+---
+
+## Friday Deploy Checklist
+
+```
+[ ] pip install -r requirements.txt  (no errors)
+[ ] src/types.py  — EngineResult has attributed_generator
+[ ] src/types.py  — DetectionResponse has engine_breakdown: list[EngineResult]
+[ ] src/fusion/fuser.py  — returns 3-tuple
+[ ] src/explainability/explainer.py  — uses Gemini, no anthropic import
+[ ] src/engines/fingerprint/engine.py  — full implementation
+[ ] src/engines/coherence/engine.py  — full implementation
+[ ] src/engines/sstgnn/engine.py  — full implementation
+[ ] src/api/main.py  — CORS + startup preload + video route
+[ ] src/services/inference_router.py  — RunPod httpx call
+[ ] runpod_handler.py  — added to project root
+[ ] spaces/app.py  — uvicorn entrypoint
+[ ] Dockerfile  — has ffmpeg, libgl1, EXPOSE 7860
+[ ] HF Space created + secrets set + pushed
+[ ] RunPod endpoint deployed + endpoint ID noted
+[ ] frontend/.env.local  — NEXT_PUBLIC_API_URL points to HF Space
+[ ] Vercel deploy of frontend/
+
+Smoke tests:
+[ ] GET /health → {"status":"ok"}
+[ ] POST /detect/image (real JPEG) → verdict REAL
+[ ] POST /detect/image (AI PNG)    → verdict FAKE
+[ ] POST /detect/video (MP4 <20MB) → response within 30s
+[ ] POST /detect/video (MP4 >20MB) → routes to RunPod
+```
+

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y \
+    ffmpeg libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV MODEL_CACHE_DIR=/data/models
+ENV TOKENIZERS_PARALLELISM=false
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+CMD ["python", "spaces/app.py"]

README.md

@@ -1,12 +1,19 @@
 ---
-title: Deepdetection
-emoji: 📈
-colorFrom: indigo
-colorTo: purple
+title: GenAI DeepDetect
+emoji: "??"
+colorFrom: gray
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
-license: mit
-short_description: A
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# GenAI-DeepDetect
+
+Docker-based Hugging Face Space for multimodal deepfake detection.
+
+This Space runs the FastAPI service from `src/api/main.py` and exposes:
+
+- `GET /health`
+- `POST /detect/image`
+- `POST /detect/video`

configs/coherence_baseline.yaml

@@ -0,0 +1,44 @@
+# configs/coherence_baseline.yaml
+# Training config for the Coherence (lip-audio sync) engine — Phase 2
+
+engine: coherence
+
+kaggle_datasets:
+  - xhlulu/faceforensics-in-compressed-videos
+  - reubensinclair/celeb-df
+
+kaggle_competitions:
+  - deepfake-detection-challenge   # DFDC — requires competition acceptance
+
+data:
+  processed_dir: /kaggle/working/processed/coherence
+  sources:
+    - mount: /kaggle/input/faceforensics-in-compressed-videos
+    - mount: /kaggle/input/deepfake-detection-challenge
+    - mount: /kaggle/input/celeb-df
+
+preprocess_args:
+  workers:   4
+  max_clips: 20
+
+model:
+  visual_stream: resnet18_truncated_layer3
+  audio_stream:  1d_cnn
+  embed_dim:     256
+  dropout:       0.3
+
+train_args:
+  data_dir:            /kaggle/working/processed/coherence
+  output_dir:          /kaggle/working/checkpoints/coherence
+  epochs:              25
+  batch_size:          16
+  lr:                  1.0e-4
+  weight_decay:        1.0e-4
+  contrastive_weight:  0.1
+  amp:                 true
+  seed:                42
+  patience:            5
+
+targets:
+  val_auc: 0.88
+  eer:     0.15

configs/fingerprint_baseline.yaml

@@ -0,0 +1,46 @@
+# configs/fingerprint_baseline.yaml
+# Training config for the Fingerprint (ViT) engine — Phase 1
+
+engine: fingerprint
+
+kaggle_datasets:
+  - xhlulu/140k-real-and-fake-faces
+  - philosopher0/ai-generated-vs-real-images-datasaet
+
+kaggle_competitions: []
+
+data:
+  processed_dir: /kaggle/working/processed/fingerprint
+  sources:
+    - slug: xhlulu/140k-real-and-fake-faces
+      mount: /kaggle/input/140k-real-and-fake-faces
+    - slug: philosopher0/ai-generated-vs-real-images-datasaet
+      mount: /kaggle/input/ai-generated-vs-real-images-datasaet
+
+model:
+  name: vit_base_patch16_224
+  pretrained: true
+  num_binary_classes: 2
+  num_generator_classes: 8   # must match GENERATOR_CLASSES in src/training/config.py
+
+train_args:
+  data_dir:    /kaggle/working/processed/fingerprint
+  output_dir:  /kaggle/working/checkpoints/fingerprint
+  epochs:      30
+  batch_size:  64
+  lr:          2.0e-5
+  weight_decay: 0.01
+  warmup_steps: 500
+  grad_accum:  2
+  amp:         true
+  seed:        42
+  patience:    5
+
+demo_args:
+  epochs:     5
+  batch_size: 64
+
+targets:
+  val_auc:             0.92
+  test_auc:            0.90
+  cross_dataset_auc:   0.80

configs/sstgnn_baseline.yaml

@@ -0,0 +1,49 @@
+# configs/sstgnn_baseline.yaml
+# Training config for the SSTGNN (graph attention) engine — Phase 3
+#
+# IMPORTANT: use T4x2 accelerator, NOT P100.
+# Do NOT set amp: true — mixed precision causes NaN in GAT layers.
+
+engine: sstgnn
+
+kaggle_datasets:
+  - xhlulu/faceforensics-in-compressed-videos
+  - reubensinclair/celeb-df
+
+kaggle_competitions:
+  - deepfake-detection-challenge
+
+data:
+  processed_dir: /kaggle/working/processed/sstgnn
+
+landmark_args:
+  window_frames: 64
+  window_stride: 32
+  num_landmarks: 68
+  min_detection_confidence: 0.3   # FIX: was 0.5 — too strict for DFDC low-res
+  min_tracking_confidence:  0.3
+  min_video_height:         240
+
+model:
+  in_channels:    5
+  hidden_dim:     64
+  heads:          4
+  num_gat_layers: 3
+  dropout:        0.3
+  out_dropout:    0.4
+
+train_args:
+  data_dir:     /kaggle/working/processed/sstgnn
+  output_dir:   /kaggle/working/checkpoints/sstgnn
+  epochs:       40
+  batch_size:   8
+  lr:           5.0e-4
+  weight_decay: 5.0e-4
+  scheduler:    cosine
+  seed:         42
+  patience:     8
+  amp:          false   # NEVER set true for SSTGNN
+
+targets:
+  val_auc: 0.85
+  test_auc: 0.83

frontend/Dockerfile

@@ -0,0 +1,25 @@
+# Stage 1 — install deps
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+# Stage 2 — build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+# Stage 3 — runtime
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+COPY --from=builder /app/.next          ./.next
+COPY --from=builder /app/node_modules   ./node_modules
+COPY --from=builder /app/package.json   ./package.json
+COPY --from=builder /app/public         ./public
+
+EXPOSE 3000
+CMD ["npm", "start"]

frontend/components/ui/background-paths.tsx

@@ -0,0 +1,50 @@
+'use client'
+
+interface Props {
+  opacity?: number
+}
+
+export default function BackgroundPaths({ opacity = 0.04 }: Props) {
+  return (
+    <div
+      className="absolute inset-0 pointer-events-none overflow-hidden"
+      aria-hidden="true"
+      style={{ opacity }}
+    >
+      <svg
+        className="w-full h-full"
+        xmlns="http://www.w3.org/2000/svg"
+        preserveAspectRatio="xMidYMid slice"
+      >
+        <defs>
+          <pattern
+            id="grid-pattern"
+            width="48"
+            height="48"
+            patternUnits="userSpaceOnUse"
+          >
+            <path
+              d="M 48 0 L 0 0 0 48"
+              fill="none"
+              stroke="#f2f2f2"
+              strokeWidth="0.5"
+            />
+          </pattern>
+          <radialGradient id="fade-radial" cx="50%" cy="50%" r="50%">
+            <stop offset="0%"   stopColor="#f2f2f2" stopOpacity="1" />
+            <stop offset="100%" stopColor="#f2f2f2" stopOpacity="0" />
+          </radialGradient>
+          <mask id="fade-mask">
+            <rect width="100%" height="100%" fill="url(#fade-radial)" />
+          </mask>
+        </defs>
+        <rect
+          width="100%"
+          height="100%"
+          fill="url(#grid-pattern)"
+          mask="url(#fade-mask)"
+        />
+      </svg>
+    </div>
+  )
+}

frontend/components/ui/confidence-ring.tsx

@@ -0,0 +1,67 @@
+import { motion } from 'framer-motion'
+import type { Verdict } from '@/types/detection'
+import { formatConfidence } from '@/lib/utils'
+
+interface Props {
+  confidence: number
+  verdict:    Verdict
+}
+
+const RADIUS    = 36
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS
+
+export default function ConfidenceRing({ confidence, verdict }: Props) {
+  const dashOffset = CIRCUMFERENCE * (1 - confidence)
+  const color      = verdict === 'FAKE' ? '#ef4444' : '#22c55e'
+  const bgColor    = verdict === 'FAKE' ? 'rgba(239,68,68,0.1)' : 'rgba(34,197,94,0.08)'
+
+  return (
+    <div
+      className="bg-brand-surface border border-brand-borderHi rounded-lg px-4 py-3.5 flex items-center gap-4"
+      style={{ background: bgColor }}
+    >
+      {/* SVG ring */}
+      <div className="relative shrink-0">
+        <svg width="88" height="88" viewBox="0 0 88 88">
+          {/* Track */}
+          <circle
+            cx="44" cy="44" r={RADIUS}
+            fill="none"
+            stroke="rgba(255,255,255,0.06)"
+            strokeWidth="5"
+          />
+          {/* Progress */}
+          <motion.circle
+            cx="44" cy="44" r={RADIUS}
+            fill="none"
+            stroke={color}
+            strokeWidth="5"
+            strokeLinecap="round"
+            strokeDasharray={CIRCUMFERENCE}
+            initial={{ strokeDashoffset: CIRCUMFERENCE }}
+            animate={{ strokeDashoffset: dashOffset }}
+            transition={{ duration: 0.7, ease: 'easeOut' }}
+            style={{ transform: 'rotate(-90deg)', transformOrigin: '50% 50%' }}
+          />
+        </svg>
+        <div className="absolute inset-0 flex flex-col items-center justify-center">
+          <span className="font-mono text-[13px] font-medium text-brand-primary">
+            {Math.round(confidence * 100)}%
+          </span>
+        </div>
+      </div>
+
+      <div>
+        <div className="font-mono text-[9px] tracking-[0.12em] uppercase text-brand-muted mb-1">
+          Confidence
+        </div>
+        <div className="text-[22px] font-light tracking-[-0.02em] text-brand-primary leading-none">
+          {formatConfidence(confidence)}
+        </div>
+        <div className="text-[11px] text-brand-secondary mt-0.5">
+          overall {verdict.toLowerCase()} confidence
+        </div>
+      </div>
+    </div>
+  )
+}

frontend/components/ui/engine-breakdown.tsx

@@ -0,0 +1,66 @@
+import { motion } from 'framer-motion'
+import type { EngineResult } from '@/types/detection'
+import VerdictBadge from './verdict-badge'
+import { ENGINE_LABELS } from '@/lib/constants'
+import { formatMs } from '@/lib/utils'
+
+interface Props {
+  engines: EngineResult[]
+}
+
+export default function EngineBreakdown({ engines }: Props) {
+  return (
+    <div className="flex flex-col gap-2.5">
+      {engines.map((engine, i) => {
+        const isNA = engine.explanation.startsWith('N/A')
+        return (
+          <motion.div
+            key={engine.engine}
+            initial={{ opacity: 0, y: 8 }}
+            animate={{ opacity: 1, y: 0 }}
+            transition={{ delay: i * 0.08, duration: 0.35, ease: 'easeOut' }}
+            className="bg-brand-surface border border-brand-borderHi rounded-lg px-4 py-3 flex items-center gap-3"
+          >
+            {/* Engine name */}
+            <span className="font-mono text-[9px] tracking-[0.12em] uppercase text-brand-secondary w-24 shrink-0">
+              {ENGINE_LABELS[engine.engine] ?? engine.engine.toUpperCase()}
+            </span>
+
+            {/* Verdict badge or NA */}
+            {isNA ? (
+              <span className="font-mono text-[9px] tracking-[0.08em] text-brand-muted border border-brand-borderHi rounded-[20px] px-2.5 py-1">
+                VIDEO ONLY
+              </span>
+            ) : (
+              <VerdictBadge verdict={engine.verdict} />
+            )}
+
+            {/* Confidence bar */}
+            <div className="flex-1 min-w-0">
+              {!isNA && (
+                <div className="h-[3px] bg-[#1a1a1a] rounded-full overflow-hidden">
+                  <motion.div
+                    className={engine.verdict === 'FAKE' ? 'h-full bg-[#ef4444]/50 rounded-full' : 'h-full bg-[#22c55e]/50 rounded-full'}
+                    initial={{ width: 0 }}
+                    animate={{ width: `${engine.confidence * 100}%` }}
+                    transition={{ duration: 0.6, delay: i * 0.08 + 0.1, ease: 'easeOut' }}
+                  />
+                </div>
+              )}
+            </div>
+
+            {/* Score */}
+            <span className="font-mono text-[11px] text-brand-primary w-10 text-right shrink-0">
+              {isNA ? '—' : `${Math.round(engine.confidence * 100)}%`}
+            </span>
+
+            {/* Time */}
+            <span className="font-mono text-[9px] text-brand-muted w-12 text-right shrink-0">
+              {engine.processing_time_ms > 0 ? formatMs(engine.processing_time_ms) : '—'}
+            </span>
+          </motion.div>
+        )
+      })}
+    </div>
+  )
+}

frontend/components/ui/liquid-glass-button.tsx

@@ -0,0 +1,31 @@
+import { cn } from '@/lib/utils'
+import type { ButtonHTMLAttributes } from 'react'
+
+interface Props extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'ghost'
+  size?:    'sm' | 'md'
+}
+
+export default function LiquidGlassButton({
+  children,
+  variant = 'primary',
+  size    = 'md',
+  className,
+  ...rest
+}: Props) {
+  return (
+    <button
+      className={cn(
+        'font-mono tracking-[0.06em] rounded-full border transition-all duration-200 backdrop-blur-sm',
+        size === 'md' ? 'text-[11px] px-6 py-2.5' : 'text-[10px] px-4 py-2',
+        variant === 'primary'
+          ? 'bg-white/[0.08] border-white/[0.2] text-brand-primary hover:bg-white/[0.12] hover:border-white/[0.3]'
+          : 'bg-transparent border-white/[0.1] text-brand-secondary hover:border-white/[0.2] hover:text-brand-primary',
+        className
+      )}
+      {...rest}
+    >
+      {children}
+    </button>
+  )
+}

frontend/components/ui/loading-orbit.tsx

@@ -0,0 +1,67 @@
+import { useState, useEffect } from 'react'
+import { motion, AnimatePresence } from 'framer-motion'
+import { LOADING_STAGES } from '@/lib/constants'
+
+export default function LoadingOrbit() {
+  const [stageIndex, setStageIndex] = useState(0)
+
+  useEffect(() => {
+    const id = setInterval(() => {
+      setStageIndex(i => (i + 1) % LOADING_STAGES.length)
+    }, 2800)
+    return () => clearInterval(id)
+  }, [])
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-10 py-24">
+      {/* Spinning ring */}
+      <div className="relative w-24 h-24 flex items-center justify-center">
+        {/* Static inner circle */}
+        <div className="absolute w-16 h-16 rounded-full bg-brand-surface border border-white/[0.09]" />
+        {/* Outer orbit ring */}
+        <motion.div
+          className="absolute w-24 h-24 rounded-full"
+          style={{
+            border: '1px solid transparent',
+            borderTopColor: 'rgba(255,255,255,0.25)',
+            borderRightColor: 'rgba(255,255,255,0.06)',
+            borderBottomColor: 'rgba(255,255,255,0.06)',
+            borderLeftColor: 'rgba(255,255,255,0.06)',
+          }}
+          animate={{ rotate: 360 }}
+          transition={{ duration: 1.8, ease: 'linear', repeat: Infinity }}
+        />
+        {/* Center label */}
+        <span className="font-mono text-[7px] tracking-[0.1em] text-brand-muted z-10 text-center leading-tight">
+          SCANNING
+        </span>
+      </div>
+
+      {/* Stage label — animates on change */}
+      <AnimatePresence mode="wait">
+        <motion.p
+          key={stageIndex}
+          initial={{ opacity: 0, y: 5 }}
+          animate={{ opacity: 1, y: 0 }}
+          exit={{ opacity: 0, y: -5 }}
+          transition={{ duration: 0.25 }}
+          className="font-mono text-[10px] tracking-[0.22em] text-brand-muted uppercase"
+        >
+          {LOADING_STAGES[stageIndex]}
+        </motion.p>
+      </AnimatePresence>
+
+      {/* Dots */}
+      <div className="flex gap-1.5">
+        {LOADING_STAGES.map((_, i) => (
+          <div
+            key={i}
+            className={`w-1 h-1 rounded-full transition-all duration-300 ${
+              i === stageIndex ? 'bg-brand-secondary scale-125' : 'bg-brand-border'
+            }`}
+          />
+        ))}
+      </div>
+    </div>
+  )
+}

frontend/components/ui/media-meta-strip.tsx

@@ -0,0 +1,23 @@
+import { formatBytes } from '@/lib/utils'
+
+interface Props {
+  file: File
+}
+
+export default function MediaMetaStrip({ file }: Props) {
+  const ext = file.name.split('.').pop()?.toUpperCase() ?? '—'
+
+  return (
+    <div className="bg-brand-surface border border-brand-borderHi rounded-lg px-4 py-3 flex items-center gap-3">
+      <span className="font-mono text-[9px] tracking-[0.12em] uppercase text-brand-muted w-14 shrink-0">
+        File
+      </span>
+      <div className="flex-1 min-w-0">
+        <p className="text-[12px] text-brand-primary truncate">{file.name}</p>
+        <p className="font-mono text-[9px] text-brand-muted mt-0.5 tracking-[0.06em]">
+          {ext} · {formatBytes(file.size)}
+        </p>
+      </div>
+    </div>
+  )
+}

frontend/components/ui/radial-orbital-timeline.tsx

@@ -0,0 +1,73 @@
+import type { LucideIcon } from 'lucide-react'
+
+export interface OrbitalNode {
+  label: string
+  Icon:  LucideIcon
+}
+
+interface Props {
+  nodes:       OrbitalNode[]
+  centerLabel?: string
+  radius?:     number
+  size?:       number
+}
+
+function nodePosition(index: number, total: number, radius: number) {
+  const angle = (Math.PI / 2) - (index * 2 * Math.PI) / total
+  return {
+    x: Math.round(radius * Math.cos(angle)),
+    y: Math.round(-radius * Math.sin(angle)),
+  }
+}
+
+export default function RadialOrbitalTimeline({
+  nodes,
+  centerLabel = 'DETECT',
+  radius      = 140,
+  size        = 320,
+}: Props) {
+  return (
+    <div
+      className="relative flex items-center justify-center"
+      style={{ width: size, height: size }}
+    >
+      {/* Orbit rings */}
+      {[size * 0.875, size * 0.625].map((d, i) => (
+        <div
+          key={d}
+          className="absolute rounded-full border border-white/[0.07]"
+          style={{ width: d, height: d }}
+        />
+      ))}
+
+      {/* Center */}
+      <div
+        className="w-[72px] h-[72px] rounded-full flex flex-col items-center justify-center z-10 border border-white/10"
+        style={{ background: 'linear-gradient(135deg, #595958, #262626)' }}
+      >
+        <span className="font-mono text-[6.5px] tracking-[0.08em] text-brand-secondary text-center leading-relaxed">
+          GENAI<br />{centerLabel}
+        </span>
+      </div>
+
+      {/* Nodes */}
+      {nodes.map((node, i) => {
+        const pos = nodePosition(i, nodes.length, radius)
+        return (
+          <div
+            key={node.label}
+            className="absolute flex flex-col items-center gap-1.5"
+            style={{ transform: `translate(${pos.x}px, ${pos.y}px)` }}
+          >
+            <div className="w-9 h-9 rounded-full bg-brand-surface border border-white/[0.14] flex items-center justify-center">
+              <node.Icon size={13} className="text-brand-secondary" />
+            </div>
+            <span className="font-mono text-[7px] tracking-[0.07em] text-brand-muted whitespace-nowrap">
+              {node.label}
+            </span>
+          </div>
+        )
+      })}
+    </div>
+  )
+}

frontend/components/ui/upload-zone.tsx

@@ -0,0 +1,96 @@
+import { useRef, useState, useCallback } from 'react'
+import { Image as ImageIcon, Film } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import {
+  ALLOWED_IMAGE_TYPES, ALLOWED_VIDEO_TYPES,
+  IMAGE_FORMAT_LABEL, VIDEO_FORMAT_LABEL,
+  MAX_IMAGE_MB, MAX_VIDEO_MB,
+} from '@/lib/constants'
+
+interface Props {
+  mediaType: 'image' | 'video'
+  onFile:    (file: File) => void
+}
+
+export default function UploadZone({ mediaType, onFile }: Props) {
+  const inputRef    = useRef<HTMLInputElement>(null)
+  const [dragging, setDragging]   = useState(false)
+  const [error, setError]         = useState<string | null>(null)
+
+  const accept       = mediaType === 'image' ? ALLOWED_IMAGE_TYPES.join(',') : ALLOWED_VIDEO_TYPES.join(',')
+  const formatLabel  = mediaType === 'image' ? IMAGE_FORMAT_LABEL : VIDEO_FORMAT_LABEL
+  const maxMb        = mediaType === 'image' ? MAX_IMAGE_MB : MAX_VIDEO_MB
+  const Icon         = mediaType === 'image' ? ImageIcon : Film
+
+  const validate = useCallback((file: File): string | null => {
+    const allowed = mediaType === 'image' ? ALLOWED_IMAGE_TYPES : ALLOWED_VIDEO_TYPES
+    if (file.type && !allowed.includes(file.type)) {
+      return `Unsupported format. Allowed: ${formatLabel}`
+    }
+    if (file.size > maxMb * 1024 * 1024) {
+      return `File too large. Max ${maxMb}MB.`
+    }
+    return null
+  }, [mediaType, formatLabel, maxMb])
+
+  const handleFiles = useCallback((files: FileList | null) => {
+    if (!files || files.length === 0) return
+    const file = files[0]
+    const err  = validate(file)
+    if (err) { setError(err); return }
+    setError(null)
+    onFile(file)
+  }, [validate, onFile])
+
+  const onDrop = (e: React.DragEvent) => {
+    e.preventDefault()
+    setDragging(false)
+    handleFiles(e.dataTransfer.files)
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      <label
+        className={cn(
+          'relative border border-dashed rounded-[10px] flex flex-col items-center justify-center',
+          'min-h-[280px] px-8 py-10 gap-2.5 cursor-pointer transition-colors duration-200',
+          dragging
+            ? 'border-white/25 bg-white/[0.025]'
+            : 'border-white/[0.11] hover:border-white/[0.2]'
+        )}
+        onDragOver={e => { e.preventDefault(); setDragging(true) }}
+        onDragLeave={() => setDragging(false)}
+        onDrop={onDrop}
+      >
+        <input
+          ref={inputRef}
+          type="file"
+          className="sr-only"
+          accept={accept}
+          onChange={e => handleFiles(e.target.files)}
+        />
+
+        {/* Icon container */}
+        <div className="w-10 h-10 rounded-lg bg-white/[0.05] border border-white/[0.08] flex items-center justify-center mb-2">
+          <Icon size={16} className="text-brand-muted" />
+        </div>
+
+        <h4 className="text-[13px] font-normal text-brand-primary">
+          Drop {mediaType} here
+        </h4>
+        <p className="text-[11px] text-brand-muted text-center">
+          or click to browse
+        </p>
+        <span className="font-mono text-[9px] text-brand-muted tracking-[0.1em] mt-1">
+          {formatLabel}
+        </span>
+      </label>
+
+      {error && (
+        <p className="font-mono text-[9px] tracking-[0.08em] text-[#fca5a5] px-1">
+          {error}
+        </p>
+      )}
+    </div>
+  )
+}

frontend/components/ui/verdict-badge.tsx

@@ -0,0 +1,23 @@
+import type { Verdict } from '@/types/detection'
+import { cn } from '@/lib/utils'
+
+interface Props {
+  verdict: Verdict
+  size?: 'sm' | 'md'
+}
+
+export default function VerdictBadge({ verdict, size = 'sm' }: Props) {
+  return (
+    <span
+      className={cn(
+        'font-mono font-medium tracking-[0.1em] rounded-[20px] border inline-flex items-center',
+        size === 'sm' ? 'text-[9px] px-2.5 py-1' : 'text-[11px] px-3.5 py-1.5',
+        verdict === 'FAKE'
+          ? 'bg-[rgba(239,68,68,0.15)] border-[rgba(239,68,68,0.3)] text-[#fca5a5]'
+          : 'bg-[rgba(34,197,94,0.10)] border-[rgba(34,197,94,0.25)] text-[#86efac]'
+      )}
+    >
+      {verdict}
+    </span>
+  )
+}

frontend/lib/api.ts

@@ -0,0 +1,33 @@
+// frontend/lib/api.ts
+
+import type { DetectionResponse } from '@/types/detection'
+
+const BASE_URL =
+  process.env.NEXT_PUBLIC_API_URL ??
+  'http://localhost:8000'
+
+async function _post(endpoint: string, file: File): Promise<DetectionResponse> {
+  const form = new FormData()
+  form.append('file', file)
+
+  const res = await fetch(`${BASE_URL}${endpoint}`, {
+    method: 'POST',
+    body: form,
+  })
+
+  if (!res.ok) {
+    const err = await res.text()
+    throw new Error(`Detection failed (${res.status}): ${err}`)
+  }
+
+  return res.json()
+}
+
+export const detectImage = (file: File) => _post('/detect/image', file)
+export const detectVideo = (file: File) => _post('/detect/video', file)
+
+export async function healthCheck(): Promise<{ status: string; version?: string }> {
+  const res = await fetch(`${BASE_URL}/health`)
+  if (!res.ok) throw new Error(`Health check failed: ${res.status}`)
+  return res.json()
+}

frontend/lib/constants.ts

@@ -0,0 +1,46 @@
+// frontend/lib/constants.ts
+
+import type { GeneratorLabel } from '@/types/detection'
+
+export const MAX_IMAGE_MB = 20
+export const MAX_VIDEO_MB = 500
+
+export const ALLOWED_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/webp']
+export const ALLOWED_VIDEO_TYPES = ['video/mp4', 'video/quicktime', 'video/x-msvideo']
+
+export const IMAGE_FORMAT_LABEL = 'JPG - PNG - WEBP - MAX 20MB'
+export const VIDEO_FORMAT_LABEL = 'MP4 - MOV - AVI - MAX 500MB'
+
+export const GENERATOR_LABELS: Record<GeneratorLabel, string> = {
+  real: 'Real',
+  unknown_gan: 'Unknown GAN',
+  stable_diffusion: 'Stable Diffusion',
+  midjourney: 'Midjourney',
+  dall_e: 'DALL-E',
+  flux: 'FLUX',
+  firefly: 'Adobe Firefly',
+  imagen: 'Google Imagen',
+  sora: 'OpenAI Sora',
+}
+
+export const ENGINE_LABELS: Record<string, string> = {
+  fingerprint: 'FINGERPRINT',
+  coherence: 'COHERENCE',
+  sstgnn: 'SSTGNN',
+}
+
+export const ORBITAL_NODES = [
+  { label: 'Image', icon: 'Image' },
+  { label: 'Video', icon: 'Film' },
+  { label: 'Audio', icon: 'Mic' },
+  { label: 'Face Mesh', icon: 'Scan' },
+  { label: 'Generator ID', icon: 'Cpu' },
+  { label: 'Confidence', icon: 'BarChart2' },
+  { label: 'Report', icon: 'FileText' },
+] as const
+
+export const LOADING_STAGES = [
+  'FINGERPRINT SCAN',
+  'COHERENCE CHECK',
+  'GRAPH ANALYSIS',
+] as const

frontend/lib/utils.ts

@@ -0,0 +1,29 @@
+// frontend/lib/utils.ts
+
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B'
+  const k     = 1024
+  const sizes = ['B', 'KB', 'MB', 'GB']
+  const i     = Math.floor(Math.log(bytes) / Math.log(k))
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`
+}
+
+export function formatMs(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+export function formatConfidence(confidence: number): string {
+  return `${(confidence * 100).toFixed(1)}%`
+}
+
+export function clampConfidence(v: number): number {
+  return Math.max(0, Math.min(1, v))
+}

frontend/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.

frontend/next.config.js

@@ -0,0 +1,17 @@
+const path = require('path')
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  outputFileTracingRoot: path.join(__dirname),
+  async rewrites() {
+    return [
+      {
+        source: '/api/:path*',
+        destination: `${process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:8000'}/:path*`,
+      },
+    ]
+  },
+}
+
+module.exports = nextConfig

frontend/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "genai-deepdetect-ui",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "framer-motion": "^12.38.0",
+    "lucide-react": "^0.323.0",
+    "next": "^15.5.14",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tailwind-merge": "^2.2.1",
+    "update": "^0.7.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.5",
+    "@types/react": "^18.2.48",
+    "@types/react-dom": "^18.2.18",
+    "autoprefixer": "^10.4.17",
+    "eslint": "^8.56.0",
+    "eslint-config-next": "^15.5.14",
+    "postcss": "^8.4.33",
+    "tailwindcss": "^3.4.1",
+    "typescript": "^5.3.3"
+  }
+}

frontend/pages/_app.tsx

@@ -0,0 +1,18 @@
+import type { AppProps } from 'next/app'
+import Head from 'next/head'
+import '@/styles/globals.css'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <>
+      <Head>
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="description" content="Multimodal AI-generated content detection — three independent engines, one verdict." />
+        <link rel="icon" href="/favicon.ico" />
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+      </Head>
+      <Component {...pageProps} />
+    </>
+  )
+}

frontend/pages/_document.tsx

@@ -0,0 +1,20 @@
+import { Html, Head, Main, NextScript } from 'next/document'
+
+export default function Document() {
+  return (
+    <Html lang="en">
+      <Head>
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+        <link
+          href="https://fonts.googleapis.com/css2?family=DM+Mono:ital,wght@0,300;0,400;0,500;1,300&family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,300&display=swap"
+          rel="stylesheet"
+        />
+      </Head>
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  )
+}

frontend/pages/analyze.tsx

@@ -0,0 +1,249 @@
+import type { NextPage } from 'next'
+import Head from 'next/head'
+import { useRouter } from 'next/router'
+import { useState, useCallback, useRef } from 'react'
+import { motion, AnimatePresence } from 'framer-motion'
+import { ArrowLeft, Image as ImageIcon, Film } from 'lucide-react'
+import type { AnalysisState, DetectionResponse } from '@/types/detection'
+import { detectImage, detectVideo } from '@/lib/api'
+import { formatBytes } from '@/lib/utils'
+import UploadZone from '@/components/ui/upload-zone'
+import LoadingOrbit from '@/components/ui/loading-orbit'
+import VerdictBadge from '@/components/ui/verdict-badge'
+import EngineBreakdown from '@/components/ui/engine-breakdown'
+import MediaMetaStrip from '@/components/ui/media-meta-strip'
+import ConfidenceRing from '@/components/ui/confidence-ring'
+
+const FADE_UP = {
+  initial:    { opacity: 0, y: 14 },
+  animate:    { opacity: 1, y: 0 },
+  transition: { duration: 0.4, ease: [0.25, 0.46, 0.45, 0.94] },
+}
+
+export default function Analyze(): JSX.Element {
+  const router = useRouter()
+  const defaultType = router.query.type === 'video' ? 'video' : 'image'
+  const [mediaType, setMediaType] = useState<'image' | 'video'>(defaultType)
+  const [state, setState] = useState<AnalysisState>({ status: 'idle' })
+
+  const handleFile = useCallback(async (file: File) => {
+    const preview = URL.createObjectURL(file)
+    setState({ status: 'uploading', file, preview })
+
+    try {
+      setState(s => ({ ...s, status: 'analysing' }))
+      const result = mediaType === 'image'
+        ? await detectImage(file)
+        : await detectVideo(file)
+      setState({ status: 'done', file, preview, result })
+    } catch (err) {
+      setState(s => ({
+        ...s,
+        status: 'error',
+        error: err instanceof Error ? err.message : 'Unknown error',
+      }))
+    }
+  }, [mediaType])
+
+  const reset = () => {
+    if (state.preview) URL.revokeObjectURL(state.preview)
+    setState({ status: 'idle' })
+  }
+
+  return (
+    <>
+      <Head>
+        <title>Analyse · GenAI-DeepDetect</title>
+      </Head>
+
+      <main className="min-h-screen bg-brand-bg flex flex-col">
+        {/* Nav */}
+        <nav className="flex items-center gap-4 px-8 py-5 border-b border-brand-border">
+          <button
+            onClick={() => router.push('/')}
+            className="flex items-center gap-2 font-mono text-[10px] tracking-[0.12em] uppercase text-brand-muted hover:text-brand-secondary transition-colors"
+          >
+            <ArrowLeft size={12} />
+            Back
+          </button>
+          <span className="font-mono text-[10px] tracking-[0.2em] uppercase text-brand-muted">
+            /analyze
+          </span>
+
+          {/* Media type toggle */}
+          <div className="ml-auto flex items-center gap-1 bg-brand-surface border border-brand-borderHi rounded-full p-0.5">
+            {(['image', 'video'] as const).map(t => (
+              <button
+                key={t}
+                onClick={() => { setMediaType(t); reset() }}
+                className={`flex items-center gap-1.5 font-mono text-[9px] tracking-[0.08em] uppercase px-3.5 py-1.5 rounded-full transition-all duration-150 ${
+                  mediaType === t
+                    ? 'bg-white/10 text-brand-primary'
+                    : 'text-brand-muted hover:text-brand-secondary'
+                }`}
+              >
+                {t === 'image' ? <ImageIcon size={10} /> : <Film size={10} />}
+                {t}
+              </button>
+            ))}
+          </div>
+        </nav>
+
+        <div className="flex-1 max-w-[900px] w-full mx-auto px-8 py-10">
+
+          {/* IDLE — upload zone */}
+          {state.status === 'idle' && (
+            <motion.div {...FADE_UP} className="grid grid-cols-1 md:grid-cols-2 gap-4">
+              <UploadZone
+                mediaType={mediaType}
+                onFile={handleFile}
+              />
+              {/* Info panel */}
+              <div className="flex flex-col gap-3">
+                {['FINGERPRINT', 'COHERENCE', 'SSTGNN'].map((engine, i) => (
+                  <motion.div
+                    key={engine}
+                    initial={{ opacity: 0, x: 8 }}
+                    animate={{ opacity: 1, x: 0 }}
+                    transition={{ delay: i * 0.07, duration: 0.35 }}
+                    className="bg-brand-surface border border-brand-borderHi rounded-lg px-4 py-3"
+                  >
+                    <div className="font-mono text-[9px] tracking-[0.15em] text-brand-muted mb-1">
+                      {engine}
+                    </div>
+                    <div className="text-[12px] text-brand-secondary font-light">
+                      {engine === 'FINGERPRINT' && 'Frequency-domain artifact analysis via ViT-B/16'}
+                      {engine === 'COHERENCE'   && 'Lip-audio synchronisation scoring (video only)'}
+                      {engine === 'SSTGNN'      && 'Facial landmark trajectory graph attention (video only)'}
+                    </div>
+                  </motion.div>
+                ))}
+              </div>
+            </motion.div>
+          )}
+
+          {/* UPLOADING / ANALYSING — loading orbit */}
+          {(state.status === 'uploading' || state.status === 'analysing') && (
+            <LoadingOrbit />
+          )}
+
+          {/* ERROR */}
+          {state.status === 'error' && (
+            <motion.div {...FADE_UP} className="flex flex-col items-center gap-6 py-20">
+              <div className="font-mono text-[10px] tracking-[0.15em] uppercase text-brand-muted">
+                Error
+              </div>
+              <p className="text-brand-secondary text-center max-w-sm">{state.error}</p>
+              <button
+                onClick={reset}
+                className="font-mono text-[10px] tracking-[0.1em] uppercase px-5 py-2 border border-brand-borderHi rounded-full text-brand-secondary hover:border-brand-muted transition-colors"
+              >
+                Try Again
+              </button>
+            </motion.div>
+          )}
+
+          {/* DONE — results */}
+          {state.status === 'done' && state.result && (
+            <div className="flex flex-col gap-6">
+              {/* Header row */}
+              <motion.div {...FADE_UP} className="flex items-center justify-between">
+                <div className="section-label">Results</div>
+                <button
+                  onClick={reset}
+                  className="font-mono text-[9px] tracking-[0.1em] uppercase text-brand-muted hover:text-brand-secondary border border-brand-borderHi rounded-full px-3.5 py-1.5 transition-colors"
+                >
+                  New analysis
+                </button>
+              </motion.div>
+
+              {/* Preview + stats */}
+              <motion.div
+                {...FADE_UP}
+                transition={{ ...FADE_UP.transition, delay: 0.05 }}
+                className="grid grid-cols-1 md:grid-cols-2 gap-4"
+              >
+                {/* Preview */}
+                <div className="relative bg-brand-surface border border-brand-borderHi rounded-[14px] overflow-hidden aspect-[4/3] flex items-center justify-center">
+                  {state.preview && (
+                    <img
+                      src={state.preview}
+                      alt="Uploaded media"
+                      className="w-full h-full object-cover"
+                    />
+                  )}
+                  {!state.preview && (
+                    <span className="font-mono text-[10px] text-brand-muted tracking-[0.1em]">
+                      PREVIEW
+                    </span>
+                  )}
+                  <div className="absolute top-2.5 right-2.5">
+                    <VerdictBadge verdict={state.result.verdict} />
+                  </div>
+                </div>
+
+                {/* Stats */}
+                <div className="flex flex-col gap-3">
+                  <ConfidenceRing
+                    confidence={state.result.confidence}
+                    verdict={state.result.verdict}
+                  />
+                  <StatPanel
+                    label="Processing time"
+                    value={`${(state.result.processing_time_ms / 1000).toFixed(2)}s`}
+                  />
+                  <StatPanel
+                    label="Generator"
+                    value={state.result.attributed_generator.replace(/_/g, ' ')}
+                    mono
+                  />
+                  {state.file && (
+                    <MediaMetaStrip file={state.file} />
+                  )}
+                </div>
+              </motion.div>
+
+              {/* Engine breakdown */}
+              <motion.div
+                {...FADE_UP}
+                transition={{ ...FADE_UP.transition, delay: 0.1 }}
+              >
+                <div className="section-label mb-4">Engine breakdown</div>
+                <EngineBreakdown engines={state.result.engine_breakdown} />
+              </motion.div>
+
+              {/* Explanation */}
+              <motion.div
+                {...FADE_UP}
+                transition={{ ...FADE_UP.transition, delay: 0.15 }}
+                className="bg-brand-surface border border-brand-borderHi rounded-lg px-5 py-4"
+              >
+                <div className="font-mono text-[9px] tracking-[0.15em] uppercase text-brand-muted mb-2.5">
+                  Analysis detail
+                </div>
+                <p className="text-[13px] text-brand-secondary font-light leading-relaxed">
+                  {state.result.explanation}
+                </p>
+              </motion.div>
+            </div>
+          )}
+        </div>
+      </main>
+    </>
+  )
+}
+
+function StatPanel({
+  label, value, mono = false,
+}: { label: string; value: string; mono?: boolean }) {
+  return (
+    <div className="bg-brand-surface border border-brand-borderHi rounded-lg px-4 py-3">
+      <div className="font-mono text-[9px] tracking-[0.12em] uppercase text-brand-muted mb-1.5">
+        {label}
+      </div>
+      <div className={`text-[20px] font-light tracking-[-0.02em] text-brand-primary ${mono ? 'font-mono text-[14px]' : ''}`}>
+        {value}
+      </div>
+    </div>
+  )
+}

frontend/pages/index.tsx

@@ -0,0 +1,206 @@
+import type { NextPage } from 'next';
+import Head from 'next/head';
+import { useRouter } from 'next/router';
+import { motion } from 'framer-motion';
+import {
+	Image as ImageIcon,
+	Film,
+	Mic,
+	Scan,
+	Cpu,
+	BarChart2,
+	FileText,
+} from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+import { ORBITAL_NODES } from '@/lib/constants';
+
+const ICONS: Record<string, LucideIcon> = {
+	Image: ImageIcon,
+	Film,
+	Mic,
+	Scan,
+	Cpu,
+	BarChart2,
+	FileText,
+};
+
+// Node positions at radius=140 — 7 nodes, 360/7 ≈ 51.4° apart, starting at top (90°)
+function nodePosition(index: number, radius = 140) {
+	const angle = Math.PI / 2 - (index * 2 * Math.PI) / 7;
+	return {
+		x: Math.round(radius * Math.cos(angle)),
+		y: Math.round(-radius * Math.sin(angle)), // flip Y for CSS
+	};
+}
+
+export default function Landing(): JSX.Element {
+	const router = useRouter();
+
+	return (
+		<>
+			<Head>
+				<title>GenAI-DeepDetect — Forensic Detection System</title>
+			</Head>
+
+			<main className="min-h-screen bg-brand-bg flex flex-col">
+				{/* Nav */}
+				<nav className="flex items-center justify-between px-10 py-6 border-b border-brand-border">
+					<span className="font-mono text-[11px] tracking-[0.2em] uppercase text-brand-muted">
+						GenAI-DeepDetect
+					</span>
+					<a
+						href="/docs"
+						className="font-mono text-[10px] tracking-[0.1em] text-brand-muted border border-brand-borderHi rounded-full px-4 py-1.5 hover:border-brand-muted transition-colors">
+						API Docs
+					</a>
+				</nav>
+
+				{/* Hero */}
+				<section className="flex-1 flex flex-col items-center justify-center px-8 py-20 relative overflow-hidden">
+					{/* Background paths */}
+					<div
+						className="absolute inset-0 opacity-[0.06] pointer-events-none"
+						aria-hidden>
+						<svg
+							className="w-full h-full"
+							xmlns="http://www.w3.org/2000/svg">
+							<defs>
+								<pattern
+									id="grid"
+									width="48"
+									height="48"
+									patternUnits="userSpaceOnUse">
+									<path
+										d="M 48 0 L 0 0 0 48"
+										fill="none"
+										stroke="#f2f2f2"
+										strokeWidth="0.5"
+									/>
+								</pattern>
+							</defs>
+							<rect
+								width="100%"
+								height="100%"
+								fill="url(#grid)"
+							/>
+						</svg>
+					</div>
+
+					{/* Eyebrow */}
+					<motion.div
+						initial={{ opacity: 0, y: 8 }}
+						animate={{ opacity: 1, y: 0 }}
+						transition={{ duration: 0.5 }}
+						className="font-mono text-[11px] tracking-[0.2em] uppercase text-brand-muted mb-12">
+						Forensic Detection System
+					</motion.div>
+
+					{/* Orbital diagram */}
+					<motion.div
+						initial={{ opacity: 0, scale: 0.96 }}
+						animate={{ opacity: 1, scale: 1 }}
+						transition={{ duration: 0.6, delay: 0.1 }}
+						className="relative w-[320px] h-[320px] flex items-center justify-center mb-14">
+						{/* Orbit rings */}
+						{[280, 200].map((size, i) => (
+							<div
+								key={size}
+								className="absolute rounded-full border border-white/[0.07]"
+								style={{ width: size, height: size }}
+							/>
+						))}
+
+						{/* Center node */}
+						<div
+							className="w-[72px] h-[72px] rounded-full flex flex-col items-center justify-center z-10 border border-white/10"
+							style={{
+								background:
+									'linear-gradient(135deg, #595958, #262626)',
+							}}>
+							<span className="font-mono text-[6.5px] tracking-[0.08em] text-brand-secondary text-center leading-relaxed">
+								GENAI
+								<br />
+								DETECT
+							</span>
+						</div>
+
+						{/* Orbital nodes */}
+						{ORBITAL_NODES.map((node, i) => {
+							const pos = nodePosition(i);
+							const Icon = ICONS[node.icon];
+							return (
+								<div
+									key={node.label}
+									className="absolute flex flex-col items-center gap-1.5"
+									style={{
+										transform: `translate(${pos.x}px, ${pos.y}px)`,
+									}}>
+									<div className="w-9 h-9 rounded-full bg-brand-surface border border-white/[0.14] flex items-center justify-center">
+										{Icon && (
+											<Icon
+												size={13}
+												className="text-brand-secondary"
+											/>
+										)}
+									</div>
+									<span className="font-mono text-[7px] tracking-[0.07em] text-brand-muted whitespace-nowrap">
+										{node.label}
+									</span>
+								</div>
+							);
+						})}
+					</motion.div>
+
+					{/* Headline */}
+					<motion.h1
+						initial={{ opacity: 0, y: 12 }}
+						animate={{ opacity: 1, y: 0 }}
+						transition={{ duration: 0.5, delay: 0.2 }}
+						className="text-[clamp(36px,5vw,64px)] font-light tracking-[-0.03em] leading-[1.05] text-center text-brand-primary mb-5">
+						Detect AI-Generated
+						<br />
+						<span className="text-brand-secondary">Content</span>
+					</motion.h1>
+
+					<motion.p
+						initial={{ opacity: 0, y: 8 }}
+						animate={{ opacity: 1, y: 0 }}
+						transition={{ duration: 0.5, delay: 0.3 }}
+						className="text-[15px] font-light text-brand-secondary text-center max-w-[460px] leading-relaxed mb-10">
+						Three independent engines analyse your media for
+						synthetic fingerprints, temporal inconsistencies, and
+						facial landmark anomalies.
+					</motion.p>
+
+					{/* CTAs */}
+					<motion.div
+						initial={{ opacity: 0, y: 8 }}
+						animate={{ opacity: 1, y: 0 }}
+						transition={{ duration: 0.5, delay: 0.4 }}
+						className="flex gap-3">
+						<button
+							onClick={() => router.push('/analyze?type=image')}
+							className="font-mono text-[11px] tracking-[0.06em] px-6 py-2.5 rounded-full border border-white/20 bg-white/[0.08] text-brand-primary hover:bg-white/[0.12] hover:border-white/30 transition-all duration-200 backdrop-blur-sm">
+							Upload Image
+						</button>
+						<button
+							onClick={() => router.push('/analyze?type=video')}
+							className="font-mono text-[11px] tracking-[0.06em] px-6 py-2.5 rounded-full border border-white/10 text-brand-secondary hover:border-white/20 hover:text-brand-primary transition-all duration-200">
+							Upload Video
+						</button>
+					</motion.div>
+				</section>
+
+				{/* Footer */}
+				<footer className="border-t border-brand-border px-10 py-5 flex items-center justify-between">
+					<span className="font-mono text-[9px] tracking-[0.15em] text-brand-border text-[#333]">
+						GENAI-DEEPDETECT · v1.0.0
+					</span>
+					<span className="font-mono text-[9px] text-[#333]">
+						Fingerprint · Coherence · SSTGNN
+					</span>
+				</footer>
+			</main>
+		</>
+	);
+}

frontend/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

frontend/styles/globals.css

@@ -0,0 +1,83 @@
+@import url('https://fonts.googleapis.com/css2?family=DM+Mono:ital,wght@0,300;0,400;0,500;1,300&family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,300&display=swap');
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --c-bg:        #0D0D0D;
+  --c-surface:   #262626;
+  --c-border:    #1A1A1A;
+  --c-border-hi: #2A2A2A;
+  --c-muted:     #595958;
+  --c-secondary: #A6A6A6;
+  --c-primary:   #F2F2F2;
+  --font-sans:   'DM Sans', sans-serif;
+  --font-mono:   'DM Mono', monospace;
+
+  /* Semantic verdict colors */
+  --c-fake-bg:   rgba(239, 68, 68, 0.15);
+  --c-fake-bd:   rgba(239, 68, 68, 0.30);
+  --c-fake-tx:   #fca5a5;
+  --c-real-bg:   rgba(34, 197, 94, 0.10);
+  --c-real-bd:   rgba(34, 197, 94, 0.25);
+  --c-real-tx:   #86efac;
+}
+
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html,
+body {
+  background: var(--c-bg);
+  color: var(--c-primary);
+  font-family: var(--font-sans);
+  font-size: 15px;
+  line-height: 1.7;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Scrollbar */
+::-webkit-scrollbar { width: 4px; }
+::-webkit-scrollbar-track { background: var(--c-bg); }
+::-webkit-scrollbar-thumb { background: var(--c-border-hi); border-radius: 2px; }
+
+/* Focus visible */
+:focus-visible {
+  outline: 1px solid var(--c-muted);
+  outline-offset: 2px;
+}
+
+/* Mono utility */
+.font-mono { font-family: var(--font-mono); }
+
+/* Section label with trailing line */
+.section-label {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--c-muted);
+}
+.section-label::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: #222;
+}
+
+/* Card hover lift */
+.card-interactive {
+  transition: transform 200ms ease, border-color 200ms ease;
+}
+.card-interactive:hover {
+  transform: translateY(-1px);
+  border-color: rgba(255, 255, 255, 0.15);
+}

frontend/tailwind.config.ts

@@ -0,0 +1,51 @@
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+  content: [
+    './pages/**/*.{js,ts,jsx,tsx,mdx}',
+    './components/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          bg:        '#0D0D0D',
+          surface:   '#262626',
+          border:    '#1A1A1A',
+          borderHi:  '#2A2A2A',
+          muted:     '#595958',
+          secondary: '#A6A6A6',
+          primary:   '#F2F2F2',
+        },
+      },
+      fontFamily: {
+        sans: ['DM Sans', 'sans-serif'],
+        mono: ['DM Mono', 'monospace'],
+      },
+      borderRadius: {
+        card:   '14px',
+        panel:  '8px',
+        zone:   '10px',
+        badge:  '20px',
+      },
+      animation: {
+        'spin-slow': 'spin 2s linear infinite',
+        'fade-up':   'fadeUp 0.4s ease-out forwards',
+        'pulse-ring':'pulseRing 2s ease-in-out infinite',
+      },
+      keyframes: {
+        fadeUp: {
+          '0%':   { opacity: '0', transform: 'translateY(12px)' },
+          '100%': { opacity: '1', transform: 'translateY(0)' },
+        },
+        pulseRing: {
+          '0%, 100%': { opacity: '0.4', transform: 'scale(1)' },
+          '50%':      { opacity: '0.8', transform: 'scale(1.04)' },
+        },
+      },
+    },
+  },
+  plugins: [],
+}
+
+export default config

frontend/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "paths": {
+      "@/components/*": ["./components/*"],
+      "@/lib/*": ["./lib/*"],
+      "@/styles/*": ["./styles/*"],
+      "@/types/*": ["./types/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}

frontend/types/detection.ts

@@ -0,0 +1,43 @@
+// frontend/types/detection.ts
+// Types aligned with src/types.py.
+
+export type Verdict = 'FAKE' | 'REAL' | 'UNKNOWN'
+
+export type GeneratorLabel =
+  | 'real'
+  | 'unknown_gan'
+  | 'stable_diffusion'
+  | 'midjourney'
+  | 'dall_e'
+  | 'flux'
+  | 'firefly'
+  | 'imagen'
+  | 'sora'
+
+export interface EngineResult {
+  engine: string
+  verdict: Verdict
+  confidence: number
+  attributed_generator?: GeneratorLabel | string | null
+  explanation: string
+  processing_time_ms: number
+}
+
+export interface DetectionResponse {
+  verdict: Verdict
+  confidence: number
+  attributed_generator: GeneratorLabel | string
+  explanation: string
+  processing_time_ms: number
+  engine_breakdown: EngineResult[]
+}
+
+export type MediaType = 'image' | 'video'
+
+export interface AnalysisState {
+  status: 'idle' | 'uploading' | 'analysing' | 'done' | 'error'
+  file?: File
+  preview?: string
+  result?: DetectionResponse
+  error?: string
+}

frontend/types/framer-motion.d.ts

@@ -0,0 +1 @@
+declare module 'framer-motion';

package-lock.json

@@ -0,0 +1,1268 @@
+{
+  "name": "genai-deepdetect",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "@upstash/context7-mcp": "^2.1.4"
+      }
+    },
+    "node_modules/@hono/node-server": {
+      "version": "1.19.11",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.11.tgz",
+      "integrity": "sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.14.1"
+      },
+      "peerDependencies": {
+        "hono": "^4"
+      }
+    },
+    "node_modules/@modelcontextprotocol/sdk": {
+      "version": "1.28.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.28.0.tgz",
+      "integrity": "sha512-gmloF+i+flI8ouQK7MWW4mOwuMh4RePBuPFAEPC6+pdqyWOUMDOixb6qZ69owLJpz6XmyllCouc4t8YWO+E2Nw==",
+      "license": "MIT",
+      "dependencies": {
+        "@hono/node-server": "^1.19.9",
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1",
+        "content-type": "^1.0.5",
+        "cors": "^2.8.5",
+        "cross-spawn": "^7.0.5",
+        "eventsource": "^3.0.2",
+        "eventsource-parser": "^3.0.0",
+        "express": "^5.2.1",
+        "express-rate-limit": "^8.2.1",
+        "hono": "^4.11.4",
+        "jose": "^6.1.3",
+        "json-schema-typed": "^8.0.2",
+        "pkce-challenge": "^5.0.0",
+        "raw-body": "^3.0.0",
+        "zod": "^3.25 || ^4.0",
+        "zod-to-json-schema": "^3.25.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@cfworker/json-schema": "^4.1.1",
+        "zod": "^3.25 || ^4.0"
+      },
+      "peerDependenciesMeta": {
+        "@cfworker/json-schema": {
+          "optional": true
+        },
+        "zod": {
+          "optional": false
+        }
+      }
+    },
+    "node_modules/@types/body-parser": {
+      "version": "1.19.6",
+      "resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.6.tgz",
+      "integrity": "sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/connect": "*",
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/connect": {
+      "version": "3.4.38",
+      "resolved": "https://registry.npmjs.org/@types/connect/-/connect-3.4.38.tgz",
+      "integrity": "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/express": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@types/express/-/express-5.0.6.tgz",
+      "integrity": "sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/body-parser": "*",
+        "@types/express-serve-static-core": "^5.0.0",
+        "@types/serve-static": "^2"
+      }
+    },
+    "node_modules/@types/express-serve-static-core": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-5.1.1.tgz",
+      "integrity": "sha512-v4zIMr/cX7/d2BpAEX3KNKL/JrT1s43s96lLvvdTmza1oEvDudCqK9aF/djc/SWgy8Yh0h30TZx5VpzqFCxk5A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "@types/qs": "*",
+        "@types/range-parser": "*",
+        "@types/send": "*"
+      }
+    },
+    "node_modules/@types/http-errors": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz",
+      "integrity": "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "25.5.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.5.0.tgz",
+      "integrity": "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.18.0"
+      }
+    },
+    "node_modules/@types/qs": {
+      "version": "6.15.0",
+      "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.0.tgz",
+      "integrity": "sha512-JawvT8iBVWpzTrz3EGw9BTQFg3BQNmwERdKE22vlTxawwtbyUSlMppvZYKLZzB5zgACXdXxbD3m1bXaMqP/9ow==",
+      "license": "MIT"
+    },
+    "node_modules/@types/range-parser": {
+      "version": "1.2.7",
+      "resolved": "https://registry.npmjs.org/@types/range-parser/-/range-parser-1.2.7.tgz",
+      "integrity": "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==",
+      "license": "MIT"
+    },
+    "node_modules/@types/send": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@types/send/-/send-1.2.1.tgz",
+      "integrity": "sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/serve-static": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@types/serve-static/-/serve-static-2.2.0.tgz",
+      "integrity": "sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/http-errors": "*",
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@upstash/context7-mcp": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/@upstash/context7-mcp/-/context7-mcp-2.1.4.tgz",
+      "integrity": "sha512-PZ8ZgA5/tOshHi/7bQxAhbwukJUjmJvFmBtciH7P5IG4WirLEPo+8ieQgCrvwgPkWG5btym9a70iNVTL3IiF3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.25.1",
+        "@types/express": "^5.0.4",
+        "commander": "^14.0.0",
+        "express": "^5.1.0",
+        "jose": "^6.1.3",
+        "undici": "^6.6.3",
+        "zod": "^4.3.4"
+      },
+      "bin": {
+        "context7-mcp": "dist/index.js"
+      }
+    },
+    "node_modules/accepts": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
+      "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==",
+      "license": "MIT",
+      "dependencies": {
+        "mime-types": "^3.0.0",
+        "negotiator": "^1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/ajv": {
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
+      "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ajv-formats": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
+      "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "ajv": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/body-parser": {
+      "version": "2.2.2",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
+      "integrity": "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==",
+      "license": "MIT",
+      "dependencies": {
+        "bytes": "^3.1.2",
+        "content-type": "^1.0.5",
+        "debug": "^4.4.3",
+        "http-errors": "^2.0.0",
+        "iconv-lite": "^0.7.0",
+        "on-finished": "^2.4.1",
+        "qs": "^6.14.1",
+        "raw-body": "^3.0.1",
+        "type-is": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/bytes": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
+      "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/call-bind-apply-helpers": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
+      "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/call-bound": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
+      "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.2",
+        "get-intrinsic": "^1.3.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/commander": {
+      "version": "14.0.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
+      "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/content-disposition": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.0.1.tgz",
+      "integrity": "sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/content-type": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz",
+      "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/cookie": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
+      "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/cookie-signature": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
+      "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.6.0"
+      }
+    },
+    "node_modules/cors": {
+      "version": "2.8.6",
+      "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz",
+      "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==",
+      "license": "MIT",
+      "dependencies": {
+        "object-assign": "^4",
+        "vary": "^1"
+      },
+      "engines": {
+        "node": ">= 0.10"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/depd": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
+      "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/dunder-proto": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
+      "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.1",
+        "es-errors": "^1.3.0",
+        "gopd": "^1.2.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/ee-first": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz",
+      "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
+      "license": "MIT"
+    },
+    "node_modules/encodeurl": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
+      "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/es-define-property": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
+      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-errors": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
+      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-object-atoms": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
+      "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==",
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/escape-html": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
+      "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
+      "license": "MIT"
+    },
+    "node_modules/etag": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz",
+      "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/eventsource": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz",
+      "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==",
+      "license": "MIT",
+      "dependencies": {
+        "eventsource-parser": "^3.0.1"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/eventsource-parser": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.0.6.tgz",
+      "integrity": "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/express": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
+      "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "accepts": "^2.0.0",
+        "body-parser": "^2.2.1",
+        "content-disposition": "^1.0.0",
+        "content-type": "^1.0.5",
+        "cookie": "^0.7.1",
+        "cookie-signature": "^1.2.1",
+        "debug": "^4.4.0",
+        "depd": "^2.0.0",
+        "encodeurl": "^2.0.0",
+        "escape-html": "^1.0.3",
+        "etag": "^1.8.1",
+        "finalhandler": "^2.1.0",
+        "fresh": "^2.0.0",
+        "http-errors": "^2.0.0",
+        "merge-descriptors": "^2.0.0",
+        "mime-types": "^3.0.0",
+        "on-finished": "^2.4.1",
+        "once": "^1.4.0",
+        "parseurl": "^1.3.3",
+        "proxy-addr": "^2.0.7",
+        "qs": "^6.14.0",
+        "range-parser": "^1.2.1",
+        "router": "^2.2.0",
+        "send": "^1.1.0",
+        "serve-static": "^2.2.0",
+        "statuses": "^2.0.1",
+        "type-is": "^2.0.1",
+        "vary": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/express-rate-limit": {
+      "version": "8.3.1",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.3.1.tgz",
+      "integrity": "sha512-D1dKN+cmyPWuvB+G2SREQDzPY1agpBIcTa9sJxOPMCNeH3gwzhqJRDWCXW3gg0y//+LQ/8j52JbMROWyrKdMdw==",
+      "license": "MIT",
+      "dependencies": {
+        "ip-address": "10.1.0"
+      },
+      "engines": {
+        "node": ">= 16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/express-rate-limit"
+      },
+      "peerDependencies": {
+        "express": ">= 4.11"
+      }
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "license": "MIT"
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
+      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/finalhandler": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
+      "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.4.0",
+        "encodeurl": "^2.0.0",
+        "escape-html": "^1.0.3",
+        "on-finished": "^2.4.1",
+        "parseurl": "^1.3.3",
+        "statuses": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 18.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/forwarded": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
+      "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/fresh": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz",
+      "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/function-bind": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
+      "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/get-intrinsic": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
+      "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.2",
+        "es-define-property": "^1.0.1",
+        "es-errors": "^1.3.0",
+        "es-object-atoms": "^1.1.1",
+        "function-bind": "^1.1.2",
+        "get-proto": "^1.0.1",
+        "gopd": "^1.2.0",
+        "has-symbols": "^1.1.0",
+        "hasown": "^2.0.2",
+        "math-intrinsics": "^1.1.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/get-proto": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
+      "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
+      "license": "MIT",
+      "dependencies": {
+        "dunder-proto": "^1.0.1",
+        "es-object-atoms": "^1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/gopd": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
+      "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/has-symbols": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
+      "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/hasown": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
+      "integrity": "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==",
+      "license": "MIT",
+      "dependencies": {
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/hono": {
+      "version": "4.12.9",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.9.tgz",
+      "integrity": "sha512-wy3T8Zm2bsEvxKZM5w21VdHDDcwVS1yUFFY6i8UobSsKfFceT7TOwhbhfKsDyx7tYQlmRM5FLpIuYvNFyjctiA==",
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=16.9.0"
+      }
+    },
+    "node_modules/http-errors": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
+      "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
+      "license": "MIT",
+      "dependencies": {
+        "depd": "~2.0.0",
+        "inherits": "~2.0.4",
+        "setprototypeof": "~1.2.0",
+        "statuses": "~2.0.2",
+        "toidentifier": "~1.0.1"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/iconv-lite": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
+      "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "license": "ISC"
+    },
+    "node_modules/ip-address": {
+      "version": "10.1.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
+      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
+    "node_modules/ipaddr.js": {
+      "version": "1.9.1",
+      "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
+      "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
+    "node_modules/is-promise": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
+      "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==",
+      "license": "MIT"
+    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "license": "ISC"
+    },
+    "node_modules/jose": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.2.tgz",
+      "integrity": "sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "license": "MIT"
+    },
+    "node_modules/json-schema-typed": {
+      "version": "8.0.2",
+      "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz",
+      "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/math-intrinsics": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
+      "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/media-typer": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz",
+      "integrity": "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/merge-descriptors": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz",
+      "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/mime-db": {
+      "version": "1.54.0",
+      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz",
+      "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mime-types": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
+      "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
+      "license": "MIT",
+      "dependencies": {
+        "mime-db": "^1.54.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT"
+    },
+    "node_modules/negotiator": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.0.0.tgz",
+      "integrity": "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/object-assign": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
+      "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/object-inspect": {
+      "version": "1.13.4",
+      "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
+      "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/on-finished": {
+      "version": "2.4.1",
+      "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
+      "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==",
+      "license": "MIT",
+      "dependencies": {
+        "ee-first": "1.1.1"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "license": "ISC",
+      "dependencies": {
+        "wrappy": "1"
+      }
+    },
+    "node_modules/parseurl": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
+      "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/path-to-regexp": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.3.0.tgz",
+      "integrity": "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/pkce-challenge": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
+      "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/proxy-addr": {
+      "version": "2.0.7",
+      "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
+      "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==",
+      "license": "MIT",
+      "dependencies": {
+        "forwarded": "0.2.0",
+        "ipaddr.js": "1.9.1"
+      },
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
+    "node_modules/qs": {
+      "version": "6.15.0",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.0.tgz",
+      "integrity": "sha512-mAZTtNCeetKMH+pSjrb76NAM8V9a05I9aBZOHztWy/UqcJdQYNsf59vrRKWnojAT9Y+GbIvoTBC++CPHqpDBhQ==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "side-channel": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=0.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/range-parser": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz",
+      "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/raw-body": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz",
+      "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==",
+      "license": "MIT",
+      "dependencies": {
+        "bytes": "~3.1.2",
+        "http-errors": "~2.0.1",
+        "iconv-lite": "~0.7.0",
+        "unpipe": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/router": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
+      "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.4.0",
+        "depd": "^2.0.0",
+        "is-promise": "^4.0.0",
+        "parseurl": "^1.3.3",
+        "path-to-regexp": "^8.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/safer-buffer": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
+      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+      "license": "MIT"
+    },
+    "node_modules/send": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz",
+      "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.4.3",
+        "encodeurl": "^2.0.0",
+        "escape-html": "^1.0.3",
+        "etag": "^1.8.1",
+        "fresh": "^2.0.0",
+        "http-errors": "^2.0.1",
+        "mime-types": "^3.0.2",
+        "ms": "^2.1.3",
+        "on-finished": "^2.4.1",
+        "range-parser": "^1.2.1",
+        "statuses": "^2.0.2"
+      },
+      "engines": {
+        "node": ">= 18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/serve-static": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz",
+      "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==",
+      "license": "MIT",
+      "dependencies": {
+        "encodeurl": "^2.0.0",
+        "escape-html": "^1.0.3",
+        "parseurl": "^1.3.3",
+        "send": "^1.2.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/setprototypeof": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
+      "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
+      "license": "ISC"
+    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/side-channel": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",
+      "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==",
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "object-inspect": "^1.13.3",
+        "side-channel-list": "^1.0.0",
+        "side-channel-map": "^1.0.1",
+        "side-channel-weakmap": "^1.0.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/side-channel-list": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.0.tgz",
+      "integrity": "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==",
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "object-inspect": "^1.13.3"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/side-channel-map": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
+      "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bound": "^1.0.2",
+        "es-errors": "^1.3.0",
+        "get-intrinsic": "^1.2.5",
+        "object-inspect": "^1.13.3"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/side-channel-weakmap": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
+      "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bound": "^1.0.2",
+        "es-errors": "^1.3.0",
+        "get-intrinsic": "^1.2.5",
+        "object-inspect": "^1.13.3",
+        "side-channel-map": "^1.0.1"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/statuses": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
+      "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/toidentifier": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
+      "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.6"
+      }
+    },
+    "node_modules/type-is": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz",
+      "integrity": "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==",
+      "license": "MIT",
+      "dependencies": {
+        "content-type": "^1.0.5",
+        "media-typer": "^1.1.0",
+        "mime-types": "^3.0.0"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/undici": {
+      "version": "6.24.1",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.24.1.tgz",
+      "integrity": "sha512-sC+b0tB1whOCzbtlx20fx3WgCXwkW627p4EA9uM+/tNNPkSS+eSEld6pAs9nDv7WbY1UUljBMYPtu9BCOrCWKA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.18.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+      "license": "MIT"
+    },
+    "node_modules/unpipe": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
+      "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/vary": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
+      "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
+      "license": "ISC"
+    },
+    "node_modules/zod": {
+      "version": "4.3.6",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
+      "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
+      "license": "MIT",
+      "peer": true,
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    },
+    "node_modules/zod-to-json-schema": {
+      "version": "3.25.1",
+      "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz",
+      "integrity": "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==",
+      "license": "ISC",
+      "peerDependencies": {
+        "zod": "^3.25 || ^4"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@upstash/context7-mcp": "^2.1.4"
+  }
+}

pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+addopts = -p no:tmpdir -p no:cacheprovider --ignore=tests/.tmp
+testpaths = tests
+norecursedirs = .tmp tmp* pytest_tmp node_modules frontend tmp_everything_claude_code

requirements.txt

@@ -0,0 +1,42 @@
+# API
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+python-multipart>=0.0.9
+aiofiles>=23.2.1
+httpx>=0.27.0
+pydantic>=2.7.0
+python-dotenv>=1.0.1
+
+# ML - fingerprint
+transformers>=4.40.0
+timm>=1.0.0
+torch>=2.1.0
+torchvision>=0.16.0
+
+# ML - coherence
+# facenet-pytorch currently has limited support on newer Python versions.
+facenet-pytorch>=2.5.3; python_version < "3.13"
+mediapipe>=0.10.14
+opencv-python-headless>=4.9.0
+
+# ML - sstgnn
+torch-geometric>=2.5.0
+scipy>=1.13.0
+
+# Explainability - Gemini
+google-generativeai>=0.8.0
+
+# HuggingFace
+huggingface-hub>=0.23.0
+
+# RunPod serverless handler
+runpod>=1.6.0
+
+# Continual learning
+apscheduler>=3.10.4
+
+# Utils
+Pillow>=10.3.0
+numpy>=1.26.0; python_version < "3.13"
+numpy>=2.0.0; python_version >= "3.13"
+scikit-learn>=1.5.0

runpod_handler.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import base64
+import io
+import os
+import tempfile
+import time
+
+from PIL import Image
+
+os.environ.setdefault("MODEL_CACHE_DIR", "/tmp/models")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+from src.engines.coherence.engine import CoherenceEngine
+from src.engines.fingerprint.engine import FingerprintEngine
+from src.engines.sstgnn.engine import SSTGNNEngine
+from src.explainability.explainer import explain
+from src.fusion.fuser import fuse
+
+_fp = FingerprintEngine()
+_co = CoherenceEngine()
+_st = SSTGNNEngine()
+
+
+def _extract_frames(video_path: str) -> list:
+    try:
+        import cv2
+    except Exception:
+        return []
+
+    cap = cv2.VideoCapture(video_path)
+    frames = []
+    index = 0
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+        if index % 4 == 0:
+            frames.append(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
+        index += 1
+        if len(frames) >= 300:
+            break
+    cap.release()
+    return frames
+
+
+def handler(job: dict) -> dict:
+    inp = job.get("input", {})
+    encoded = inp.get("data") or inp.get("image_b64")
+    if not encoded:
+        raise ValueError("Missing input.data (base64 payload)")
+
+    raw = base64.b64decode(encoded)
+    media_type = str(inp.get("media_type", "image")).lower()
+
+    t0 = time.perf_counter()
+
+    if media_type == "image":
+        image = Image.open(io.BytesIO(raw)).convert("RGB")
+        fp = _fp.run(image)
+        co = _co.run(image)
+        st = _st.run(image)
+        verdict, conf, generator = fuse([fp, co, st], is_video=False)
+    else:
+        with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as temp:
+            temp.write(raw)
+            tmp_path = temp.name
+
+        try:
+            frames = _extract_frames(tmp_path)
+        finally:
+            os.unlink(tmp_path)
+
+        fp = _fp.run_video(frames)
+        co = _co.run_video(frames)
+        st = _st.run_video(frames)
+        verdict, conf, generator = fuse([fp, co, st], is_video=True)
+
+    engine_results = [fp, co, st]
+    explanation = explain(verdict, conf, engine_results, generator)
+    total_ms = (time.perf_counter() - t0) * 1000
+
+    return {
+        "verdict": verdict,
+        "confidence": conf,
+        "attributed_generator": generator,
+        "explanation": explanation,
+        "processing_time_ms": total_ms,
+        "engine_breakdown": [result.model_dump() for result in engine_results],
+    }
+
+
+try:
+    import runpod  # type: ignore
+except Exception:
+    runpod = None
+
+
+if runpod is not None:
+    runpod.serverless.start({"handler": handler})

scripts/assemble_image_baseline.py

@@ -0,0 +1,37 @@
+"""
+scripts/assemble_image_baseline.py
+
+Assembles the image baseline dataset manifest from multiple prepared source
+directories. Delegates to build_dataset.py with the correct Kaggle input paths.
+
+Kaggle usage:
+  !python scripts/assemble_image_baseline.py \
+    --faces_140k  /kaggle/input/140k-real-and-fake-faces \
+    --ai_vs_real  /kaggle/input/ai-generated-vs-real-images-datasaet \
+    --output_dir  /kaggle/working/processed/fingerprint
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from training.phase1_fingerprint.build_dataset import build, parse_args as _parse
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="Assemble image baseline dataset (Kaggle)")
+    p.add_argument("--faces_140k",    default=None)
+    p.add_argument("--ai_vs_real",    default=None)
+    p.add_argument("--deepfake_real", default=None)
+    p.add_argument("--deepfake_faces",default=None)
+    p.add_argument("--celebdf",       default=None)
+    p.add_argument("--output_dir",    default="/kaggle/working/processed/fingerprint")
+    p.add_argument("--seed",          type=int, default=42)
+    args = p.parse_args()
+    build(args)
+
+
+if __name__ == "__main__":
+    main()

scripts/bootstrap_kaggle_dataset.py

@@ -0,0 +1,72 @@
+"""
+scripts/bootstrap_kaggle_dataset.py
+
+Uploads processed dataset to Kaggle as a private dataset so it can be
+reused across notebook sessions without re-running preprocessing.
+
+Usage (run locally after downloading processed data from Kaggle):
+  python scripts/bootstrap_kaggle_dataset.py \
+    --processed_dir /path/to/processed/fingerprint \
+    --dataset_name  deepdetect-fingerprint-processed \
+    --title         "DeepDetect Fingerprint Processed Dataset"
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main(args: argparse.Namespace) -> None:
+    processed_dir  = Path(args.processed_dir)
+    dataset_name   = args.dataset_name
+    kaggle_username = args.username or os.environ.get("KAGGLE_USERNAME")
+
+    if not kaggle_username:
+        print("ERROR: Kaggle username required. Set --username or KAGGLE_USERNAME env var.")
+        sys.exit(1)
+
+    if not processed_dir.exists():
+        print(f"ERROR: Directory not found: {processed_dir}")
+        sys.exit(1)
+
+    # Write dataset-metadata.json
+    meta = {
+        "title":    args.title,
+        "id":       f"{kaggle_username}/{dataset_name}",
+        "licenses": [{"name": "CC0-1.0"}],
+    }
+    meta_path = processed_dir / "dataset-metadata.json"
+    with open(meta_path, "w") as f:
+        json.dump(meta, f, indent=2)
+
+    print(f"Creating Kaggle dataset: {kaggle_username}/{dataset_name}")
+    result = subprocess.run(
+        ["kaggle", "datasets", "create", "-p", str(processed_dir), "--dir-mode", "zip"],
+        capture_output=True, text=True,
+    )
+
+    if result.returncode == 0:
+        print(f"Dataset created: https://www.kaggle.com/datasets/{kaggle_username}/{dataset_name}")
+    else:
+        print(f"STDOUT: {result.stdout}")
+        print(f"STDERR: {result.stderr}")
+        print("If dataset already exists, use 'kaggle datasets version' to update it.")
+
+    meta_path.unlink()  # clean up
+
+
+def parse_args():
+    p = argparse.ArgumentParser(description="Upload processed dataset to Kaggle")
+    p.add_argument("--processed_dir", required=True)
+    p.add_argument("--dataset_name",  required=True)
+    p.add_argument("--title",         default="DeepDetect Processed Dataset")
+    p.add_argument("--username",      default=None)
+    return p.parse_args()
+
+
+if __name__ == "__main__":
+    main(parse_args())

scripts/demo_smoke_test.py

@@ -0,0 +1,298 @@
+"""
+scripts/demo_smoke_test.py
+
+Prepare demo sample media and run one-command smoke tests against the running API.
+
+Usage:
+  python scripts/demo_smoke_test.py
+  python scripts/demo_smoke_test.py --base-url http://localhost:8000
+
+Environment:
+  DEMO_API_BASE_URL overrides default base URL.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+import httpx
+import numpy as np
+from PIL import Image, ImageDraw
+
+
+LOG_FORMAT = "%(levelname)s: %(message)s"
+logging.basicConfig(level=logging.INFO, format=LOG_FORMAT)
+log = logging.getLogger(__name__)
+
+
+SAMPLE_DIR = Path("data/samples")
+REQUIRED_RESPONSE_KEYS = {
+    "verdict",
+    "confidence",
+    "attributed_generator",
+    "explanation",
+    "processing_time_ms",
+    "engine_breakdown",
+}
+
+
+def _download_file(url: str, output: Path) -> bool:
+    try:
+        with httpx.Client(timeout=20.0, follow_redirects=True) as client:
+            resp = client.get(url)
+            resp.raise_for_status()
+            output.write_bytes(resp.content)
+        return True
+    except Exception as exc:
+        log.warning("Could not download %s (%s)", url, exc)
+        return False
+
+
+def _make_fallback_fake_image(fake_img: Path) -> None:
+    # Synthetic-looking sample (deterministic).
+    fake = Image.new("RGB", (512, 512), (12, 12, 12))
+    draw_fake = ImageDraw.Draw(fake)
+    for i in range(0, 512, 16):
+        color = (40 + (i % 120), 40, 120 + (i % 80))
+        draw_fake.rectangle([i, 0, i + 8, 511], fill=color)
+    draw_fake.ellipse([140, 110, 380, 350], outline=(220, 220, 220), width=4)
+    draw_fake.text((168, 380), "SYNTHETIC SAMPLE", fill=(220, 220, 220))
+    fake.save(fake_img, format="JPEG", quality=95)
+
+
+def _make_fallback_real_image(real_img: Path) -> None:
+    # Natural-looking simple fallback when a real photo cannot be downloaded.
+    arr = np.zeros((512, 512, 3), dtype=np.uint8)
+    for y in range(512):
+        arr[y, :, 0] = np.uint8(200 - y // 4)
+        arr[y, :, 1] = np.uint8(160 - y // 6)
+        arr[y, :, 2] = np.uint8(140 - y // 8)
+    real = Image.fromarray(arr, mode="RGB")
+    draw_real = ImageDraw.Draw(real)
+    draw_real.rectangle([56, 280, 456, 508], outline=(245, 245, 245), width=2)
+    draw_real.text((70, 468), "REAL-LIKE SAMPLE", fill=(245, 245, 245))
+    real.save(real_img, format="JPEG", quality=95)
+
+
+def _prepare_images(
+    sample_dir: Path,
+    refresh: bool = False,
+    use_web_samples: bool = False,
+) -> tuple[Path, Path]:
+    sample_dir.mkdir(parents=True, exist_ok=True)
+    fake_img = sample_dir / "fake_1.jpg"
+    real_img = sample_dir / "real_1.jpg"
+
+    if not refresh and fake_img.exists() and real_img.exists():
+        return fake_img, real_img
+
+    fake_ok = False
+    if use_web_samples:
+        fake_ok = _download_file("https://thispersondoesnotexist.com", fake_img)
+    if not fake_ok:
+        _make_fallback_fake_image(fake_img)
+
+    real_ok = _download_file(
+        "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=512",
+        real_img,
+    )
+    if not real_ok:
+        log.info("Could not download real sample image; using generated fallback real image.")
+        _make_fallback_real_image(real_img)
+
+    return fake_img, real_img
+
+
+def _prepare_video(sample_dir: Path) -> Path:
+    import cv2
+
+    sample_dir.mkdir(parents=True, exist_ok=True)
+    video_path = sample_dir / "demo_1.avi"
+    if video_path.exists() and video_path.stat().st_size > 0:
+        return video_path
+
+    width, height = 512, 512
+    fps = 10.0
+    frames = 40
+
+    fourcc_fn = cast(Any, getattr(cv2, "VideoWriter_fourcc", None))
+    if not callable(fourcc_fn):
+        raise RuntimeError("OpenCV VideoWriter_fourcc is unavailable")
+    fourcc_xvid = cast(int, fourcc_fn(*"XVID"))
+    fourcc_mjpg = cast(int, fourcc_fn(*"MJPG"))
+
+    writer = cv2.VideoWriter(
+        str(video_path), fourcc_xvid, fps, (width, height)
+    )
+    if not writer.isOpened():
+        writer = cv2.VideoWriter(
+            str(video_path), fourcc_mjpg, fps, (width, height)
+        )
+
+    if not writer.isOpened():
+        raise RuntimeError("Could not initialize AVI video writer")
+
+    for i in range(frames):
+        frame = np.zeros((height, width, 3), dtype=np.uint8)
+        # Background gradient animation
+        frame[:, :, 0] = np.uint8((40 + i * 3) % 255)
+        frame[:, :, 1] = np.uint8((20 + i * 2) % 255)
+        frame[:, :, 2] = np.uint8((60 + i * 4) % 255)
+
+        # Moving face-like circle + eyes/mouth
+        cx = int(120 + (i * 8) % 280)
+        cy = 220
+        cv2.circle(frame, (cx, cy), 70, (220, 220, 220), 2)
+        cv2.circle(frame, (cx - 24, cy - 12), 6, (230, 230, 230), -1)
+        cv2.circle(frame, (cx + 24, cy - 12), 6, (230, 230, 230), -1)
+        cv2.ellipse(frame, (cx, cy + 20), (24, 12), 0, 0, 180, (230, 230, 230), 2)
+
+        cv2.putText(
+            frame,
+            "DEMO VIDEO SAMPLE",
+            (110, 470),
+            cv2.FONT_HERSHEY_SIMPLEX,
+            0.8,
+            (245, 245, 245),
+            2,
+            cv2.LINE_AA,
+        )
+        writer.write(frame)
+
+    writer.release()
+
+    if not video_path.exists() or video_path.stat().st_size == 0:
+        raise RuntimeError("Video file was not written")
+
+    return video_path
+
+
+def _validate_response(payload: dict) -> None:
+    missing = REQUIRED_RESPONSE_KEYS - set(payload.keys())
+    if missing:
+        raise ValueError(f"Response missing keys: {sorted(missing)}")
+
+    verdict = payload.get("verdict")
+    confidence = payload.get("confidence")
+
+    if verdict not in {"FAKE", "REAL"}:
+        raise ValueError(f"Invalid verdict: {verdict}")
+    if not isinstance(confidence, (int, float)):
+        raise ValueError("confidence is not numeric")
+    if confidence < 0.0 or confidence > 1.0:
+        raise ValueError(f"confidence out of range: {confidence}")
+
+
+def _post_file(base_url: str, endpoint: str, path: Path, content_type: str) -> dict:
+    with httpx.Client(timeout=60.0) as client:
+        with path.open("rb") as fh:
+            files = {"file": (path.name, fh, content_type)}
+            resp = client.post(f"{base_url}{endpoint}", files=files)
+
+        if resp.status_code != 200:
+            raise RuntimeError(
+                f"{endpoint} returned {resp.status_code}: {resp.text[:300]}"
+            )
+
+        payload = resp.json()
+        _validate_response(payload)
+        return payload
+
+
+def _check_health(base_url: str) -> None:
+    with httpx.Client(timeout=15.0) as client:
+        resp = client.get(f"{base_url}/health")
+        resp.raise_for_status()
+
+
+def run_smoke(
+    base_url: str,
+    refresh_samples: bool = False,
+    use_web_samples: bool = False,
+) -> int:
+    base_url = base_url.rstrip("/")
+    log.info("Using API base URL: %s", base_url)
+
+    _check_health(base_url)
+    log.info("Health check OK")
+
+    fake_img, real_img = _prepare_images(
+        SAMPLE_DIR,
+        refresh=refresh_samples,
+        use_web_samples=use_web_samples,
+    )
+    video = _prepare_video(SAMPLE_DIR)
+
+    image_fake = _post_file(base_url, "/detect/image", fake_img, "image/jpeg")
+    image_real = _post_file(base_url, "/detect/image", real_img, "image/jpeg")
+    video_res = _post_file(base_url, "/detect/video", video, "video/x-msvideo")
+
+    log.info(
+        "Image test 1 (%s): verdict=%s confidence=%.3f generator=%s",
+        fake_img.name,
+        image_fake["verdict"],
+        float(image_fake["confidence"]),
+        image_fake["attributed_generator"],
+    )
+    log.info(
+        "Image test 2 (%s): verdict=%s confidence=%.3f generator=%s",
+        real_img.name,
+        image_real["verdict"],
+        float(image_real["confidence"]),
+        image_real["attributed_generator"],
+    )
+    log.info(
+        "Video test (%s): verdict=%s confidence=%.3f generator=%s",
+        video.name,
+        video_res["verdict"],
+        float(video_res["confidence"]),
+        video_res["attributed_generator"],
+    )
+
+    log.info("Smoke test PASSED")
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Prepare demo media and smoke-test image/video endpoints"
+    )
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("DEMO_API_BASE_URL", "http://localhost:8000"),
+        help="API base URL (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--refresh-samples",
+        action="store_true",
+        help="Re-download/regenerate demo samples instead of reusing existing files",
+    )
+    parser.add_argument(
+        "--use-web-samples",
+        action="store_true",
+        help="Use downloaded web sample for the fake image (less deterministic)",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    base_url = args.base_url
+    try:
+        return run_smoke(
+            base_url,
+            refresh_samples=args.refresh_samples,
+            use_web_samples=args.use_web_samples,
+        )
+    except Exception as exc:
+        log.error("Smoke test FAILED: %s", exc)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/kaggle_train_image_baseline.py

@@ -0,0 +1,235 @@
+"""
+scripts/kaggle_train_image_baseline.py
+
+Self-contained Kaggle training script.
+Paste directly into a Kaggle notebook code cell and run.
+No separate data prep step needed — builds the dataset inline from Kaggle input mounts.
+
+Datasets needed (add via Notebook → Add Data):
+  - xhlulu/140k-real-and-fake-faces
+  - philosopher0/ai-generated-vs-real-images-datasaet
+
+Accelerator: P100 (16GB VRAM)
+"""
+from __future__ import annotations
+
+import os, sys, logging, random, time, csv, shutil, hashlib
+from pathlib import Path
+
+import numpy as np
+import torch
+import torch.nn as nn
+from torch.cuda.amp import GradScaler, autocast
+from torch.utils.data import DataLoader, Dataset, WeightedRandomSampler
+from torchvision import transforms
+from PIL import Image
+from sklearn.metrics import roc_auc_score, accuracy_score
+from tqdm import tqdm
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s  %(message)s")
+log = logging.getLogger(__name__)
+
+# ── Configuration — edit these ────────────────────────────────────────────────
+
+CFG = {
+    "faces_140k":  "/kaggle/input/140k-real-and-fake-faces",
+    "ai_vs_real":  "/kaggle/input/ai-generated-vs-real-images-datasaet",
+    "processed":   "/kaggle/working/processed/fingerprint",
+    "output":      "/kaggle/working/checkpoints/fingerprint",
+    "epochs":      5,        # 5 for demo (~55 min), 30 for full run (~6h)
+    "batch_size":  64,
+    "lr":          2e-5,
+    "amp":         True,
+    "seed":        42,
+    "workers":     2,
+}
+
+torch.manual_seed(CFG["seed"])
+np.random.seed(CFG["seed"])
+random.seed(CFG["seed"])
+
+Path(CFG["processed"]).mkdir(parents=True, exist_ok=True)
+Path(CFG["output"]).mkdir(parents=True, exist_ok=True)
+
+# ── GPU check ────────────────────────────────────────────────────────────────
+
+print(f"PyTorch {torch.__version__} | CUDA {torch.cuda.is_available()}")
+if torch.cuda.is_available():
+    print(f"GPU: {torch.cuda.get_device_name(0)}")
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# ── Dataset build ─────────────────────────────────────────────────────────────
+
+IMG_EXTS = {".jpg", ".jpeg", ".png", ".webp"}
+
+def collect_images(root, label_str):
+    records = []
+    for p in Path(root).rglob("*"):
+        if p.suffix.lower() in IMG_EXTS:
+            records.append((p, label_str))
+    return records
+
+def build_dataset():
+    log.info("Building fingerprint dataset ...")
+    all_records = []
+
+    # 140k faces: has train/real and train/fake folders
+    if Path(CFG["faces_140k"]).exists():
+        for split in ["train", "valid", ""]:
+            for label in ["real", "fake"]:
+                d = Path(CFG["faces_140k"]) / split / label if split else Path(CFG["faces_140k"]) / label
+                if d.exists():
+                    imgs = collect_images(d, label)
+                    all_records.extend(imgs)
+                    log.info(f"  140k/{split or 'root'}/{label}: {len(imgs)}")
+
+    # AI vs real: subfolder name = generator
+    if Path(CFG["ai_vs_real"]).exists():
+        for sub in Path(CFG["ai_vs_real"]).iterdir():
+            if not sub.is_dir(): continue
+            label = "real" if "real" in sub.name.lower() else "fake"
+            imgs  = collect_images(sub, label)
+            all_records.extend(imgs)
+            log.info(f"  ai_vs_real/{sub.name} → {label}: {len(imgs)}")
+
+    random.shuffle(all_records)
+    n       = len(all_records)
+    n_train = int(n * 0.80)
+    n_val   = int(n * 0.10)
+    splits  = {
+        "train": all_records[:n_train],
+        "val":   all_records[n_train:n_train+n_val],
+        "test":  all_records[n_train+n_val:],
+    }
+
+    seen = set()
+    for split, records in splits.items():
+        for src, label in tqdm(records, desc=f"Copying {split}"):
+            h   = hashlib.md5(src.read_bytes()).hexdigest()[:8]
+            dst = Path(CFG["processed"]) / split / label / f"{h}_{src.name}"
+            if h not in seen and not dst.exists():
+                dst.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(src, dst)
+            seen.add(h)
+
+    for split in ["train", "val"]:
+        for label in ["real", "fake"]:
+            count = len(list((Path(CFG["processed"]) / split / label).glob("*")))
+            log.info(f"  {split}/{label}: {count}")
+
+build_dataset()
+
+# ── Transforms ────────────────────────────────────────────────────────────────
+
+MEAN, STD = [0.485, 0.456, 0.406], [0.229, 0.224, 0.225]
+TRAIN_TF  = transforms.Compose([
+    transforms.RandomResizedCrop(224, scale=(0.8, 1.0)),
+    transforms.RandomHorizontalFlip(),
+    transforms.ColorJitter(0.2, 0.2, 0.2, 0.1),
+    transforms.ToTensor(),
+    transforms.Normalize(MEAN, STD),
+])
+VAL_TF = transforms.Compose([
+    transforms.Resize(256), transforms.CenterCrop(224),
+    transforms.ToTensor(), transforms.Normalize(MEAN, STD),
+])
+
+# ── Dataset class ──────────────────────────────────────────────────────────────
+
+class ImgDataset(Dataset):
+    def __init__(self, root, split, transform):
+        self.transform = transform
+        self.samples   = []
+        for label, is_fake in [("real", 0), ("fake", 1)]:
+            d = Path(root) / split / label
+            if not d.exists(): continue
+            for p in d.iterdir():
+                if p.suffix.lower() in IMG_EXTS:
+                    self.samples.append((p, is_fake))
+        log.info(f"Dataset [{split}]: {len(self.samples)} images")
+
+    def __len__(self):  return len(self.samples)
+    def __getitem__(self, i):
+        p, label = self.samples[i]
+        img = Image.open(p).convert("RGB")
+        return self.transform(img), label
+
+train_ds  = ImgDataset(CFG["processed"], "train", TRAIN_TF)
+val_ds    = ImgDataset(CFG["processed"], "val",   VAL_TF)
+labels    = [s[1] for s in train_ds.samples]
+n_real    = labels.count(0); n_fake = labels.count(1)
+weights   = [1.0/n_real if l==0 else 1.0/n_fake for l in labels]
+sampler   = WeightedRandomSampler(weights, len(weights), replacement=True)
+train_dl  = DataLoader(train_ds, batch_size=CFG["batch_size"], sampler=sampler,
+                       num_workers=CFG["workers"], pin_memory=True)
+val_dl    = DataLoader(val_ds,   batch_size=CFG["batch_size"]*2, shuffle=False,
+                       num_workers=CFG["workers"], pin_memory=True)
+
+# ── Model ─────────────────────────────────────────────────────────────────────
+
+import timm
+class FingerprintModel(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.backbone       = timm.create_model("vit_base_patch16_224", pretrained=True,
+                                                 num_classes=0, global_pool="token")
+        d                   = self.backbone.num_features
+        self.binary_head    = nn.Sequential(nn.Linear(d, 384), nn.GELU(), nn.Dropout(0.1), nn.Linear(384, 2))
+        self.generator_head = nn.Sequential(nn.Linear(d, 384), nn.GELU(), nn.Dropout(0.1), nn.Linear(384, 8))
+
+    def forward(self, x):
+        f = self.backbone(x)
+        return {"binary_logits": self.binary_head(f), "generator_logits": self.generator_head(f)}
+
+model     = FingerprintModel().to(device)
+cw        = torch.tensor([1.0/n_real, 1.0/n_fake], dtype=torch.float32).to(device)
+criterion = nn.CrossEntropyLoss(weight=cw, label_smoothing=0.05)
+optimizer = torch.optim.AdamW(model.parameters(), lr=CFG["lr"], weight_decay=0.01)
+scaler    = GradScaler(enabled=CFG["amp"])
+
+# ── Training loop ─────────────────────────────────────────────────────────────
+
+best_auc = 0.0
+for epoch in range(CFG["epochs"]):
+    model.train()
+    t0 = time.time()
+    for imgs, labels_b in tqdm(train_dl, desc=f"Train E{epoch+1}", leave=False):
+        imgs, labels_b = imgs.to(device), labels_b.to(device)
+        with autocast(enabled=CFG["amp"]):
+            out  = model(imgs)
+            loss = criterion(out["binary_logits"], labels_b)
+        scaler.scale(loss).backward()
+        scaler.unscale_(optimizer)
+        nn.utils.clip_grad_norm_(model.parameters(), 1.0)
+        scaler.step(optimizer); scaler.update(); optimizer.zero_grad()
+
+    # Validate
+    model.eval()
+    all_probs, all_labels = [], []
+    with torch.no_grad():
+        for imgs, labels_b in tqdm(val_dl, desc="Val", leave=False):
+            imgs = imgs.to(device)
+            out  = model(imgs)
+            probs = torch.softmax(out["binary_logits"], 1)[:, 1].cpu().numpy()
+            all_probs.extend(probs); all_labels.extend(labels_b.numpy())
+
+    auc = roc_auc_score(all_labels, all_probs) if len(set(all_labels)) > 1 else 0.5
+    acc = accuracy_score(all_labels, (np.array(all_probs) > 0.5).astype(int))
+    elapsed = time.time() - t0
+    log.info(f"Epoch {epoch+1}/{CFG['epochs']} | val_auc={auc:.4f} | val_acc={acc:.4f} | {elapsed:.0f}s")
+
+    if auc > best_auc:
+        best_auc = auc
+        ckpt = {
+            "epoch": epoch, "model_state": model.state_dict(),
+            "val_auc": auc, "config": CFG,
+        }
+        torch.save(ckpt, Path(CFG["output"]) / "best.pt")
+        log.info(f"  Saved best.pt (AUC={best_auc:.4f})")
+
+    torch.save({"epoch": epoch, "model_state": model.state_dict(),
+                "val_auc": auc, "config": CFG},
+               Path(CFG["output"]) / "latest.pt")
+
+print(f"\nTraining complete. Best val AUC: {best_auc:.4f}")
+print(f"Download: /kaggle/working/checkpoints/fingerprint/best.pt")

scripts/prepare_cifake.py

@@ -0,0 +1,76 @@
+"""
+scripts/prepare_cifake.py
+
+Prepares the CIFAKE dataset (Kaggle: bird-coder/cifake-real-and-ai-generated-synthetic-images)
+for use in the fingerprint engine training pipeline.
+
+CIFAKE contains 60k real images (CIFAR-10) and 60k AI-generated equivalents.
+Useful as extra training data for the fingerprint engine.
+
+Kaggle usage:
+  !python scripts/prepare_cifake.py \
+    --source  /kaggle/input/cifake-real-and-ai-generated-synthetic-images \
+    --output  /kaggle/working/processed/fingerprint \
+    --max_per_class 20000
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import random
+import shutil
+from pathlib import Path
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s  %(message)s")
+log = logging.getLogger(__name__)
+
+IMG_EXTS = {".jpg", ".jpeg", ".png"}
+
+
+def main(args: argparse.Namespace) -> None:
+    source = Path(args.source)
+    output = Path(args.output)
+    rng    = random.Random(args.seed)
+
+    if not source.exists():
+        log.error(f"Source not found: {source}")
+        return
+
+    for split in ["train", "test"]:
+        for label, is_fake in [("REAL", "real"), ("FAKE", "fake")]:
+            src_dir = source / split / label
+            if not src_dir.exists():
+                src_dir = source / label
+            if not src_dir.exists():
+                log.warning(f"  Not found: {src_dir}")
+                continue
+
+            imgs = [p for p in src_dir.iterdir() if p.suffix.lower() in IMG_EXTS]
+            rng.shuffle(imgs)
+            imgs = imgs[:args.max_per_class]
+
+            out_split = "train" if split == "train" else "val"
+            dst_dir   = output / out_split / is_fake
+            dst_dir.mkdir(parents=True, exist_ok=True)
+
+            for img in imgs:
+                dst = dst_dir / f"cifake_{img.name}"
+                if not dst.exists():
+                    shutil.copy2(img, dst)
+
+            log.info(f"  cifake/{split}/{label} → {out_split}/{is_fake}: {len(imgs)} images")
+
+    log.info("CIFAKE preparation complete.")
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument("--source",        default="/kaggle/input/cifake-real-and-ai-generated-synthetic-images")
+    p.add_argument("--output",        default="/kaggle/working/processed/fingerprint")
+    p.add_argument("--max_per_class", type=int, default=20000)
+    p.add_argument("--seed",          type=int, default=42)
+    return p.parse_args()
+
+
+if __name__ == "__main__":
+    main(parse_args())

scripts/prepare_cocoxgen.py

@@ -0,0 +1,76 @@
+"""
+scripts/prepare_cocoxgen.py
+
+Prepares COCO-XGen dataset for fingerprint engine training.
+Maps COCO real images against XL-generated equivalents for generator attribution training.
+
+Kaggle usage:
+  !python scripts/prepare_cocoxgen.py \
+    --real_source  /kaggle/input/coco-2017-dataset/coco2017/val2017 \
+    --fake_source  /kaggle/input/coco-xgen-synthetic \
+    --output       /kaggle/working/processed/fingerprint \
+    --max          15000
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import random
+import shutil
+from pathlib import Path
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s  %(message)s")
+log = logging.getLogger(__name__)
+
+IMG_EXTS = {".jpg", ".jpeg", ".png"}
+
+
+def copy_subset(src_dir: Path, dst_dir: Path, max_n: int, prefix: str, rng: random.Random) -> int:
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    imgs = [p for p in src_dir.rglob("*") if p.suffix.lower() in IMG_EXTS]
+    rng.shuffle(imgs)
+    imgs = imgs[:max_n]
+    for img in imgs:
+        dst = dst_dir / f"{prefix}_{img.name}"
+        if not dst.exists():
+            shutil.copy2(img, dst)
+    return len(imgs)
+
+
+def main(args: argparse.Namespace) -> None:
+    rng = random.Random(args.seed)
+
+    splits = {"train": int(args.max * 0.9), "val": int(args.max * 0.1)}
+
+    for split, max_n in splits.items():
+        if args.real_source and Path(args.real_source).exists():
+            n = copy_subset(
+                Path(args.real_source),
+                Path(args.output) / split / "real",
+                max_n, "coco", rng
+            )
+            log.info(f"  real/{split}: {n} images")
+
+        if args.fake_source and Path(args.fake_source).exists():
+            n = copy_subset(
+                Path(args.fake_source),
+                Path(args.output) / split / "fake",
+                max_n, "xgen", rng
+            )
+            log.info(f"  fake/{split}: {n} images (generator: stable_diffusion/xl)")
+
+    log.info("COCO-XGen preparation complete.")
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument("--real_source", default=None)
+    p.add_argument("--fake_source", default=None)
+    p.add_argument("--output",      default="/kaggle/working/processed/fingerprint")
+    p.add_argument("--max",         type=int, default=15000)
+    p.add_argument("--seed",        type=int, default=42)
+    return p.parse_args()
+
+
+if __name__ == "__main__":
+    main(parse_args())

scripts/prepare_hf_source.py

@@ -0,0 +1,79 @@
+"""
+scripts/prepare_hf_source.py
+
+Downloads and prepares datasets from HuggingFace Hub for fingerprint engine training.
+Requires: pip install datasets huggingface_hub
+
+Kaggle usage (internet must be enabled in notebook settings):
+  !pip install datasets huggingface_hub -q
+  !python scripts/prepare_hf_source.py \
+    --dataset  elsaEU/ELSA_1M \
+    --split    train \
+    --output   /kaggle/working/processed/fingerprint \
+    --max      10000
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s  %(message)s")
+log = logging.getLogger(__name__)
+
+
+def main(args: argparse.Namespace) -> None:
+    try:
+        from datasets import load_dataset
+    except ImportError:
+        log.error("datasets not installed. Run: pip install datasets")
+        return
+
+    log.info(f"Loading {args.dataset} (split={args.split}, max={args.max}) ...")
+
+    try:
+        ds = load_dataset(args.dataset, split=args.split, streaming=True)
+    except Exception as e:
+        log.error(f"Failed to load dataset: {e}")
+        return
+
+    output = Path(args.output)
+    real_dir = output / "train" / "real"
+    fake_dir = output / "train" / "fake"
+    real_dir.mkdir(parents=True, exist_ok=True)
+    fake_dir.mkdir(parents=True, exist_ok=True)
+
+    n_saved = 0
+    for i, sample in enumerate(ds):
+        if n_saved >= args.max:
+            break
+
+        img   = sample.get("image") or sample.get("img")
+        label = sample.get("label", sample.get("is_fake", 0))
+
+        if img is None:
+            continue
+
+        dst_dir = fake_dir if label else real_dir
+        dst     = dst_dir / f"hf_{i:07d}.jpg"
+        if not dst.exists():
+            img.save(dst, format="JPEG", quality=95)
+        n_saved += 1
+
+        if n_saved % 1000 == 0:
+            log.info(f"  Saved {n_saved}/{args.max} ...")
+
+    log.info(f"HuggingFace source preparation complete. {n_saved} images saved.")
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument("--dataset", default="elsaEU/ELSA_1M")
+    p.add_argument("--split",   default="train")
+    p.add_argument("--output",  default="/kaggle/working/processed/fingerprint")
+    p.add_argument("--max",     type=int, default=10000)
+    return p.parse_args()
+
+
+if __name__ == "__main__":
+    main(parse_args())

scripts/prepare_ifakefakedb.py

@@ -0,0 +1,66 @@
+"""
+scripts/prepare_ifakefakedb.py
+
+Prepares the iFakeFaceDB dataset for fingerprint engine training.
+Kaggle slug: tapakah68/artificial-faces-dataset or similar.
+
+iFakeFaceDB contains ~87k StyleGAN-generated fake faces, useful for
+increasing unknown_gan class coverage.
+
+Kaggle usage:
+  !python scripts/prepare_ifakefakedb.py \
+    --source  /kaggle/input/artificial-faces-dataset \
+    --output  /kaggle/working/processed/fingerprint \
+    --max     20000
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import random
+import shutil
+from pathlib import Path
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s  %(message)s")
+log = logging.getLogger(__name__)
+
+IMG_EXTS = {".jpg", ".jpeg", ".png"}
+
+
+def main(args: argparse.Namespace) -> None:
+    source = Path(args.source)
+    if not source.exists():
+        log.error(f"Source not found: {source}")
+        return
+
+    rng  = random.Random(args.seed)
+    imgs = [p for p in source.rglob("*") if p.suffix.lower() in IMG_EXTS]
+    rng.shuffle(imgs)
+    imgs = imgs[:args.max]
+
+    n_train = int(len(imgs) * 0.85)
+    splits  = {"train": imgs[:n_train], "val": imgs[n_train:]}
+
+    for split, subset in splits.items():
+        dst_dir = Path(args.output) / split / "fake"
+        dst_dir.mkdir(parents=True, exist_ok=True)
+        for img in subset:
+            dst = dst_dir / f"ifake_{img.name}"
+            if not dst.exists():
+                shutil.copy2(img, dst)
+        log.info(f"  {split}/fake: {len(subset)} images (generator: unknown_gan / StyleGAN)")
+
+    log.info("iFakeFaceDB preparation complete.")
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument("--source", default="/kaggle/input/artificial-faces-dataset")
+    p.add_argument("--output", default="/kaggle/working/processed/fingerprint")
+    p.add_argument("--max",    type=int, default=20000)
+    p.add_argument("--seed",   type=int, default=42)
+    return p.parse_args()
+
+
+if __name__ == "__main__":
+    main(parse_args())