GETTING_STARTED.md

# MorphGuard On-Prem Setup & Training Guide

This guide walks you through setting up data sources, training the MorphDetector model, and running the live demo—entirely self-contained via the web UI or automation script.

## Prerequisites
- Linux/Ubuntu 24.04 or compatible
- NVIDIA GPU (e.g., GeForce RTX 5070) with CUDA drivers installed
- Python 3.12 and venv module
- Git, curl, build-essential
- PostgreSQL with TimescaleDB extension (required, for real-time metrics)
- Ethereum node (required, for blockchain verification)

## GPU and CUDA Compatibility

By default, MorphGuard runs all models on the CPU to ensure broad compatibility. If you have an NVIDIA GPU and a PyTorch build that supports your card’s compute capability (e.g., sm_120 for a GeForce RTX 5070), you can enable GPU inference:

```bash
# Install PyTorch:
# - CPU-only (broad compatibility):
pip install torch torchvision torchaudio
# - GPU (CUDA 11.x):
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# - GPU nightly (CUDA 12.x, Python 3.12):
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu122
```

```bash
# Enable GPU mode at runtime:
export USE_CUDA=1
    python app.py
    ```  


### Nightly Preview Builds
If you’re running Python 3.12 and want out-of-the-box support for CUDA 12.2+ (including sm_120 on RTX 5070), you can use the official PyTorch nightly wheels:
```bash
pip3 install --pre \
  --index-url https://download.pytorch.org/whl/nightly/cu122 \
  torch torchvision torchaudio
```
Note: the `cu122` nightly index publishes `cp312` (Python 3.12) wheels. Use a custom wheel server or build PyTorch from source with `TORCH_CUDA_ARCH_LIST="...;12.0"` if needed.
This pulls the latest preview build containing PTX for sm_120 and prebuilt kernels, so GPU inference just works on Python 3.12 today.

If GPU memory is insufficient or your PyTorch install does not support your GPU’s compute capability, the models will automatically fall back to CPU to avoid out-of-memory errors.

## Installation
1. Clone the repository:
   ```bash
   git clone https://github.com/your_org/MorphGuard.git
   cd MorphGuard
   ```
2. Create and activate a virtual environment:
   ```bash
   python3.12 -m venv venv
   source venv/bin/activate
   ```
3. Install Python dependencies:
   ```bash
   pip install --upgrade pip
   # Install PyTorch (choose one):
   # CPU-only:
   pip install torch torchvision torchaudio
   # GPU (CUDA 11.x):
   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
   # GPU nightly (CUDA 12.x, Python 3.12):
   pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu122

   # Install remaining dependencies
   pip install timm flask flask-socketio pillow numpy gradio facenet-pytorch insightface onnxruntime-gpu open3d scikit-learn
   pip install requests sklearn  # for data scripts
   pip install dronekit pymavlink  # for DroneKit/MAVLink integration
   
   # Install TimescaleDB and Ethereum dependencies
   pip install psycopg2-binary  # PostgreSQL driver
   pip install web3 eth-account solcx  # Ethereum and Smart Contract support
   ```

4. Automated setup using the provided script:
   ```bash
   # Executes full setup with all dependencies
   bash setup.sh
   ```

5. Initialize TimescaleDB (if using metrics collection):
   ```bash
   # Install TimescaleDB extension (one-time)
   sudo bash scripts/install_timescaledb.sh
   
   # Initialize or migrate the database schema
   # - Creates hypertables, indexes, retention policies
   # - Applies in-place migrations (e.g. adds missing columns)
   # - Records a schema version to skip on subsequent runs
   python3 scripts/setup_timescaledb.py
   ```
   On first run this may take a few seconds. Subsequent runs detect the recorded schema version
   and immediately skip the setup (printing "Schema is already at version 1, skipping setup.").
   
   If you add new schema changes in the future, bump the `SCHEMA_VERSION` constant in
   `scripts/setup_timescaledb.py` so that the setup script applies only once per version.

6. Set up Ethereum verification (if using blockchain):
   ```bash
   # Deploy smart contract to local Ethereum node
   python ethereum/deploy_contract.py
   ```

## Starting the Flask Server
```bash
# (Optional) Set SoundCloud stream URL for the landing page:
# export SOUNDCLOUD_STREAM_URL="https://soundcloud.com/your_user/your_track"
source venv/bin/activate
python app.py
```  
By default it listens on `0.0.0.0:5000`.

> **Note:** On startup, `app.py` will automatically terminate any process listening on port 5000 before binding, so you can re-run the server without manually freeing the port.

## Automated Verification Script

You can now automatically verify installation, clone 3D scan repositories, launch the server, and check the UI by running:

