Upload README.md with huggingface_hub

README.md

@@ -3,7 +3,6 @@ license: mit
 base_model: zai-org/GLM-5.3-Flash
 tags: [reap, moe, pruning, glm5_next, jetson, thor]
 ---
-
 # GLM-5.3-Flash REAP-50 (FP8)
 
 50% of routed experts removed with **REAP**
@@ -18,6 +17,73 @@ permissively-licensed multi-domain corpus that includes real image-text pairs.
 | Healed | yes |
 | MTP block | excluded (see below) |
 
+
+## Versions — which weights are which
+
+Three selection passes have shipped. Each is a **different mask**, not a re-run of the same one,
+and all keep **144 of 288 routed experts** (REAP50). What differs is *which* 144.
+
+**Older weights are never overwritten.** The subdirectory tells you the version.
+
+| version | method | healing | location in this repo |
+|---|---|---|---|
+| **v2** | refined REAP scalar mask | per-expert | **repo root** (the files beside this card) |
+| **v3** | **HOPE** — interaction-aware, `protect_frac=0.04` | per-expert | subdirectory **`pass3-hope/`** |
+
+> The repo name's `-v2` suffix is from the pass-2 release and is now just a name. Read the
+> **path**, not the repo title: root = v2, `pass3-hope/` = v3.
+
+v1 (the first published REAP mask) is superseded and not carried here.
+
+### What v3 changed, and why
+
+v2 ranked each expert alone and took the top-k. [arXiv 2609.18916] shows that is exactly HOPE with
+the off-diagonal of `F` zeroed — two experts that duplicate each other are cheap to drop together,
+two that complement each other are not, and a per-expert ranking cannot tell the difference. v3
+minimises `pᵀFp`, the output error a prune set actually causes, over the same accumulators.
+
+v2 also ran with **no domain floor** and lost ballast capability as a result. v3 sets
+`protect_frac = 0.04`, measured off this run's own accumulators at the knee of worst-domain
+retention against interaction cost — not guessed, and not inherited from MiMo's 0.08, which sits
+where marginal efficiency is 0.43.
+
+v3 is calibrated on **866,678,064 routed slots** (42 layers x 10 chunks) and heals to a median gain
+of 0.766 across 42 layers with none skipped.
+
+### Honest comparison
+
+v1 -> v2 improved reconstruction residual by 2.5% but was **zero to within noise** end to end
+(top-1 agreement 0.8370 -> 0.8369, SE 0.00075 on 241,516 held-out tokens). Per domain it was a
+redistribution rather than a lift. **v3 has not yet been evaluated end to end** — when it has, the
+numbers will be published here. Until then, treat v3 as "better-motivated selection, unproven
+head-to-head", not as a measured improvement.
+
+### Two caveats that apply to v3
+
+- **No bio coverage.** The bio domain saw **0** of 866,678,064 routed slots, because every bio
+  source is excluded by licence or clinical scope (`camel-ai/biology`, `tattabio/OG`, `PubMedQA`).
+  Selection scored the 7 live domains. This is a property of the calibration corpus, not a bug, and
+  no amount of recomputation changes it. **Do not rely on this model for biomedical work.**
+- **Long-context assurance is at 8192 tokens**, not the intended 16384. A single 16384-token
+  forward needs >93 GiB — attention is quadratic and one forward is indivisible, so no amount of
+  blocking helps on the build host. 8192 is still 4x the 2048 tokens the mask was calibrated at.
+
+Full method write-up: **[glm-5.3-reap/wiki/31-pass3-hope-method.md](https://github.com/patrickbdevaney/glm-5.3-reap/blob/main/wiki/31-pass3-hope-method.md)**
+
+### Download a specific version
+
+```bash
+# v3 (HOPE) - 160.6 GiB, 62 shards
+hf download patrickbdevaney/GLM-5.3-Flash-REAP50-FP8-v2 \
+    --include "pass3-hope/*" --local-dir ./glm53-reap50-fp8-v3
+
+# v2 - repo root
+hf download patrickbdevaney/GLM-5.3-Flash-REAP50-FP8-v2 \
+    --exclude "pass3-hope/*" --local-dir ./glm53-reap50-fp8-v2
+```
+
+FP8 is the **master** checkpoint: NVFP4 and GGUF are both derived from it.
+
 ## Why FP8 and not BF16
 
 The upstream release is **FP8**, not BF16. Routed experts are stored per-expert with their own