Add model card

README.md

@@ -0,0 +1,83 @@
+---
+license: other
+tags:
+  - image-classification
+  - ai-generated-image-detection
+  - lorc
+  - dinov3
+  - lora
+pipeline_tag: image-classification
+---
+
+# Modulated-LoRC
+
+An [LoRC](https://arxiv.org/abs/2608.20882) (Low-Rank Collapse) AI-generated-image
+detector: a frozen **DINOv3 ViT-H+/16** backbone + LoRA adapters, an orthogonal
+decomposition of the patch tokens against the [CLS] token, and a Low-Rank
+Attention Block on the residual subspace, fine-tuned on the full
+[DDA-Training-Set](https://arxiv.org/abs/2608.20882) (118,287 real/fake
+pairs) with **pair-aware energy augmentation** — a training-time trick that
+randomly rescales each pair's residual-subspace magnitude (simulating
+different image compositions/energy bands) while mathematically guaranteeing
+the real>fake energy ordering *within* every pair is preserved exactly.
+
+This is "run 1": `attn_rank=64`, `lora_rank=32`.
+
+## Why pair-aware, not per-sample
+
+An earlier version of this augmentation drew an independent random scale for
+every image, real and fake alike. That let a real image get scaled down
+while its own paired fake got scaled up in the same batch — a real,
+quantified risk (23.75% instantaneous real/fake energy-inversion rate per
+augmented draw, vs. a 3.80% natural baseline). This checkpoint's training
+draws **one shared scale factor per real/fake pair** instead — proven, not
+just observed, to leave the inversion rate exactly at the 3.80% baseline,
+since scaling both sides of a ratio by the same factor can't flip its sign.
+
+## Results (full 30,000-image WildFake eval)
+
+| | Clean BAcc | Clean AUC | Full (transformed) BAcc | Full AUC |
+|---|---|---|---|---|
+| v2 baseline (no aug) | 95.01% | 0.9911 | 91.92% | 0.9739 |
+| **This checkpoint** | **96.57%** | **0.9929** | **92.65%** | 0.9723 |
+
+Biggest gains: real-photo groups that were previously the model's weakest
+point — celebahq (85.4%→94.7% under transforms), ffhq (84.3%→94.4%). Full
+per-generator breakdown, throughput benchmarks, and training details: see
+`MODULATED_LORC_RUN1_REPORT.md` in the companion GitHub-style repo directory
+(`modulated_lorc_inference/`).
+
+Known regression: Imagen (Google) under transforms, 91.9%→90.9% — the one
+generator where this trick's real-photo gains don't fully offset a drop in
+raw recall on that specific generator (93.7%→86.1%).
+
+## Usage
+
+```bash
+pip install -r requirements.txt   # torch, transformers, peft, huggingface_hub, Pillow
+```
+
+```python
+from inference import ModulatedLoRC
+
+model = ModulatedLoRC.from_pretrained()      # pulls modulated-lorc.pt from this repo
+result = model.predict_image("photo.jpg")
+print(result)   # {"label": "fake", "p_fake": 0.93, "p_real": 0.07}
+```
+
+or from the command line:
+
+```bash
+python inference.py photo.jpg
+```
+
+This repo is **private** — pass a token (`from_pretrained(hf_token="hf_...")`
+or set `HF_TOKEN`/run `huggingface-cli login`) to access it.
+
+## Files
+
+- `modulated-lorc.pt` — the checkpoint. **Partial save**: only the trained
+  LoRA adapters (q/k/v/o_proj, rank=32/α=32), the Low-Rank Attention Block
+  (rank=64), and the classifier head (~124MB total). The frozen DINOv3
+  backbone is not included here — it's pulled fresh from
+  `facebook/dinov3-vith16plus-pretrain-lvd1689m` on first load.