```bash
bash verify_setup.sh
```

A return code of 0 indicates success; any other code indicates a failure during one of the verification steps.

## Web UI: Data Setup & Training
Browse to:
```
http://localhost:5000/setup?token=<YOUR_TOKEN>
```
Replace `<YOUR_TOKEN>` with the fixed token:
`-api03-S3CYYOvtQ23xP8pt34Gfkv4g_F1iCY6QOD_1PJqZAZ6nLZVXXMQqXLacIXI1swCUzwekjnDYeU9Mho244LT7gw-VkeZowAA`

### Step 1: Save API Keys
Enter/get your keys (persisted to `unsplash_keys.json`):
- **Unsplash Access Key** and **Secret Key**
- **Pexels API Key**

### Step 2: Collect Real Faces
- **Fetch Real Faces** (Unsplash) → `data/train/real/`
 - **Fetch Real Faces** (Unsplash) → `data/train/real/`
- **Fetch Pexels Faces** → `data/train/real/`
- **Fetch LFW Faces** (scikit-learn) → `data/train/real/`
- **Fetch GAN Faces** (ThisPersonDoesNotExist) → `data/train/real/`
- **Fetch UTKFace** (archive download) → `data/train/real/`

### Step 3: Generate Morphs
- **Generate Morphs** → `data/train/morph/`

### Step 4: Prepare Validation Set
- **Fetch Val Real** → `data/val/real/`
- **Generate Val Morphs** → `data/val/morph/`

### Step 5: Start Detector Training
 - Click **Start Detector Training** to launch on-GPU training via `scripts/train_detector.py`
 - Real-time logs stream in the **Logs** panel (left)

### System & Resource Monitoring
 - **Camera Detection**: The UI will list available USB camera indexes under "System Info" (polls `/api/devices/cameras`).  Use these for live video demos.
 - **GPU Utilization**: Live GPU usage (util%, memory used/total) is shown under "System Info" (polls `/api/devices/gpu`).

### Live Training Monitor
 - On the right panel, view:
   - **Training Loss** chart (train vs. val loss per epoch)
   - **Validation Accuracy** chart (val accuracy per epoch)
   - Charts update automatically by polling `/api/train/metrics` every 10 s

### Live Training Monitor
On the right you’ll see:
- **Status**: `not_started` → `running (n/epochs)` → `complete`
- **Loss Chart**: Train vs. Validation loss per epoch
- **Accuracy Chart**: Validation accuracy per epoch

### Step 6: Model Map
- Click the **Model Map** tab in the top navigation of the Setup dashboard.
- Displays an interactive Mermaid.js flowchart illustrating:
  - Inference pipeline (upload → MorphDetector & Demorpher → results)
  - Continuous learning feedback loop (flags → dataset ingestion → thresholded fine-tuning)
  - Offline full training process (via `run_full_training.sh`)
- You can pan, zoom, and explore the chart directly in the browser.

## Training Methodology & Performance

We use supervised deep learning (transfer learning) to train our MorphDetector model as a binary real-vs-morphed face classifier. Key details:

- **Model Architecture**: Fine-tune a pre-trained vision backbone (ResNet-18 by default, or any Vision Transformer from timm) with a lightweight custom classification head.
- **Training Procedure**: Standard multi-epoch back-propagation over labeled data. Default is 20 epochs (each epoch is one full pass over the dataset). No clustering or EM-style algorithms.
- **Validation Accuracy**: Typically 94 – 98% on held-out validation sets after 20 epochs, with most gains occurring in the first 5–10 epochs.
- **Convergence & Logging**: Per-epoch training/validation losses and validation accuracy are recorded to `training_stats.json` (or `models/detector_metrics.json`) and visualized in the “Live Training Monitor”.
- **Inference Latency**: Approximately 100 – 200 ms per 224×224 image on GPU; 300 – 500 ms on CPU.

## Product Demo

## Product Demo
Browse to (if running with default demo token):
```
http://localhost:5000/demo?token=-api03-S3CYYOvtQ23xP8pt34Gfkv4g_F1iCY6QOD_1PJqZAZ6nLZVXXMQqXLacIXI1swCUzwekjnDYeU9Mho244LT7gw-VkeZowAA
```
Or set your own token via the DEMO_TOKEN environment variable before starting the server:
```bash
export DEMO_TOKEN="<YOUR_TOKEN>"
python app.py
```  
Then browse to:
```
http://localhost:5000/demo?token=<YOUR_TOKEN>
```
- **Morph Detection**: upload a face, get `is_morphed`, `confidence`, etc.
 - **Demorphing**: select a demorph method (Transformer, GAN, Diffusion, or LDM), optionally enter a text prompt for LDM, upload a morphed face with an optional reference image, and view the demorphed output image
   - The demo UI now supports text conditioning for latent diffusion demorphing
   - Frequency-domain analysis (Fourier + wavelet) is used under the hood for improved morph detection
