Expand model card with usage, provenance, evaluation scope and related releases

README.md

@@ -1,77 +1,122 @@
 ---
 license: other
 library_name: bagel-mot
+language:
+- en
 tags:
 - geoug
-- vision-language
-- spatial-reasoning
+- geometry
 - supervised-fine-tuning
 ---
 
 # GeoUG-ColdStart
 
-**Supervised cold-start checkpoint for initializing GeoUG spatial-policy RL.**
+[Project page](https://yangr116.github.io/geoug-project-page/) ·
+[Paper](https://yangr116.github.io/geoug-project-page/assets/geoug-paper.pdf)
 
-This is the EMA checkpoint at step **1500** of GeoUG v6 interleaved reasoning
-SFT. It is released as the initialization used for RL training. Use
-[GeoUG-Spatial](https://huggingface.co/rayruiyang/GeoUG-Spatial) for the final
-adaptive spatial reasoning policy; the final policy's benchmark results are
-not results for this checkpoint.
+**The supervised cold-start checkpoint for GeoUG spatial-policy RL.**
 
-## Training role
+GeoUG-ColdStart is the EMA checkpoint at step **1500** of GeoUG v6 interleaved
+reasoning SFT. Its released role is to initialize the subsequent RL stage.
 
-The checkpoint precedes the `spatial_gate_draft_v3` RL stage. The released EMA
-weights preserve their original BF16 dtype. The bundled transform matches the
-v6 reasoning SFT and spatial RL recipe, including multiscale disparity
-normalization with `c: [2.0, 8.0, 32.0]`.
+| Property | Value |
+|---|---|
+| Stage | v6 interleaved reasoning supervised fine-tuning |
+| Checkpoint | Step 1500, EMA |
+| Precision | Original BF16 weights |
+| Downstream model | GeoUG-Spatial after spatial-policy RL |
+| Bundled transform | Matches the v6 reasoning SFT and spatial RL recipe |
 
-After downloading, set these paths when following GeoUG's `docs/RL_TRAINING.md`:
+## Download
+
+```python
+from huggingface_hub import snapshot_download
+
+snapshot_download(
+    repo_id="rayruiyang/GeoUG-ColdStart",
+    local_dir="ckpt/geoug-coldstart",
+)
+```
+
+These are custom BAGEL/MoT weights. Use the GeoUG runtime rather than a generic
+`AutoModel.from_pretrained` call. The weight repository contains the checkpoint
+assets; inference and training code live in the GeoUG code checkout.
+
+Verify the download:
 
 ```bash
-export MODEL_PATH="$PWD/ckpt/geoug-coldstart"
-export RL_TRANSFORM_CONFIG="$MODEL_PATH/transform_config.yaml"
+(cd ckpt/geoug-coldstart && sha256sum -c checksums.sha256)
 ```
 
-The trainer requires the training data, camera metadata, depth caches, and a
-separately prepared validation/evaluation set. The public training parquet is
-available at [GeoUG_data](https://huggingface.co/datasets/rayruiyang/GeoUG_data).
-The GeoUG `scripts/pack_data_parquet.py unpack-rl` command restores its training
-layout. The internal evaluation subset is not distributed.
+## Initialize RL training
 
-## Package contents
+Use the GeoUG checkout's separate RL environment, described in
+`docs/RL_TRAINING.md`. After downloading this model and
+[train_geoug_rl.parquet](https://huggingface.co/datasets/rayruiyang/GeoUG_data/blob/main/train_geoug_rl.parquet),
+restore the public training layout:
 
-`ema.safetensors` (BF16), `ae.safetensors`, model configs, tokenizer files,
-`transform_config.yaml`, this card, and `checksums.sha256`.
-Only EMA weights are released; a non-EMA model or a shard index is not needed.
+```bash
+python scripts/pack_data_parquet.py unpack-rl \
+  --input /absolute/path/to/train_geoug_rl.parquet \
+  --output /absolute/path/to/rl_train
 
-## License
+export MODEL_PATH="$PWD/ckpt/geoug-coldstart"
+export RL_TRANSFORM_CONFIG="$MODEL_PATH/transform_config.yaml"
+export RL_DATASET=/absolute/path/to/rl_train
+export DEPTH_CACHE_DIR=/absolute/path/to/rl_train/depth-cache
+```
 
-The checkpoint accompanies the mixed-license GeoUG code release. Review the
-repository `LICENSE` and `THIRD_PARTY_NOTICES.md`, including the CC BY-NC
-restrictions on the listed BAGEL/DiT-derived code files, before use.
+The parquet includes training images, camera metadata, and generated-depth
+caches. Prepare your own validation/evaluation inputs as required by the RL
+recipe; the internal RL evaluation subset is not distributed.
 
-## Download
+The transform uses multiscale disparity normalization with
+`c: [2.0, 8.0, 32.0]`. The RL loader uses `ema.safetensors`, matching the
+initialization used by the released recipe.
 
-```python
-from huggingface_hub import snapshot_download
+## Scope and interpretation
 
-snapshot_download(
-    repo_id="rayruiyang/GeoUG-ColdStart",
-    local_dir="ckpt/geoug-coldstart",
-)
-```
+This repository provides the initialization checkpoint, not the final adaptive
+policy. Use GeoUG-Spatial for the final model. Its reported RL benchmark scores
+must not be attributed to GeoUG-ColdStart.
 
-Use the GeoUG code and its documented environment to load this package. These
-are custom BAGEL/MoT weights, not a standalone `AutoModel.from_pretrained`
-Transformers package. The inference loader selects `ema.safetensors` by default.
+The cold start **model** is released here. The cold start **training data** is a
+separate, pending release; it is not included in this repository or in the
+800-sample RL training parquet.
 
-## Related releases
+## Model family
 
-| Model | Role |
+| Checkpoint | Intended use |
 |---|---|
 | [GeoUG-Spatial](https://huggingface.co/rayruiyang/GeoUG-Spatial) | Final adaptive spatial reasoning policy |
 | [GeoUG-Depth](https://huggingface.co/rayruiyang/GeoUG-Depth) | Standalone metric-depth generation |
 | [GeoUG-ColdStart](https://huggingface.co/rayruiyang/GeoUG-ColdStart) | SFT initialization for spatial-policy RL |
 
-[Project page](https://yangr116.github.io/geoug-project-page/) ·
-[Paper](https://yangr116.github.io/geoug-project-page/assets/geoug-paper.pdf)
+## Package and integrity
+
+| File | Contents |
+|---|---|
+| `ema.safetensors` | BF16 EMA model weights, approximately 27.21 GiB |
+| `ae.safetensors` | VAE weights |
+| `llm_config.json`, `vit_config.json`, `config.json`, `generation_config.json` | Model and generation configuration |
+| `tokenizer.json`, `tokenizer_config.json`, `vocab.json`, `merges.txt` | Tokenizer assets |
+| `transform_config.yaml` | Image/depth preprocessing and normalization |
+| `checksums.sha256` | SHA-256 checksums for the package files |
+
+Download the complete repository. The release uses EMA weights and does not
+require a separate non-EMA checkpoint or a shard index.
+
+## License and attribution
+
+GeoUG builds on the BAGEL/MoT architecture and its pretrained components.
+This checkpoint accompanies the mixed-license GeoUG code release. Consult
+`LICENSE` and `THIRD_PARTY_NOTICES.md` in the GeoUG code checkout for the
+applicable component terms, including the CC BY-NC restrictions on the listed
+BAGEL/DiT-derived code files. This card does not assign a new blanket license
+to upstream components. The data repositories document their own source and
+usage terms separately.
+
+## Contact
+
+For questions about this release, contact
+[rayyang0116@connect.hku.hk](mailto:rayyang0116@connect.hku.hk).

checksums.sha256

@@ -1,4 +1,4 @@
-51cb469f78aaf3c2411f5d9930c865f3258f6cad1efec5a664fbacc91082f51b  README.md
+d993de5bf2b825b6088e94ef9f1988467caff830aa81ad3f15904719f628bb89  README.md
 afc8e28272cd15db3919bacdb6918ce9c1ed22e96cb12c4d5ed0fba823529e38  ae.safetensors
 6340dfd03b315d68faf266944c2a4a484ec8dafff4f2b55a059d95ad7656cbf7  config.json
 09934295baa7d057afaf51cc0aec2edd646708df380f79327400c18c4190a189  ema.safetensors