Model card: align layout with GLM-5.3-Flash-MLX template

README.md

@@ -75,11 +75,12 @@ tags:
 > tensors more bits (shared experts `+2`, `down_proj` `+1`) while **attention stays at 8-bit and
 > the DSA indexer stays in BF16** in every build. Browse all models in the
 > [OrcaRouter Model Catalog](https://www.orcarouter.ai/models); deployed as API
-> [here](https://www.orcarouter.ai/models/z-ai/glm-5.3).
+> [here](https://www.orcarouter.ai/models/z-ai/glm-5.3). Put this model to work reviewing your
+> pull requests with **[OrcaCode Review](https://github.com/Continuum-AI-Corp/Orca-Code-Review)**.
 
 ---
 
-## Available Quantizations
+## Available quantizations
 
 | Folder | Expert base bits | Group size | Size | Min RAM | Quality vs FP8 |
 |---|---|---|---:|---:|---|
@@ -117,7 +118,7 @@ Two properties of this checkpoint drive the whole recipe:
 
 Everything that was *not* FP8 in the base release — the indexer, router `gate` weights, the FP32 `e_score_correction_bias`, every norm, `embed_tokens` and `lm_head` — is carried through at its **original dtype**, never a lossy cast.
 
-### Bit Allocation for GLM-5.3
+### Bit allocation for GLM-5.3
 
 | Component | Tensors | Params | 2-bit | 3-bit | 4-bit | 6-bit | Policy |
 |---|---:|---:|---|---|---|---|---|
@@ -150,43 +151,11 @@ The **MTP (multi-token prediction) layer — layer 78 — is dropped**, and `num
 
 ## Quality vs FP8
 
-### Weight-Space Fidelity
+All three tables compare each build against the full **FP8** reference (dequantized to BF16 and run
+through the identical `glm_moe_dsa` forward, so the only variable is the quantization). Sizes are
+decimal GB, matching the file sizes in this repo.
 
-Measured on **every quantized tensor** at pack time (58,224 per build), against the FP8 source block-dequantized to BF16 — so the only variable is the quantization.
-
-| Build | Size | Cosine sim | SNR (dB) | Rel. error |
-|---|---:|---:|---:|---:|
-| `6-bit` | 671 GB | **0.9998** | **37.2** | **1.7 %** |
-| `4-bit` | 459 GB | **0.9968** | **22.9** | **7.6 %** |
-| `3-bit` | 368 GB | **0.9865** | **16.7** | **15.7 %** |
-| `2-bit` | 322 GB | **0.9517** | **11.2** | **29.7 %** |
-
-Worst-case per build (`cos_min` / `snr_min`): `6-bit` 0.99972 / 32.5 dB · `4-bit` 0.99509 / 20.1 dB · `3-bit` 0.97869 / 13.7 dB · `2-bit` 0.92718 / 8.3 dB.
-
-> Relative error is the mean of the **per-tensor** relative error `10^(-SNR/20)` over all 58,224 quantized tensors — not a value back-derived from the mean SNR, which would understate it (1.4 / 7.1 / 14.7 / 27.5 %).
-
-Per role — this is where the OrcaSAQ policy shows up:
-
-| Role | bits/gs | 2-bit cos | 3-bit cos | 4-bit cos | 6-bit cos |
-|---|---|---:|---:|---:|---:|
-| Expert `gate_proj`/`up_proj` | base | 0.93417 | 0.98169 | 0.99570 | 0.99975 |
-| Expert `down_proj` | base +1 | 0.98510 | 0.99568 | 0.99898 | 0.99998 |
-| Shared expert | base +2 | 0.99561 | 0.99896 | 0.99974 | 0.99998 |
-| MLA attention | 8/64 | 0.99998 | 0.99998 | 0.99998 | 0.99998 |
-| Dense MLP | 6/64 | 0.99975 | 0.99975 | 0.99975 | 0.99975 |
-
-Cosine distribution across all quantized tensors (tight percentiles = no outlier tensors hiding behind a good mean):
-
-| Build | min | p1 | p5 | median | p95 | max |
-|---|---:|---:|---:|---:|---:|---:|
-| `2-bit` | 0.92718 | 0.93133 | 0.93390 | 0.93437 | 0.98515 | 0.99999 |
-| `3-bit` | 0.97869 | 0.98047 | 0.98157 | 0.98178 | 0.99571 | 0.99999 |
-| `4-bit` | 0.99509 | 0.99546 | 0.99566 | 0.99571 | 0.99899 | 0.99999 |
-| `6-bit` | 0.99972 | 0.99974 | 0.99975 | 0.99975 | 0.99999 | 0.99999 |
-
-The worst tensors in every build are the same ones — early-layer routed experts (`layers.3–5`, e.g. `layers.4.mlp.experts.168.gate_proj`) — and `6-bit` still holds them above 0.9997.
-
-### Perplexity
+**Perplexity**
 
 Measured against the **FP8 reference** on wikitext-2 test, 4 chunks × 1024 tokens
 (4,092 predicted tokens). Both sides run the identical `glm_moe_dsa` forward on the
@@ -203,7 +172,7 @@ transformers model — so quantization is the only variable.
 
 `6-bit` lands within noise of the FP8 reference — read it as indistinguishable.
 
-### KL Divergence & Top-1 Token Agreement
+**KL divergence & Top-1 token agreement**
 
 KLD is `KL(ref ‖ quant)` per token against the FP8 reference distribution, Top-1 is how
 often the build's argmax matches the reference's. Lower KLD and higher Top-1 = closer to
@@ -223,9 +192,41 @@ less memory** and is the recommended default, and `3-bit` holds up well at 40 %
 FP8. `2-bit` is the memory-first option — reach for it when the hardware cannot hold
 anything larger.
 
-### Build Verification
+**Weight-space fidelity** — measured on every quantized tensor at pack time (58,224 per build):
+
+| Build | Size | Cosine sim | SNR (dB) | Rel. error |
+|---|---:|---:|---:|---:|
+| `6-bit` | 671 GB | **0.9998** | **37.2** | **1.7 %** |
+| `4-bit` | 459 GB | **0.9968** | **22.9** | **7.6 %** |
+| `3-bit` | 368 GB | **0.9865** | **16.7** | **15.7 %** |
+| `2-bit` | 322 GB | **0.9517** | **11.2** | **29.7 %** |
+
+Worst-case per build (`cos_min` / `snr_min`): `6-bit` 0.99972 / 32.5 dB · `4-bit` 0.99509 / 20.1 dB · `3-bit` 0.97869 / 13.7 dB · `2-bit` 0.92718 / 8.3 dB.
+
+> Relative error is the mean of the **per-tensor** relative error `10^(-SNR/20)` over all 58,224 quantized tensors — not a value back-derived from the mean SNR, which would understate it (1.4 / 7.1 / 14.7 / 27.5 %).
+
+Per role — this is where the OrcaSAQ policy shows up:
+
+| Role | bits/gs | 2-bit cos | 3-bit cos | 4-bit cos | 6-bit cos |
+|---|---|---:|---:|---:|---:|
+| Expert `gate_proj`/`up_proj` | base | 0.93417 | 0.98169 | 0.99570 | 0.99975 |
+| Expert `down_proj` | base +1 | 0.98510 | 0.99568 | 0.99898 | 0.99998 |
+| Shared expert | base +2 | 0.99561 | 0.99896 | 0.99974 | 0.99998 |
+| MLA attention | 8/64 | 0.99998 | 0.99998 | 0.99998 | 0.99998 |
+| Dense MLP | 6/64 | 0.99975 | 0.99975 | 0.99975 | 0.99975 |
+
+Cosine distribution across all quantized tensors (tight percentiles = no outlier tensors hiding behind a good mean):
+
+| Build | min | p1 | p5 | median | p95 | max |
+|---|---:|---:|---:|---:|---:|---:|
+| `2-bit` | 0.92718 | 0.93133 | 0.93390 | 0.93437 | 0.98515 | 0.99999 |
+| `3-bit` | 0.97869 | 0.98047 | 0.98157 | 0.98178 | 0.99571 | 0.99999 |
+| `4-bit` | 0.99509 | 0.99546 | 0.99566 | 0.99571 | 0.99899 | 0.99999 |
+| `6-bit` | 0.99972 | 0.99974 | 0.99975 | 0.99975 | 0.99999 | 0.99999 |
+
+The worst tensors in every build are the same ones — early-layer routed experts (`layers.3–5`, e.g. `layers.4.mlp.experts.168.gate_proj`) — and `6-bit` still holds them above 0.9997.
 
-Independent of quality, every build passed a structural release gate before upload:
+**Build verification** — every build passed a structural release gate before upload:
 
 - **accounting** — 175,242 tensors on disk, 58,224 quantized modules, `weight`/`scales`/`biases` triplets all paired
 - **dtype preservation** — kept tensors byte-identical in their source dtype (FP32 router bias stays FP32; FP8 `keep` goes through a proper block dequant, never a raw cast)
@@ -236,9 +237,11 @@ Independent of quality, every build passed a structural release gate before uplo
 
 ---
 
+---
+
 ## Usage
 
-### Hosted API — No Download
+### Hosted API — no download
 
 The full-precision model is live on OrcaRouter as **`z-ai/glm-5.3`** — 1M context, 128K max output, $1.26 / $3.96 per 1M input / output tokens:
 
@@ -260,7 +263,7 @@ print(response.choices[0].message.content)
 
 **https://www.orcarouter.ai/models/z-ai/glm-5.3**
 
-### Run it Locally (mlx-vlm)
+### Run it locally (mlx-vlm)
 
 > **Use `mlx-vlm`, not `mlx-lm`.** GLM-5.3 is a text-only model, but as of **mlx-lm 0.31.3** the `glm_moe_dsa` implementation builds an indexer for *every* layer, while this checkpoint shares one indexer across four layers (`indexer_types`) — 285 tensors come up missing. **mlx-vlm 0.6.17** implements the shared-indexer layout and loads these builds as-is. Check for mlx-lm support before switching back.
 
@@ -335,11 +338,29 @@ Tool calling is in the template too (`<tool_call>` / `<arg_key>` blocks, `tools=
 
 ---
 
-## GLM-5.3
+## Build Provenance
+
+| | |
+|---|---|
+| Source | `zai-org/GLM-5.3` (FP8, 141 shards, 756 GB) |
+| Quantized | 2026-08-28 |
+| Toolchain | MLX 0.32.2, safetensors 0.8.0, NumPy 2.5.2 |
+| Method | OrcaSAQ — calibration-free, role-based mixed precision |
+| Per-build files | 140 shards + `config.json`, `quantization_map.json`, `build_manifest.json`, `fidelity_summary.json`, tokenizer, chat template |
+
+Each folder carries its own `build_manifest.json` (exact recipe, source path, dropped-tensor count, toolchain versions) and `fidelity_summary.json` (per-role cosine/SNR with the five worst tensors named), so any claim in this card can be checked against the build itself.
+
+---
+
+# GLM-5.3
 
 > Available full-precision on the OrcaRouter API as **`z-ai/glm-5.3`** —
 > **https://www.orcarouter.ai/models/z-ai/glm-5.3**
 
+---
+
+## GLM-5.3 Highlights
+
 GLM-5.3 uses the same base model as GLM-5.2 — every gain comes from post-training. Compared with GLM-5.2, it is much better at complex coding and long-horizon tasks:
 
 - **Stronger coding:** the most capable open-weights model for coding, with a **50 % improvement over GLM-5.2** on Z.AI's in-house Code Bench, and open-source SOTA on public benchmarks including Terminal Bench 3.0 and Agents' Last Exam.
@@ -349,7 +370,9 @@ GLM-5.3 uses the same base model as GLM-5.2 — every gain comes from post-train
 <img src="https://raw.githubusercontent.com/zai-org/GLM-5/refs/heads/main/resources/logo.svg" width="30%" alt="GLM-5" />
 </div>
 
-### Official Benchmarks
+---
+
+## Official benchmarks
 
 Reported by Z.AI for the full-precision model. These are the upstream model's numbers, not measurements of these MLX builds — see [Quality vs FP8](#quality-vs-fp8) above for how each quantization tracks the FP8 release.
 
@@ -376,7 +399,9 @@ Reported by Z.AI for the full-precision model. These are the upstream model's nu
 
 Full evaluation protocols and footnotes are in the [official model card](https://huggingface.co/zai-org/GLM-5.3).
 
-### Model Overview
+---
+
+## Model Overview
 
 - **Type:** Mixture-of-Experts Causal LM (`glm_moe_dsa`, `GlmMoeDsaForCausalLM`)
 - **Parameters:** **753B total** · **~39B active** per token (22.6B routed + 16.7B always-on; 743B after the MTP layer is dropped)
@@ -387,7 +412,9 @@ Full evaluation protocols and footnotes are in the [official model card](https:/
 - **Context:** 1,048,576 tokens · vocab 154,880
 - **Modality:** text
 
-### Best Practices
+---
+
+## Best Practices
 
 - **Pick a precision:** `6-bit` for near-lossless, `4-bit` (repo root) as the everyday default, `3-bit` when memory is the binding constraint, `2-bit` when nothing else fits — the tables above quantify the trade at each step.
 - **Sampling:** follow the official GLM-5.3 guidance. The shipped `generation_config.json` is `temperature` 1.0, `top_p` 0.95; long-horizon agentic and coding tasks want generous `max-tokens` headroom.
@@ -397,20 +424,6 @@ Full evaluation protocols and footnotes are in the [official model card](https:/
 
 ---
 
-## Build Provenance
-
-| | |
-|---|---|
-| Source | `zai-org/GLM-5.3` (FP8, 141 shards, 756 GB) |
-| Quantized | 2026-08-28 |
-| Toolchain | MLX 0.32.2, safetensors 0.8.0, NumPy 2.5.2 |
-| Method | OrcaSAQ — calibration-free, role-based mixed precision |
-| Per-build files | 140 shards + `config.json`, `quantization_map.json`, `build_manifest.json`, `fidelity_summary.json`, tokenizer, chat template |
-
-Each folder carries its own `build_manifest.json` (exact recipe, source path, dropped-tensor count, toolchain versions) and `fidelity_summary.json` (per-role cosine/SNR with the five worst tensors named), so any claim in this card can be checked against the build itself.
-
----
-
 ## Citation
 
 ```bibtex