- **Liveness Detection**: switch to the “Liveness Detection” tab, upload a face image, and view depth, texture, reflection scores along with overall liveness decision.
- **Identity Verification**: switch to the “Identity Verification” tab, upload a selfie and an ID document, input a user ID and optional MFA code, then view match score, identity label, blockchain transaction ID, and MFA result.
- **User Flagging & Continuous Learning**: after detection or demorphing, click **Flag**, select a reason and the correct label. New examples are ingested into `data/train` and trigger a background fine-tuning job. Check live retrain status at the bottom (polls `/api/demo/retrain_status`).
- **Identity Verification**: enroll faces and verify matches via `/api/verify`
- **Model Export**: export the detector model as ONNX or TorchScript via `/api/model/export`
- **Identity Verification**: enroll user faces and verify matches (`/api/verify` endpoints)

## Orchestration Scripts
MorphGuard provides three ways to bootstrap data, start training, and run end-to-end demos:

### 1. Python API driver (scripts/full_run.py)
Requirements:
- A running Flask server on http://localhost:5000
- Python virtualenv activated

Usage:
```bash
source venv/bin/activate
python scripts/full_run.py --verbose
```
What it does:
- Installs psycopg2-binary, OpenCV, and DroneKit dependencies
- Waits for the server to respond at `/`
- Logs in as admin (POST /login)
- Writes `db_config.json` for TimescaleDB
- Calls all `/api/setup/...` endpoints to fetch UTKFace, LFW, Pexels, Pixabay, Unsplash, and generate morphs
- Starts detector training (POST /api/train/detector)
- Runs a quick camera detection & demorphing test

Use this in CI pipelines or when the server is already running.

### 2. Auto-setup shell (scripts/auto_setup.sh)
Requirements:
- Flask server running on http://localhost:5000
- `curl`, `pip`, and `bash`

Usage:
```bash
bash scripts/auto_setup.sh
```
What it does:
- Logs in via `curl` (admin credentials)
- Installs psycopg2-binary and OpenCV
- Writes `db_config.json`
- Provisions TimescaleDB if needed
- Calls `/api/setup/...` via `curl` to save keys, fetch datasets, and generate morphs
- Starts detector training (POST /api/train/detector)
- Prints a summary and live monitor URL

### 3. One-stop orchestrator (run_full_training.sh)
Requirements:
- Linux/Ubuntu (bash), Python virtualenv

Usage:
```bash
bash run_full_training.sh
```
What it does:
- Kills any process on port 5000
- Launches `python app.py` (Flask server) in the background (logs → `flask.log`)

## Site Structure & Access Policy

### Site Map
- `/` (Landing Page)
  - Background video and interactive overlay.
  - Buttons:
    - "Enter MorphGuard Demo" → `/demo` if logged in; otherwise `/lead`.
    - "Data Setup & Training" → `/setup_page` if admin/approved user; otherwise `/login`.
  - Optional SoundCloud play/pause controls at bottom-left.
- `/lead` (Lead Capture)
  - User lead form for name/email.
- `/lead_submitted` (Lead Confirmation)
  - Confirmation of lead submission.
- `/login` (Login)
  - Admin and approved-user authentication.
- `/demo` (Demo UI)
  - Morph detection and demorphing interface (requires login).
- `/logout`
  - Clear session and redirect to landing.
- `/setup_page` (Data Setup & Training)
  - Data fetching, morph generation, and training hyperparameter UI (requires admin or approved user).
- `/training` (Live Training Monitor)
  - Real-time training metrics (requires login).

### User Access Policy
- `admin` (username "admin") has full access to `/demo`, `/setup_page`, and `/training`.
- `user` accounts (approved users) have the same access as admin.
- `user_lead` accounts (leads) can log in and access `/demo` but are blocked from `/setup_page` and `/training` until approved by an admin:
  1. An admin approves a `user_lead` via the "Users" tab in Setup UI.
  2. Approval generates a password and converts the user to type `user`.
  3. The approved user can then log in and gain full access.
- Invokes `bash scripts/auto_setup.sh` in the background (logs → `setup.log`)
- Enters a 15-minute tail loop on both logs until training completes
- Prints final log excerpts when done

Use this for a fully automated, hands-off workflow: server start, data fetch, training, and log monitoring.


