Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,110 @@
 ---
 license: mit
+tags:
+- deepfake-detection
+- ai-generated-image-detection
+- synthetic-media
+- image-forensics
+- computer-vision
+- clip
+- siglip
+base_model:
+- openai/clip-vit-large-patch14
+- google/siglip2-base-patch16-512
+pipeline_tag: image-classification
 ---
+
+# DeepReality: Layer 2 detector weights
+
+Trained weights for the Layer 2 detection core of **DeepReality**, a six-layer
+forensic system for detecting AI-generated and manipulated imagery.
+
+**Source code, documentation and the full pipeline:**
+https://github.com/OmerKurtulus/DeepReality
+
+These files are the three detectors that were trained for the project. They are
+not a standalone classifier: DeepReality reads them as three of fifteen
+independent analysis modules, and its verdict is produced by a reasoning layer
+that weighs them against documentary provenance, compression physics and
+localisation evidence. Used alone, they carry the limitations described below.
+
+## Files
+
+| File | Pin | Size | Architecture |
+|---|---|---|---|
+| `pin_b1_clip_ln_tune_final.pt` | PIN-B1 | 1.6 GB | CLIP ViT-L/14, frozen backbone with LayerNorm tuning |
+| `pin_b2_siglip2_finetune_final.pt` | PIN-B2 | 1.4 GB | SigLIP2-base-patch16-512, full fine-tune |
+| `pin_b3_freq_cnn_final.pt` | PIN-B3 | 19 MB | Frequency CNN over DCT/DWT maps, trained from scratch |
+
+Two further models complete the detection core and are **not** hosted here.
+PIN-B4 is a public third-party checkpoint
+([prithivMLmods/AI-vs-Deepfake-vs-Real-Siglip2](https://huggingface.co/prithivMLmods/AI-vs-Deepfake-vs-Real-Siglip2)),
+and the PIN-F1 XGBoost meta-learner is small enough to be tracked directly in
+the GitHub repository.
+
+## Usage
+
+Download the three files into the `models/` directory of a DeepReality clone:
+
+```bash
+git clone https://github.com/OmerKurtulus/DeepReality.git
+cd DeepReality
+
+hf download OmerKurtulus/deepreality-models --local-dir models
+```
+
+PIN-B1 and PIN-B2 additionally fetch their base architectures from the Hub on
+first run. Placement instructions and the remaining setup are in
+[`models/README.md`](https://github.com/OmerKurtulus/DeepReality/blob/main/models/README.md).
+
+## Training data
+
+All three detectors were trained on **OpenDeepfake-Preview**, 20,000 images.
+
+## Reported performance
+
+Held-out results on the training corpus:
+
+| Pin | Accuracy | ROC-AUC |
+|---|---|---|
+| PIN-B1 | 99.77% | 0.9997 |
+| PIN-B2 | 99.97% | 1.0000 |
+| PIN-B3 | 96.50% | 0.9923 |
+
+## Limitations, and why they matter
+
+**Read the figures above as in-distribution performance. They do not survive a
+change of corpus.** Measured on
+[`ComplexDataLab/OpenFake`](https://huggingface.co/datasets/ComplexDataLab/OpenFake)
+the same detectors fall to 0.51 to 0.84 ROC-AUC. On
+[`Hemg/deepfake-and-real-images`](https://huggingface.co/datasets/Hemg/deepfake-and-real-images)
+all four sit at chance, and PIN-B3 is anti-correlated with the label, which is
+worse than noise because a downstream fusion stage learns to trust it backwards.
+
+This generalisation gap is the reason DeepReality exists. A single detector
+reporting 99% on its own benchmark tells you very little about an unseen
+generator, which is why the system combines paradigms that fail differently and
+subordinates all of them to documentary provenance when provenance is present.
+
+The only figure measured by cross-validation on a corpus none of these detectors
+saw in training is the Layer 6 meta-learner: ROC-AUC 0.8846 at an Expected
+Calibration Error of 0.0203. That is the conservative number, and the one to
+quote.
+
+**Intended use.** Research and assistive review. These weights should not be
+used as the sole basis for a consequential decision about a specific image or
+person.
+
+## Licence and citation
+
+Released under the MIT licence. If you use this work, please cite it:
+
+```bibtex
+@software{kurtulus2026deepreality,
+  author  = {Kurtulus, Omer Faruk},
+  title   = {DeepReality: PIN Architecture for Multi-Layer AI Image Forensics},
+  year    = {2026},
+  url     = {https://github.com/OmerKurtulus/DeepReality},
+  license = {MIT}
+}
+```