Upload README.md with huggingface_hub

README.md

@@ -19,7 +19,7 @@ tags:
 # OracleZoom
 
 **Privileged-Latent Distillation for faithful extreme super-resolution.**
-A tiny (7.1M-parameter) LoRA adapter that makes Chain-of-Zoom's recursive super-resolution add *faithful* detail instead of hallucinating, all the way to 256x.
+A tiny (7.1M-parameter) LoRA adapter that makes Chain-of-Zoom's recursive super-resolution add *faithful* detail instead of hallucinating, all the way to 256x. Shipped both as the LoRA adapter and as a **fully-merged transformer you can download and use directly**.
 
 [![GitHub](https://img.shields.io/badge/Code-OPD--Zoom-black?logo=github)](https://github.com/dipta007/OPD-Zoom)
 [![Base](https://img.shields.io/badge/Backbone-OSEDiff%20/%20SD3-blue)](https://huggingface.co/stabilityai/stable-diffusion-3-medium-diffusers)
@@ -28,16 +28,23 @@ A tiny (7.1M-parameter) LoRA adapter that makes Chain-of-Zoom's recursive super-
 [![License](https://img.shields.io/badge/License-CC--BY--NC--4.0-lightgrey)](https://creativecommons.org/licenses/by-nc/4.0/)
 
 ## Highlights
-- **Faithful, not just sharp.** At extreme zoom the backbone must *invent* detail; the question is whether it is faithful or hallucinated. This adapter teaches faithfulness.
+- **Faithful, not just sharp.** At extreme zoom the backbone must *invent* detail; the question is whether it is faithful or hallucinated. This model teaches faithfulness.
 - **Holds where baselines collapse.** CLIPIQA **0.71 at 256x** while Chain-of-Zoom (CoZ) and five SOTA SR backbones fall to <=0.58; most faithful of all methods at 4x (LPIPS **0.20** vs CoZ 0.22).
 - **Judged more faithful.** Two cross-family vision-language judges (InternVL + Gemini) prefer this zoom **68-78%** of the time at 64-256x and flag the strongest baseline hallucinating **2-5x more**.
-- **Tiny and drop-in.** A rank-16 LoRA (**7.1M** trainable params) trained on only **1,000** curated 4K images; it drops into CoZ's recursion with no other changes.
+- **Tiny to train, easy to use.** A rank-16 LoRA (**7.1M** trainable params) trained on only **1,000** curated 4K images; shipped as both the adapter and a merged, drop-in transformer.
+
+## Files in this repo
+| File | What it is |
+|---|---|
+| `merged_transformer.safetensors` | **The complete OracleZoom SR transformer** (SD3 + OSEDiff's SR-LoRA + our PLD adapter, all baked in), fp32, ~8.35 GB. Download-and-use: drop it in as the transformer, no LoRA step. |
+| `adapter_model.safetensors` + `adapter_config.json` | The rank-16 PLD LoRA **alone** (~28 MB), if you prefer to apply it onto your own OSEDiff transformer. |
+| `train_meta.json` | Training recipe / provenance. |
 
 ## Model Overview
 | Property | Value |
 |---|---|
-| Model type | LoRA adapter (PEFT) for a one-step SR backbone |
-| Backbone (frozen) | OSEDiff on Stable Diffusion 3-medium |
+| Model type | LoRA adapter (PEFT) for a one-step SR backbone, + merged transformer |
+| Backbone | OSEDiff on Stable Diffusion 3-medium |
 | Prompt extractor (frozen) | Qwen2.5-VL-3B-Instruct |
 | Trainable params | 7.1M |
 | LoRA | r = 16, alpha = 32, dropout = 0.0 |
@@ -54,31 +61,34 @@ Recursive SR (Chain-of-Zoom) reuses a 4x backbone step after step to reach 16x-2
 
 **A KL leash keeps the deep reward faithful (the safeguard).** Ground truth exists only at 4x. To carry the distilled prior into the deeper recursion, the student chases a differentiable detail reward (TOPIQ-NR) through the real zoom. Left free, such a reward games the metric with a repetitive crosshatch; **leashed** to the deployed backbone by a KL trust region (a latent distance for a one-step map), it sharpens detail without drifting into hallucination.
 
-Full derivation and ablations are in the [OPD-Zoom repo](https://github.com/dipta007/OPD-Zoom).
-
 ## Quickstart
-This is the trained artifact of OracleZoom: a PEFT LoRA on the SD3 transformer that OSEDiff uses as the SR backbone inside Chain-of-Zoom. It plugs into the OPD-Zoom pipeline.
+Both paths run inside the [OPD-Zoom](https://github.com/dipta007/OPD-Zoom) / Chain-of-Zoom pipeline.
 
 ```bash
-# 1) get the pipeline
 git clone https://github.com/dipta007/OPD-Zoom && cd OPD-Zoom
-
-# 2) get this adapter
 huggingface-cli download dipta007/OracleZoom --local-dir ckpt/OracleZoom
+```
 
-# 3) run the 4-recursion zoom with the adapter as the student SR LoRA
-python -m opd_zoom.teacher.oracle_infer \
-  --mode student --pld_lora ckpt/OracleZoom \
-  --gt_dir <your_images> --out <out_dir> --rec_num 4
+**Option A - merged transformer (recommended, no LoRA step).** `merged_transformer.safetensors` already contains SD3 + OSEDiff's SR-LoRA + our PLD adapter, so you just load it as the SR transformer's weights:
+```python
+from safetensors.torch import load_file
+sd = load_file("ckpt/OracleZoom/merged_transformer.safetensors")
+# `transformer` = the OSEDiff SD3Transformer2DModel built by the pipeline (build_sr)
+transformer.load_state_dict(sd, strict=False)
 ```
 
-Loading just the adapter with PEFT:
+**Option B - LoRA adapter.** Apply the rank-16 adapter onto the OSEDiff transformer with PEFT:
 ```python
 from peft import PeftModel
-# `sd3_transformer` is the SD3Transformer2DModel used by the OSEDiff backbone
-model = PeftModel.from_pretrained(sd3_transformer, "dipta007/OracleZoom")
+transformer = PeftModel.from_pretrained(transformer, "dipta007/OracleZoom")
+```
+Or point the repo's inference at the adapter directly:
+```bash
+python -m opd_zoom.teacher.oracle_infer \
+  --mode student --pld_lora ckpt/OracleZoom \
+  --gt_dir <your_images> --out <out_dir> --rec_num 4
 ```
-The adapter is `inference_mode` and merges into the backbone at no added latency; the VLM prompter is unchanged, so per-image inference cost equals Chain-of-Zoom's.
+Either way the VLM prompter is unchanged, so per-image inference cost equals Chain-of-Zoom's.
 
 ## Results
 Under Chain-of-Zoom's exact protocol on a curated 4K benchmark and six test sets (in-domain 4K, DIV8K, DRealSR, RealSR, FFHQ, Flickr2K):
@@ -93,8 +103,8 @@ Under Chain-of-Zoom's exact protocol on a curated 4K benchmark and six test sets
 Sharpness is the axis prior methods are built for; the decisive gap is **faithfulness**, verified by full-reference metrics at 4x and by two cross-family MLLM judges plus a blinded human study past 4x.
 
 ## Intended Use
-- **In-scope:** research on faithful extreme (recursive) super-resolution; as the SR-backbone adapter inside the Chain-of-Zoom recursion on natural photographs.
-- **Out-of-scope:** a standalone single-shot SR model (it is a drop-in LoRA for the CoZ loop, not a full model); forensic or evidentiary use (detail past 4x is generated, not recovered); real-camera-zoom claims (the benchmark uses synthetic center-crop zoom).
+- **In-scope:** research on faithful extreme (recursive) super-resolution; as the SR-backbone inside the Chain-of-Zoom recursion on natural photographs.
+- **Out-of-scope:** a standalone single-shot SR model (it is the SR backbone for the CoZ loop); forensic/evidentiary use (detail past 4x is generated, not recovered); real-camera-zoom claims (the benchmark uses synthetic center-crop zoom).
 
 ## Training
 Early-stopped on held-out validation at ~epoch 37 (step 9300); best val 0.216. Trained on one 8xH200 node (single GPU trains the adapter). Full config in `train_meta.json` and the [repo](https://github.com/dipta007/OPD-Zoom).
@@ -112,4 +122,4 @@ Early-stopped on held-out validation at ~epoch 37 (step 9300); best val 0.216. T
 Please also cite Chain-of-Zoom and OSEDiff, whose components this builds on.
 
 ## License
-Released for **research, non-commercial** use (CC-BY-NC-4.0). This adapter is trained on top of OSEDiff / Stable Diffusion 3 and used with a Qwen2.5-VL prompter inside Chain-of-Zoom; the respective upstream licenses apply to those components.
+Released for **research, non-commercial** use (CC-BY-NC-4.0). This model is built on top of OSEDiff / Stable Diffusion 3 and used with a Qwen2.5-VL prompter inside Chain-of-Zoom; the respective upstream licenses apply to those components.