## Next Steps
- Tune `train_detector.py --val-split` or supply custom `data/val` folders
- Control checkpoint retention via `--max-checkpoints` to keep only the most recent N epoch checkpoints (default 5)
- Swap backbones via `--model-name`
- Add demorph‐module training (not yet scaffolded)
- Experiment with `/api/model/export` to generate ONNX/TorchScript for edge deployment

For more details, see `train_detector.py`, `app.py`, and `scripts/data_setup.py`.
## Current Status
The current on-prem demo and training pipeline supports:
  - Web-based data collection from multiple sources (Unsplash, Pexels, Pixabay, LFW, GAN, UTKFace)
  - Automated validation set creation (fetch & morph for `data/val`)
  - Single-click model training with live logs and real-time metrics (loss & accuracy)
  - Interactive demo for morph detection and demorphing via Flask and Chart.js
  - Token-protected admin endpoints and persistent API key storage

## Roadmap: Paid Features and Enterprise Enhancements
We plan to introduce premium capabilities for paying customers:
  1. Multi-tenant user accounts and authentication (OAuth/JWT)
  2. Role-based access control (RBAC) for separation of admin and viewer roles
  3. Quota management and usage billing dashboards
  4. Batch processing API endpoints for bulk image uploads
  5. Audit logs and compliance reporting (GDPR/CCPA)
  6. Custom model training jobs with parameter tuning (per customer)
  7. ONNX export and smaller edge models for on-device inference
  8. Mobile SDKs (iOS/Android) for client-side face capture & detection
  9. Integration plugins for DroneKit/MAVLink to link detection results with drone streams
  10. Advanced demorphing with GAN-based reconstructions and higher resolution outputs
  11. Integration with identity verification workflows (KYC, passport scanners)
  12. SLA-backed on-prem installers with automated updates and monitoring

Contact us for custom enterprise licensing, support, and roadmap prioritization.

## RoadMap: Advanced Demorphing & Pipeline Automation
To leapfrog simple averaging and deliver high-fidelity demorph outputs, MorphGuard now includes a hybrid GAN + Diffusion pipeline.  See `scripts/demorph_pipeline.py` for end-to-end automation.

### B) Demorphing (GAN / Diffusion)
- StyleGAN2 inversion + latent editing:
   • Invert morphed image into StyleGAN2 latent space using pixel2style2pixel (pSp) encoder.
   • Use a learned “identity target” (reference face or average real-face code).
   • Perform a latent-space walk away from the morphed identity and decode back into a demorphed image.
- Conditional GAN (pix2pixHD-style):
   • Train a paired morphed→real generator with adversarial + L1 + perceptual (VGG-face) losses.
   • Incorporate an identity-preservation loss via an ArcFace or FaceNet embedding comparator.
- Diffusion Models:
   • Use Latent Diffusion (LDM) to denoise morphed inputs back to a single identity.
   • Condition denoising on a reference identity embedding for guided reverse diffusion.
- Loss Functions:
   • Perceptual loss (LPIPS) for visual fidelity.
   • Identity loss: minimize cosine distance in embedding space.
   • GAN loss with multi-scale discriminators (patch-GAN).

These approaches, especially a hybrid StyleGAN2 inversion + diffusion + identity-guided loss, represent a significant leap over simple linear averaging—delivering crisp, high-fidelity, identity-preserved outputs that outpace the competition.

### Pipeline Automation
Use the helper script to clone, set up, and run each stage:
```bash
# Install dependencies
pip install omegaconf lpips diffusers transformers

# Clone repos and setup
python scripts/demorph_pipeline.py clone

# Invert a morphed image
python scripts/demorph_pipeline.py invert --input data/train/morph/example.jpg --output static/demorphed/psp_example.png

# Train a pix2pixHD model (requires paired dataset under data/pix2pix)
python scripts/demorph_pipeline.py train_pix2pix --data_dir data/pix2pix

# Run latent diffusion demorphing
python scripts/demorph_pipeline.py run_diffusion --input data/train/morph/example.jpg --output static/demorphed/ldm_example.png
```

After running each step, inspect `static/demorphed/` for results, and iterate on loss weights or model checkpoints for optimal identity compatibility.

### Automatic Retraining on New Data
To continuously improve the detector whenever new images arrive, MorphGuard includes a file-watcher:
```bash
# Starts a background watcher that monitors data/train and data/val directories
# and triggers a new training run when JPEG/PNG files are added.
python scripts/data_watcher.py
```
Enable or disable auto-retrain from the Setup UI via the "Enable Auto-Retrain" checkbox.  All training hyperparameters are persisted in `settings.json` so the watcher reuses your last settings.
---
**Repository Structure**: Development and test files have been moved to the `/Cleaning` directory. The main directory contains only production-ready code for deployment. For development files and backups, see the `/Cleaning` directory structure.