docs: add comprehensive README for Authrix deepfake detection engine

README.md

@@ -1,19 +1,606 @@
+<div align="center">
+
+# 🔍 AUTHRIX
+### AI-Powered Deepfake Detection Engine
+
+[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.111-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
+[![React](https://img.shields.io/badge/React-19-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://react.dev)
+[![HuggingFace](https://img.shields.io/badge/🤗_HuggingFace-ViT_Ensemble-FFD21E?style=for-the-badge)](https://huggingface.co)
+[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://docker.com)
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
+
+**Authrix** is a full-stack, multi-agent deepfake detection platform that analyzes videos for AI-generated content using a Vision Transformer (ViT) ensemble, temporal consistency analysis, C2PA metadata scanning, and AI audio detection — all wrapped in a sleek cyberpunk-themed dashboard and a Chrome extension.
+
+[🚀 Live Demo](https://aarav13-authrix.hf.space) · [🧩 Chrome Extension](#browser-extension) · [📡 API Reference](#api-reference) · [💬 Pricing](#pricing--tiers)
+
+</div>
+
+---
+
+## ✨ Key Features
+
+| Feature | Description |
+|---|---|
+| 🧠 **ViT Ensemble** | 2-model Vision Transformer ensemble (dima806 + prithivMLmods) with float16 batched inference |
+| 🎞️ **Temporal Analysis** | Detects AI video patterns: unnatural motion smoothness, temporal flickering, color drift |
+| 🔏 **C2PA / Metadata Scan** | Identifies AI generator signatures from Veo3, Sora, Runway, Firefly, Kling, etc. |
+| 🔊 **Audio Detection** | Spectral analysis for AI voice synthesis & audio-visual mismatch detection |
+| 🌐 **Browser Extension** | Chrome/Edge extension (MV3) that captures tab video stream for real-time analysis |
+| 🔗 **URL Analysis** | Paste any YouTube/TikTok/Twitter/Instagram URL — powered by yt-dlp |
+| 🔑 **API Key System** | Tiered access control with per-month usage quotas and Stripe billing integration |
+| 🐳 **Docker + Render** | One-command deployment to Render (or any Docker host / HuggingFace Spaces) |
+
+---
+
+## 🏗️ Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        CLIENT LAYER                          │
+│  ┌─────────────────┐  ┌──────────────────┐  ┌────────────┐  │
+│  │  React Frontend │  │ Chrome Extension │  │  REST API  │  │
+│  │  (Vite + TW4)  │  │    (MV3, JS)     │  │  Consumers │  │
+│  └────────┬────────┘  └────────┬─────────┘  └─────┬──────┘  │
+└───────────┼─────────────────── ┼─────────────────── ┼────────┘
+            │                    │                     │
+            ▼                    ▼                     ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      FastAPI BACKEND                         │
+│                                                              │
+│  POST /analyze      POST /analyze-url      GET /health       │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │                  DETECTION PIPELINE                    │  │
+│  │                                                        │  │
+│  │  Agent 0a: Metadata Agent  (C2PA / AI tool scan)       │  │
+│  │  Agent 0b: Temporal Agent  (flicker / motion CV)       │  │
+│  │  Agent 1:  Frame Extractor (dedup, 40-frame sample)    │  │
+│  │  Agent 2:  Face Detector   (MediaPipe, single ctx)     │  │
+│  │  Agent 3:  Decision Agent  (ViT ensemble, float16)     │  │
+│  │  Agent 4:  Report Agent    (calibrated + audio fused)  │  │
+│  │  Agent 5:  Audio Agent     (librosa spectral + AV sync)│  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Detection Pipeline
+
+1. **Metadata Agent** — Binary-scans the first 512 KB + last 64 KB of the video file for C2PA markers, XMP tags, and known AI-generator signatures (Veo, Sora, Runway, Kling, Firefly…). If a C2PA block is found, the file is immediately flagged with 98% confidence.
+
+2. **Temporal Agent** — Measures pixel-level temporal variance, frame-difference coefficient of variation, high-frequency noise consistency, and color-channel drift across frames. Catches modern AI video generators that produce unnaturally smooth motion.
+
+3. **Frame Extractor** — Intelligently samples up to 40 deduplicated frames, skipping near-identical consecutive frames to save inference time.
+
+4. **Face Detector** — MediaPipe face detection runs in a **single context** across all frames (avoids repeated model init) and crops each face with 20% padding.
+
+5. **Decision Agent (ViT Ensemble)** — All face crops are sent to **both ViT models in a single batched forward pass** (float16). Model 2 is early-exited if Model 1 is already very confident (>88% or <12%). Scores are ensemble-weighted 55/45.
+
+6. **Audio Agent** — Extracts audio track via MoviePy/ffmpeg, runs librosa spectral analysis to detect AI voice synthesis, unnatural pitch/tempo regularity, and audio-visual sync mismatches.
+
+7. **Report Agent** — Fuses all signals with an adaptive threshold. A C2PA hard match always wins; audio-visual mismatch overrides visual; otherwise, temporal + visual ensemble determines the final verdict with calibrated confidence.
+
+---
+
+## 🗂️ Project Structure
+
+```
+authrix/
+├── backend/                    # FastAPI backend
+│   ├── main.py                 # App entry point, routes, middleware
+│   ├── detector.py             # Core multi-agent detection engine (all 5 agents)
+│   ├── audio_detector.py       # Audio analysis agent (librosa + AV sync)
+│   ├── auth.py                 # API key validation, tier limits
+│   ├── stripe_integration.py   # Stripe billing hooks
+│   ├── create_owner_key.py     # CLI helper to mint API keys
+│   ├── test_temporal.py        # Unit tests for temporal analysis
+│   ├── requirements.txt        # Python dependencies
+│   └── uploads/                # Temp upload directory (auto-cleaned)
+│
+├── frontend/                   # React 19 + Vite 8 + Tailwind 4 dashboard
+│   ├── src/
+│   │   ├── components/         # UI components (Loader, ResultCard, etc.)
+│   │   └── main.jsx            # App entry
+│   ├── index.html
+│   ├── package.json
+│   └── vite.config.js
+│
+├── frontend-vanilla/           # Vanilla HTML/JS fallback frontend
+│   ├── index.html
+│   ├── pricing.html
+│   └── script.js               # ~15KB — full upload + results UI
+│
+├── extension/                  # Chrome Extension (Manifest V3)
+│   ├── manifest.json           # Permissions, MV3 config
+│   ├── background.js           # Service worker (tab capture)
+│   ├── content.js              # Content script (overlay injection)
+│   ├── offscreen.js            # Offscreen document for MediaRecorder
+│   ├── popup.html / popup.js   # Extension popup UI
+│   ├── overlay.css             # Injected overlay styles
+│   └── icons/                  # Extension icons (16/48/128px)
+│
+├── Dockerfile                  # Multi-stage Docker build
+├── render.yaml                 # Render.com deployment config
+├── setup.sh / setup.bat        # One-command environment setup
+├── start.sh / start.bat        # Dev server launcher
+└── BUSINESS_MODEL.md           # Monetization guide & pricing
+```
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+| Tool | Version | Purpose |
+|---|---|---|
+| Python | 3.11+ | Backend runtime |
+| Node.js | 18+ | Frontend build |
+| npm / pnpm | Latest | JS package manager |
+| ffmpeg | Any | Video conversion (auto-bundled via imageio-ffmpeg) |
+| Docker | 24+ | Containerized deployment (optional) |
+
+> **Windows users:** ffmpeg is bundled via `imageio-ffmpeg` — no manual install required.
+
+---
+
+### Option A — Quick Start (Local Dev)
+
+#### 1. Clone the Repository
+
+```bash
+git clone https://github.com/Aarav-bit/Authrix.git
+cd Authrix
+```
+
+#### 2. Backend Setup
+
+```bash
+cd backend
+python -m venv ../venv
+
+# Activate (Linux/macOS)
+source ../venv/bin/activate
+
+# Activate (Windows)
+..\venv\Scripts\activate
+
+pip install -r requirements.txt
+```
+
+> **Note:** First startup downloads ~2 GB of ViT model weights from HuggingFace. Subsequent starts use the local cache.
+
+#### 3. Start the Backend
+
+```bash
+uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+The API will be live at **http://localhost:8000** and the vanilla frontend will be served automatically.
+
+#### 4. (Optional) Start the React Frontend
+
+```bash
+cd ../frontend
+npm install
+npm run dev
+```
+
+React dashboard available at **http://localhost:5173**.
+
 ---
-title: Authrix Deepfake Detector
-emoji: 🔍
-colorFrom: green
-colorTo: green
-sdk: docker
-pinned: false
-app_port: 7860
+
+### Option B — One-Command Setup Scripts
+
+```bash
+# Linux / macOS
+./setup.sh
+./start.sh
+
+# Windows
+setup.bat
+start.bat
+```
+
 ---
 
-# Authrix — AI Deepfake Detection Engine
+### Option C — Docker
+
+```bash
+# Build image
+docker build -t authrix .
+
+# Run
+docker run -p 7860:7860 authrix
+```
+
+Open **http://localhost:7860**.
+
+---
+
+## 🌐 Deployment
+
+### Render (Recommended)
+
+1. Fork this repository.
+2. Create a new **Web Service** on [Render](https://render.com).
+3. Connect your GitHub repo — Render auto-detects `render.yaml`.
+4. Set env vars (see below).
+5. Deploy. ✅
+
+`render.yaml` configures:
+- Runtime: Docker
+- Health check: `GET /health`
+- Port: `8000`
+
+### HuggingFace Spaces
+
+The `Dockerfile` is pre-configured for HuggingFace Spaces (port 7860, user 1000) and pre-caches both ViT models at build time.
+
+1. Create a new Space → **Docker** runtime.
+2. Push this repo as the Space source.
+3. Models are cached in the image — cold start is instant.
+
+### Manual VPS
+
+```bash
+# Pull latest
+git pull origin main
+
+# Build frontend
+cd frontend && npm run build
+cp -r dist ../frontend-dist
+
+# Install Python deps
+cd ../backend
+pip install -r requirements.txt
+
+# Start with Gunicorn (production)
+uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2
+```
+
+---
+
+## ⚙️ Environment Variables
+
+| Variable | Required | Description | Example |
+|---|---|---|---|
+| `PORT` | No | Port to bind | `8000` |
+| `PYTHONUNBUFFERED` | No | Force stdout flush | `1` |
+| `STRIPE_SECRET_KEY` | Optional | Stripe billing | `sk_live_...` |
+| `STRIPE_WEBHOOK_SECRET` | Optional | Stripe webhooks | `whsec_...` |
+
+> API keys for end-users are stored in `backend/api_keys.json` (auto-generated). No external database required.
+
+---
+
+## 🔑 API Reference
+
+### Base URL
+```
+https://aarav13-authrix.hf.space   (production)
+http://localhost:8000               (local)
+```
+
+### Authentication
+
+Pass your API key as a header. For local development, the key is optional.
+
+```
+X-API-Key: authrix_YOUR_KEY_HERE
+```
+
+---
+
+### `GET /health`
+
+Check server readiness.
+
+```bash
+curl https://aarav13-authrix.hf.space/health
+```
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "model": "Ensemble (2 ViT models)",
+  "ready": true
+}
+```
+
+---
+
+### `POST /analyze`
+
+Analyze an uploaded video file for deepfake content.
+
+```bash
+curl -X POST http://localhost:8000/analyze \
+  -H "X-API-Key: authrix_YOUR_KEY" \
+  -F "file=@/path/to/video.mp4"
+```
+
+**Supported formats:** `.mp4`, `.avi`, `.mov`, `.mkv`, `.webm`, `.wmv`  
+**Max file size:** 100 MB
+
+**Response:**
+```json
+{
+  "result": "FAKE",
+  "confidence": 87.3,
+  "details": {
+    "visual_score": 0.82,
+    "audio_result": "AI_VOICE",
+    "temporal_signals": ["Perfectly uniform motion (CV=0.01)"],
+    "metadata_signals": ["c2pa", "tool:runway"],
+    "face_coverage": 0.92,
+    "frames_analyzed": 38
+  },
+  "frame_timeline": [
+    { "frame_index": 0, "fake_probability": 0.84 },
+    { "frame_index": 5, "fake_probability": 0.79 }
+  ],
+  "metadata": {
+    "frames_analyzed": 38,
+    "frames_with_faces": 35,
+    "video_duration_sec": 12.4,
+    "video_fps": 30.0,
+    "resolution": "1280x720"
+  }
+}
+```
+
+---
+
+### `POST /analyze-url`
+
+Analyze a video from a URL (YouTube, TikTok, Twitter, Instagram, etc.).
+
+```bash
+curl -X POST http://localhost:8000/analyze-url \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://www.youtube.com/watch?v=..."}'
+```
+
+**Response:** Same structure as `/analyze`.
+
+---
+
+### Error Codes
+
+| Status | Meaning |
+|---|---|
+| `400` | Bad request (unsupported format, invalid URL) |
+| `401` | Invalid or missing API key |
+| `413` | File too large (>100 MB) |
+| `429` | Monthly usage limit exceeded |
+| `503` | Server still initializing — retry in 30s |
+
+---
+
+## 💰 Pricing & Tiers
+
+| Tier | Price | Analyses / Month | Features |
+|---|---|---|---|
+| **Free** | $0 | 10 | Extension, 2-min videos, community support |
+| **Pro** | $9.99/mo | 100 | 10-min videos, API access (100 calls), email support |
+| **Business** | $49/mo | 1,000 | Unlimited length, API (5K calls), white-label reports |
+| **Enterprise** | Custom | Unlimited | On-premise, custom training, SLA, dedicated support |
+
+### Pay-Per-Use API
+
+| Video Length | Price |
+|---|---|
+| < 5 min | $0.05 |
+| 5–15 min | $0.10 |
+| > 15 min | $0.25 |
+
+### Generate an API Key (Self-Hosted)
+
+```bash
+cd backend
+python create_owner_key.py
+# Or:
+python -c "from auth import create_api_key; print(create_api_key('you@email.com', 'pro'))"
+```
+
+---
+
+## 🧩 Browser Extension
+
+The Authrix Chrome Extension (v2.2.0, Manifest V3) allows one-click deepfake analysis of any video playing in your browser tab.
+
+### How It Works
+
+1. User clicks the Authrix toolbar icon while a video is playing.
+2. The background service worker uses the `tabCapture` API to start recording the tab's media stream.
+3. An offscreen document captures ~8 seconds of video via `MediaRecorder`.
+4. The clip is posted to the Authrix API and the result is overlaid on the page.
+
+### Install (Developer Mode)
+
+1. Open `chrome://extensions`
+2. Enable **Developer Mode** (top-right toggle)
+3. Click **Load unpacked** → select the `extension/` folder
+4. The Authrix icon appears in your toolbar
+
+### Permissions
+
+| Permission | Reason |
+|---|---|
+| `tabCapture` | Record tab video stream |
+| `scripting` | Inject result overlay |
+| `storage` | Cache API key & usage |
+| `offscreen` | Run MediaRecorder out-of-context |
+| `contextMenus` | Right-click menu |
+
+---
+
+## 🛠️ Development
+
+### Backend
+
+```bash
+# Run with hot-reload
+uvicorn main:app --reload --port 8000
+
+# Run tests
+cd backend
+python test_temporal.py
+
+# Lint
+flake8 . --max-line-length=120
+```
+
+### Frontend (React)
+
+```bash
+cd frontend
+npm run dev      # Dev server with HMR
+npm run build    # Production build → dist/
+npm run lint     # ESLint
+npm run preview  # Preview production build
+```
+
+### Available Scripts Summary
+
+| Command | Description |
+|---|---|
+| `uvicorn main:app --reload` | Backend dev server |
+| `npm run dev` | React frontend dev server |
+| `npm run build` | Build React app for production |
+| `python create_owner_key.py` | Generate a new API key |
+| `docker build -t authrix .` | Build Docker image |
+
+---
+
+## 🔬 Tech Stack
+
+### Backend
+- **FastAPI 0.111** — Async REST API with automatic OpenAPI docs
+- **Python 3.11** — Core runtime
+- **OpenCV 4.9** — Video decoding and frame extraction
+- **MediaPipe 0.10** — Face detection (single-context optimized)
+- **HuggingFace Transformers** — ViT model loading and inference
+- **PyTorch 2.3+** — Float16 batched tensor inference
+- **librosa 0.10** — Audio feature extraction and spectral analysis
+- **imageio-ffmpeg** — Bundled ffmpeg binary for video conversion
+- **yt-dlp** — URL-based video download (YouTube, TikTok, etc.)
+- **Stripe** — Payment processing and subscription management
+
+### Frontend
+- **React 19** — UI library
+- **Vite 8** — Build tool and dev server
+- **Tailwind CSS 4** — Utility-first styling
+- **Three.js + @react-three/fiber** — 3D particle effects
+- **Framer Motion** — Animations
+- **Zustand** — Lightweight state management
+
+### Infrastructure
+- **Docker** — Containerization
+- **Render** — PaaS deployment
+- **HuggingFace Spaces** — Model hosting and demo deployment
+
+### AI Models
+
+| Model | Source | Purpose |
+|---|---|---|
+| `dima806/deepfake_vs_real_image_detection` | HuggingFace | Primary ViT classifier |
+| `prithivMLmods/Deep-Fake-Detector-v2-Model` | HuggingFace | Secondary ViT classifier |
+
+---
+
+## 🔧 Troubleshooting
+
+### Server takes a long time to start
+
+**Cause:** HuggingFace models (~1–2 GB) are being downloaded on first run.  
+**Fix:** Wait ~2–5 minutes. Subsequent starts use the local cache at `~/.cache/huggingface/`.
+
+### `Could not open video` / OpenCV error on Windows
+
+**Cause:** OpenCV on Windows cannot natively decode `.webm` or `.mkv`.  
+**Fix:** The backend automatically converts these via bundled ffmpeg. Ensure `imageio-ffmpeg` is installed:
+```bash
+pip install imageio-ffmpeg
+```
+
+### Extension not sending data to the API
+
+**Cause:** The extension is hard-coded to connect to `http://localhost:8000` (dev) or `https://aarav13-authrix.hf.space` (prod).  
+**Fix:** Update `host_permissions` in `extension/manifest.json` to match your deployment URL, then reload the extension.
+
+### `429 Monthly limit exceeded`
+
+**Cause:** Your API key has hit its monthly quota.  
+**Fix:** Upgrade your plan, or generate a new owner key locally:
+```bash
+python create_owner_key.py
+```
+
+### `503 Server still initializing`
+
+**Cause:** The ViT models haven't finished loading yet.  
+**Fix:** Hit `GET /health` and wait until `"ready": true`, then retry.
+
+### Audio analysis not available
+
+**Cause:** `librosa`, `soundfile`, or `moviepy` not installed, or the video has no audio track.  
+**Fix:**
+```bash
+pip install librosa soundfile moviepy
+```
+
+---
+
+## 🗺️ Roadmap
+
+- [ ] Firefox extension support
+- [ ] Real-time video stream analysis via WebSocket
+- [ ] Mobile app (React Native)
+- [ ] Batch analysis endpoint for enterprise workflows
+- [ ] Webhook notifications for async analysis
+- [ ] GDPR-compliant EU data residency option
+- [ ] On-premise deployment Helm chart
+- [ ] Fine-tuned model on latest Veo3 / Sora outputs
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Commit your changes: `git commit -m 'feat: add my feature'`
+4. Push to the branch: `git push origin feat/my-feature`
+5. Open a Pull Request
+
+Please make sure your code passes linting before submitting.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 📧 Contact
+
+| Channel | Link |
+|---|---|
+| Enterprise Sales | enterprise@authrix.ai |
+| Live Demo | https://aarav13-authrix.hf.space |
+| API Docs | https://aarav13-authrix.hf.space/docs |
+
+---
+
+<div align="center">
+
+**Built with ❤️ by the Authrix Team**
 
-Upload a video and get an instant REAL / FAKE verdict powered by an ensemble of ViT models.
+*Fighting misinformation, one frame at a time.*
 
-## Features
-- Visual deepfake detection (2x ViT ensemble)
-- Audio analysis (AI voice detection)
-- Browser extension support
-- REST API
+</div>