Add model card and usage instructions

README.md

@@ -0,0 +1,121 @@
+---
+language:
+- en
+- zh
+library_name: pytorch
+pipeline_tag: image-classification
+tags:
+- ltf
+- ai-generated-image-detection
+- clip
+- multiple-instance-learning
+metrics:
+- accuracy
+---
+
+# LTF v3.3 — AI-generated image detection
+
+This repository contains the **epoch 20 checkpoint** used in the historical
+GenImage evaluation `20260326_012209_ViT-L-14_genimage_v3_v3_3`.
+The model is also named HiDA v3.3 in the original experiment code.
+
+LTF uses a frozen **CLIP ViT-L/14** backbone, two-level multiple-instance
+learning (MIL), cross-shuffle during training, and pool-logit gated fusion.
+The repository includes the custom PyTorch runtime and the frozen backbone.
+It does not require conversion to a Transformers architecture.
+
+## Historical results
+
+Fixed threshold **0.5**, 8 GenImage subsets, **100,000 images**. Accuracy is the
+unweighted mean across subsets, as recorded in the original rounded logs:
+
+| Branch | Accuracy |
+| --- | ---: |
+| L1 | 95.26% |
+| L2 | 97.39% |
+| Fusion | **98.39%** |
+
+Per-subset metrics are in `results/genimage8_logged_metrics.csv`.
+These are historical logged results; uploading this repository did not rerun
+the complete benchmark. SD1.4 official validation images were used during
+training validation, so that subset overlaps model validation. These results
+do not represent eight entirely held-out generators.
+
+## Download and run
+
+Use **Python 3.11**. Replace `MuskAI/LTF-v3.3` with this repository's ID.
+
+```bash
+python -m pip install -U huggingface_hub
+hf download MuskAI/LTF-v3.3 --local-dir ./LTF-v3.3
+cd LTF-v3.3
+python -m pip install -r requirements.txt
+python inference.py --input /path/to/image.jpg --device cpu
+```
+
+For GPU inference, use `--device cuda:0`. For larger images, lower the CLIP
+forward chunk size without removing tiles:
+
+```bash
+python inference.py --input /path/to/image.jpg --device cuda:0 --chunk-size 8
+```
+
+## Python API
+
+Run from the downloaded repository directory:
+
+```python
+from ltf_final import LTFDetector
+
+detector = LTFDetector(device="auto", chunk_size=8)
+result = detector.predict("image.jpg", branch="fusion", threshold=0.5)
+print(result["prediction"], result["score_fake"])
+print(result["probabilities"])
+```
+
+The image is decoded as RGB. All original edge-aligned 224×224 local tiles plus
+a global view use the original CLIP preprocessing. Input files are not
+recompressed. Test tiling depends on image size. Labels are **0=real, 1=fake**.
+The API returns L1/L2/fusion scores, the selected label and the view count.
+Loading the model does not download external weights after this repository
+has been downloaded. It uses `backbones/ViT-L-14.pt`.
+
+## Checkpoint identity and provenance
+
+`weights/epoch_20.pth` is the original core state_dict (not `best.pth`):
+
+```text
+SHA256 32e9fa2e38e04d6d0221c844d650f0d45f7235bbf898b5ad665543d8be580031
+```
+
+Frozen CLIP backbone:
+
+```text
+SHA256 b8cca3fd41ae0c99ba7e8951adf17d267cdb84cd88be6f7c2e0eca1737a03836
+```
+
+`release_manifest.json` records checksums of every runtime file. The original
+training and evaluation directories did not save training-day source snapshots.
+The released core was recovered from git commit
+`65c18ee5868ced87a27d048261e237632ad5d704`, with network naming adjusted to LTF.
+This verifies checkpoint identity and runtime compatibility, not bit-for-bit
+reproduction of the original training process. This Hub adaptation adds
+tensor-only checkpoint loading and removes a machine-specific dataset path.
+
+## Limitations
+
+Scores are not calibrated authenticity probabilities. Predictions can change
+with image content, generator, editing and compression. This model is a
+research detector; an individual score does not prove image provenance.
+
+The public demo uses configurable image-size limits for its available compute;
+oversized uploads are rejected, not silently resized. CPU inference can be slow
+for images containing many local tiles.
+
+## License and citation
+
+An author-selected license and final paper citation were not supplied in the
+source bundle. This release does not invent a license or citation for LTF.
+Contact the author about reuse permissions. The bundled CLIP components retain
+their upstream terms: [OpenAI CLIP](https://github.com/openai/CLIP) and its
+[MIT license](https://github.com/openai/CLIP/blob/main/LICENSE).