hf3-request-level-v1: metadata, configs, code, and registry

README.md

@@ -0,0 +1,100 @@
+---
+license: mit
+inference: false
+tags:
+- routing
+- request-level-routing
+- speculative-decoding
+- dflash
+- mixture-of-speculators
+- qwen3
+---
+
+# MoS DFlash Routers
+
+This repository contains three experimental **request-level** router snapshots
+used by the MoS/DFlash studies. A router classifies one prompt and selects one
+of five draft experts:
+
+```text
+0 code
+1 math
+2 factual_qa
+3 creative_writing
+4 general
+```
+
+These artifacts are not token-level routers, standalone language models, or
+complete serving systems. They require hidden states from the exact target
+model and feature contract recorded beside each weight file.
+
+## Release layout
+
+```text
+request-level/
+  offline-v2/qwen3-8b/
+  intraining-sidecar/qwen3-8b/
+  c3/qwen3-4b/
+registry/
+schema/
+verification/
+manifests/
+```
+
+| Release | Feature contract | Head |
+|---|---|---|
+| `offline-v2/qwen3-8b` | layers 1/9/17/25/33; mean, max, and last pooling; stored z-score statistics | LayerNorm(61440) → Linear(512) → GELU → Linear(5) |
+| `intraining-sidecar/qwen3-8b` | layers 1/9/17/25/33; mean pooling | LayerNorm(20480) → Linear(512) → GELU → Linear(5) |
+| `c3/qwen3-4b` | layers 1/9/17/25/33; mean pooling | LayerNorm(12800) → Linear(512) → GELU → Linear(5) |
+
+The offline-v2 source was a PyTorch checkpoint. This release converts only its
+tensor state into safetensors and does not publish the pickle container.
+
+## Loading
+
+Install the two runtime dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Then load a release with the included helper:
+
+```python
+from pathlib import Path
+from router_loader import load_offline_v2, load_sidecar
+
+root = Path("request-level/offline-v2/qwen3-8b")
+head, feature_mean, feature_std, config = load_offline_v2(
+    root / "router_head.safetensors",
+    root / "router_config.json",
+)
+head.eval()
+```
+
+`load_sidecar` handles either in-training sidecar release. Feature extraction
+is intentionally not hidden inside the loader: callers must implement the
+recorded tokenizer, prompt template, target-layer, and pooling contract
+exactly.
+
+The offline-v2 deployment contract additionally zeros z-scored dimensions
+whose stored standard deviation is at most `2e-6`, then clamps the remaining
+values to `[-10, 10]`. Use `prepare_offline_features` from
+`router_loader.py`.
+
+## Verification boundary
+
+The release manifest binds every public file to SHA-256 and byte size. The
+included validation report covers:
+
+- exact tensor equality for the offline-v2 weights-only conversion;
+- safetensors header, key, shape, dtype, and finite-forward checks;
+- removal of machine-local paths and private per-sample material.
+
+It does **not** claim task-level accuracy reproduction on a new inference
+backend. Exact tokenizer, target revision, prompt formatting, hidden-state
+indexing, and numeric dtype still need end-to-end parity testing.
+
+Raw prompts, hidden-state feature tensors, per-sample routing records, training
+logs, and raw pickle checkpoints are not included.
+

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third-party notices
+
+## Qwen3 runtime dependency
+
+The routers require, but do not redistribute:
+
+- `Qwen/Qwen3-8B@b968826d9c46dd6066d109eabc6255188de91218`
+- `Qwen/Qwen3-4B@1cfa9a7208912126459214e8b04321603b3df60c`
+
+Qwen3 is licensed under Apache-2.0. Target tokenizer, embedding, LM head, and
+full language-model weights are not included.
+
+## MoS / SpecForge modifications
+
+The MoS implementation, router heads, and release tooling are distributed
+under the project MIT License.
+
+## Data boundary
+
+Training and evaluation data are not redistributed. Raw prompts, hidden-state
+feature tensors, per-sample predictions, and grouped evaluation samples are
+excluded from this repository.
+

manifests/hf3-request-level-v1.json

@@ -0,0 +1,81 @@
+{
+  "batch_id": "hf3-request-level-v1",
+  "created_utc": "2026-07-23T20:19:44.853445+00:00",
+  "files": [
+    {
+      "path": "README.md",
+      "sha256": "70166ed56d3fda4959388cdf11ee75a43551c6acd86e740b9b91946b3ca6cbdb",
+      "size_bytes": 2983
+    },
+    {
+      "path": "THIRD_PARTY_NOTICES.md",
+      "sha256": "225322aa72ce0f62a01deb7397594f5bda82d70001df806f3577834dbe0574ad",
+      "size_bytes": 687
+    },
+    {
+      "path": "registry/router_registry.json",
+      "sha256": "1c60521f97239aca909c2fc2df9b480c445d685f50cb95595f2ec57dba3437d9",
+      "size_bytes": 1700
+    },
+    {
+      "path": "request-level/c3/qwen3-4b/router_config.json",
+      "sha256": "802b443727d1960188fb471101ef21f87b75aefbc427f374f030725e0e81365a",
+      "size_bytes": 4311
+    },
+    {
+      "path": "request-level/c3/qwen3-4b/router_head.safetensors",
+      "sha256": "f1a353e667df2320202daa8bd33101623335dba7f8c3b3e17d5c1f30d694f2f6",
+      "size_bytes": 13165082
+    },
+    {
+      "path": "request-level/intraining-sidecar/qwen3-8b/router_config.json",
+      "sha256": "9ff4ac13212023dc8c9a26e53391e73a6a668adc39172fb66cc6a516754b7350",
+      "size_bytes": 3964
+    },
+    {
+      "path": "request-level/intraining-sidecar/qwen3-8b/router_head.safetensors",
+      "sha256": "d0332bd1c37ef498de4b3157f7403d96709b4f641c5a765134fa45ae71d45d98",
+      "size_bytes": 21060122
+    },
+    {
+      "path": "request-level/offline-v2/qwen3-8b/router_config.json",
+      "sha256": "fbb7cdc501276efd741337d8ad830a2800cd22a2037699f04c4ff5c6fdad5235",
+      "size_bytes": 4625
+    },
+    {
+      "path": "request-level/offline-v2/qwen3-8b/router_head.safetensors",
+      "sha256": "007a5298d372db09fcb577b9e437227c8773430b2702e7e55f57f15efeafda2b",
+      "size_bytes": 126825196
+    },
+    {
+      "path": "request-level/offline-v2/qwen3-8b/selection_sweep.json",
+      "sha256": "16ce6fec4aa81471ca9541ece787803dd31f5341fca559cb83d66bc03099f8cd",
+      "size_bytes": 4068
+    },
+    {
+      "path": "requirements.txt",
+      "sha256": "64e946b5b5eccfcdb377491fd352a24b8add573799549f7885f052e64914620d",
+      "size_bytes": 29
+    },
+    {
+      "path": "router_loader.py",
+      "sha256": "8473d8d7e37b159837d1cbbb6baabc7c344b2567a6b8972a7f8425e9c1045a1c",
+      "size_bytes": 4012
+    },
+    {
+      "path": "schema/router_config.schema.json",
+      "sha256": "42bcf639ed14d5c3e57b52b717bc33a14ed3aec3885a0baf1b067039707c2b5e",
+      "size_bytes": 2231
+    },
+    {
+      "path": "verification/structural_validation.json",
+      "sha256": "51b818b32fff87e036eb4574ea017aa72f421b34a8c59020d4c769d5ec30c995",
+      "size_bytes": 675
+    }
+  ],
+  "merged": false,
+  "repo_id": "ryan-0608/MoS-DFlash-Routers",
+  "schema_version": "1.0",
+  "source_artifacts_deleted": false,
+  "tagged": false
+}

registry/router_registry.json

@@ -0,0 +1,47 @@
+{
+  "routers": [
+    {
+      "artifact_id": "offline-v2-qwen3-8b",
+      "config": "request-level/offline-v2/qwen3-8b/router_config.json",
+      "feature_dim": 61440,
+      "router_kind": "request-level",
+      "sha256": "007a5298d372db09fcb577b9e437227c8773430b2702e7e55f57f15efeafda2b",
+      "size_bytes": 126825196,
+      "status": "experimental",
+      "target_model": {
+        "repo_id": "Qwen/Qwen3-8B",
+        "revision": "b968826d9c46dd6066d109eabc6255188de91218"
+      },
+      "weights": "request-level/offline-v2/qwen3-8b/router_head.safetensors"
+    },
+    {
+      "artifact_id": "intraining-sidecar-qwen3-8b",
+      "config": "request-level/intraining-sidecar/qwen3-8b/router_config.json",
+      "feature_dim": 20480,
+      "router_kind": "request-level",
+      "sha256": "d0332bd1c37ef498de4b3157f7403d96709b4f641c5a765134fa45ae71d45d98",
+      "size_bytes": 21060122,
+      "status": "experimental",
+      "target_model": {
+        "repo_id": "Qwen/Qwen3-8B",
+        "revision": "b968826d9c46dd6066d109eabc6255188de91218"
+      },
+      "weights": "request-level/intraining-sidecar/qwen3-8b/router_head.safetensors"
+    },
+    {
+      "artifact_id": "c3-qwen3-4b",
+      "config": "request-level/c3/qwen3-4b/router_config.json",
+      "feature_dim": 12800,
+      "router_kind": "request-level",
+      "sha256": "f1a353e667df2320202daa8bd33101623335dba7f8c3b3e17d5c1f30d694f2f6",
+      "size_bytes": 13165082,
+      "status": "experimental",
+      "target_model": {
+        "repo_id": "Qwen/Qwen3-4B",
+        "revision": "1cfa9a7208912126459214e8b04321603b3df60c"
+      },
+      "weights": "request-level/c3/qwen3-4b/router_head.safetensors"
+    }
+  ],
+  "schema_version": "1.0"
+}

request-level/c3/qwen3-4b/router_config.json

@@ -0,0 +1,132 @@
+{
+  "artifact_id": "intraining-mean-qwen3-4b-r4-epoch-002-step-074910",
+  "created_utc": "2026-07-20T04:35:36.278433+00:00",
+  "domain_outputs": [
+    {
+      "domain_id": 0,
+      "expert_id": "code",
+      "label": "code"
+    },
+    {
+      "domain_id": 1,
+      "expert_id": "math",
+      "label": "math"
+    },
+    {
+      "domain_id": 2,
+      "expert_id": "factual_qa",
+      "label": "factual_qa"
+    },
+    {
+      "domain_id": 3,
+      "expert_id": "creative_writing",
+      "label": "creative_writing"
+    },
+    {
+      "domain_id": 4,
+      "expert_id": "general",
+      "label": "general"
+    }
+  ],
+  "feature_contract": {
+    "dropout_at_evaluation": false,
+    "feature_dim": 12800,
+    "hidden_size": 2560,
+    "inference_compute_dtype": "bfloat16 (matches training forward)",
+    "max_length": 3072,
+    "pooling": "mean_over_all_attended_prompt_tokens",
+    "prompt_template": "<|im_start|>system\\nYou are a helpful assistant.<|im_end|>\\n<|im_start|>user\\n{content}<|im_end|>\\n<|im_start|>assistant\\n",
+    "target_backend": "sglang (same capture path as Arm-B training)",
+    "target_layer_ids": [
+      1,
+      9,
+      17,
+      25,
+      33
+    ]
+  },
+  "head": {
+    "architecture": "LayerNorm(12800)->Linear(12800,512)->GELU->Dropout(0.2)->Linear(512,5)",
+    "dropout": 0.2,
+    "dropout_at_evaluation": false,
+    "hidden_dim": 512,
+    "input_dim": 12800,
+    "output_dim": 5
+  },
+  "paper_alias": "C3",
+  "provenance": {
+    "pre_export_source_tensor_sha256": {
+      "router_head.0.bias": "8f226e631487e84cd3f7f6bcc8c3bb84622cd6b678d290458531d4e543db1fd9",
+      "router_head.0.weight": "dc5eb0e053dbc5f84988445bcad64a5bd478a1911d8f962cb650960b971d1980",
+      "router_head.1.bias": "806fe5f22d8e175bdb1753b50e8968c2711dd82b9a035135a011d796de9e9838",
+      "router_head.1.weight": "7999df7bfb58ea932f0f75a4823df7e69000fd2cd1e58ae659fc6362278cfa52",
+      "router_head.4.bias": "c49ea773ce1a43279f8905ed2243269ff1265d3c684442055ef7c38021672374",
+      "router_head.4.weight": "bbd3a2753c5191607ac09a2c8a3790e065f0772051711d85d4538fe07c0c3743"
+    },
+    "source_checkpoint_config_sha256": "df69894933c784aaa6a7eb41717dc03df2845d856c4cf08fefa91ce1b4d53f62",
+    "source_checkpoint_model_sha256": "cda9721a37fc0766ea462608f8af7c3a4f9f0391e1bdf863f847d0dceff15f66",
+    "source_metadata_sha256": "17b1b5373e8e0ec34be35d0ab7c97d7a3ed9536847b1293b00f373d15b129dd4",
+    "target_backend_implementation_sha256": "654b43cb3a646bda857a5cc3091027f1ef382bcf333f80137b3e597d2572d888",
+    "target_config_sha256": "8ba006f74fecfaaeb392872a60f4a480e7ec9860153d2e1b769ec81f9a147f8a"
+  },
+  "router_kind": "request-level",
+  "schema_version": "1.0",
+  "source_snapshot_id": "epoch-002-step-074910",
+  "status": "experimental",
+  "target_model": {
+    "repo_id": "Qwen/Qwen3-4B",
+    "revision": "1cfa9a7208912126459214e8b04321603b3df60c"
+  },
+  "weights": {
+    "filename": "router_head.safetensors",
+    "format": "safetensors",
+    "sha256": "f1a353e667df2320202daa8bd33101623335dba7f8c3b3e17d5c1f30d694f2f6",
+    "size_bytes": 13165082,
+    "tensor_info": {
+      "router_head.0.bias": {
+        "dtype": "bfloat16",
+        "sha256": "c5543a99083d6270f50eadd20f86aa1fef14ab3b7f582603721b831db6ae9d19",
+        "shape": [
+          12800
+        ]
+      },
+      "router_head.0.weight": {
+        "dtype": "bfloat16",
+        "sha256": "a9f7df25661cae17ec5ce8afae0862845f247aed85e719b21387c0574a2c2702",
+        "shape": [
+          12800
+        ]
+      },
+      "router_head.1.bias": {
+        "dtype": "bfloat16",
+        "sha256": "7d078914ce63c4d485e8682b9c4f718fbd5a76cdecb1df472ed48c1998511a46",
+        "shape": [
+          512
+        ]
+      },
+      "router_head.1.weight": {
+        "dtype": "bfloat16",
+        "sha256": "ec58c348a3d18276a7e52304227a57a63776677012e90ab1f81137bf0953b4a9",
+        "shape": [
+          512,
+          12800
+        ]
+      },
+      "router_head.4.bias": {
+        "dtype": "bfloat16",
+        "sha256": "f8c6fa4694e452b7675f540e9fb92260f82f585009e7cb01316eec66344d6b26",
+        "shape": [
+          5
+        ]
+      },
+      "router_head.4.weight": {
+        "dtype": "bfloat16",
+        "sha256": "3541b9619042d7f179271249e55ef0f27705ab4edb369bbd61caa5c19b64a0b3",
+        "shape": [
+          5,
+          512
+        ]
+      }
+    }
+  }
+}

request-level/c3/qwen3-4b/router_head.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f1a353e667df2320202daa8bd33101623335dba7f8c3b3e17d5c1f30d694f2f6
+size 13165082

request-level/intraining-sidecar/qwen3-8b/router_config.json

@@ -0,0 +1,128 @@
+{
+  "artifact_id": "intraining-sidecar-qwen3-8b-epoch-000-step-002341",
+  "created_utc": "2026-07-19T04:26:37.133107+00:00",
+  "domain_outputs": [
+    {
+      "domain_id": 0,
+      "expert_id": "code",
+      "label": "code"
+    },
+    {
+      "domain_id": 1,
+      "expert_id": "math",
+      "label": "math"
+    },
+    {
+      "domain_id": 2,
+      "expert_id": "factual_qa",
+      "label": "factualqa"
+    },
+    {
+      "domain_id": 3,
+      "expert_id": "creative_writing",
+      "label": "creativewriting"
+    },
+    {
+      "domain_id": 4,
+      "expert_id": "general",
+      "label": "general"
+    }
+  ],
+  "feature_contract": {
+    "dropout_at_serving": false,
+    "feature_dim": 20480,
+    "feature_standardization": null,
+    "hidden_state_offset": 1,
+    "max_length": 3072,
+    "pooling": "mean_over_prompt_tokens",
+    "prompt_template": "<|im_start|>system\\nYou are a helpful assistant.<|im_end|>\\n<|im_start|>user\\n{content}<|im_end|>\\n<|im_start|>assistant\\n",
+    "target_layer_ids": [
+      1,
+      9,
+      17,
+      25,
+      33
+    ]
+  },
+  "head": {
+    "architecture": "LayerNorm(20480)->Linear(20480,512)->GELU->Dropout(0.2)->Linear(512,5)",
+    "dropout": 0.2,
+    "dropout_at_evaluation": false,
+    "hidden_dim": 512,
+    "input_dim": 20480,
+    "output_dim": 5
+  },
+  "provenance": {
+    "pre_export_source_tensor_sha256": {
+      "router_head.0.bias": "12258f6171230eca45b8e32a6c71de18d8da183159b26e6d46431dafdedd4e46",
+      "router_head.0.weight": "9da7066800a1d526656318e182f3f8675ba439b216be323e6b99bb5ab854419d",
+      "router_head.1.bias": "1dca0bef5b54b6cd21aa52e8b42fb13cf7b2110e5eb28302e5eabcb8c59c4c1e",
+      "router_head.1.weight": "2c5adde4909f8b3c92a7669790a7ca3de122bc4d4f1d086e9a4398878e59572f",
+      "router_head.4.bias": "c4cc7c266d132dfea19baa792e5a9a347d48272504ebf6a9f1c97892df955d3e",
+      "router_head.4.weight": "b7f92fe5bda71e837ae4979606c3ec07afbe991a2338422a110d63251e83c425"
+    },
+    "source_checkpoint_config_sha256": "52f8597dcb666d4e7e9136ef00af5a502ccc20be48dfefe35eabc389d553011f",
+    "source_checkpoint_index_sha256": "fad5709071910e254838e40c51a601541dbaab181ac508afa3f52002f11fbe28",
+    "source_metadata_sha256": "b15ff65196f41c0c99a9e6fc87ad3f4251698ac083c618859a83b523a745e67b"
+  },
+  "router_kind": "request-level",
+  "schema_version": "1.0",
+  "source_snapshot_id": "epoch-000-step-002341",
+  "status": "experimental",
+  "target_model": {
+    "repo_id": "Qwen/Qwen3-8B",
+    "revision": "b968826d9c46dd6066d109eabc6255188de91218"
+  },
+  "weights": {
+    "filename": "router_head.safetensors",
+    "format": "safetensors",
+    "sha256": "d0332bd1c37ef498de4b3157f7403d96709b4f641c5a765134fa45ae71d45d98",
+    "size_bytes": 21060122,
+    "tensor_info": {
+      "router_head.0.bias": {
+        "dtype": "bfloat16",
+        "sha256": "2d28be30d37b490e9a195a0ebde656f27eff287576846370e1e1339927c0533b",
+        "shape": [
+          20480
+        ]
+      },
+      "router_head.0.weight": {
+        "dtype": "bfloat16",
+        "sha256": "d1d5fe35f4860164fa1d792785f985681770bba65410f30d064e8678b9b34773",
+        "shape": [
+          20480
+        ]
+      },
+      "router_head.1.bias": {
+        "dtype": "bfloat16",
+        "sha256": "ff2ca250d24324f3ce6cbe5e0c8360d29662f6a13d4426bd6a9fcec3b475ab71",
+        "shape": [
+          512
+        ]
+      },
+      "router_head.1.weight": {
+        "dtype": "bfloat16",
+        "sha256": "4490d2940bcd0dcf7ea880429e8b2cca6526228a2adbfa2322b7100f665d0901",
+        "shape": [
+          512,
+          20480
+        ]
+      },
+      "router_head.4.bias": {
+        "dtype": "bfloat16",
+        "sha256": "4142aa8de41a17fc6cdfa37efc665d0caa7535d3174aabf0c5cb87a5f5bac5f4",
+        "shape": [
+          5
+        ]
+      },
+      "router_head.4.weight": {
+        "dtype": "bfloat16",
+        "sha256": "dab62389367b90bafda0af396886021b3712bb4201f1e313042973a03508ebb5",
+        "shape": [
+          5,
+          512
+        ]
+      }
+    }
+  }
+}

request-level/intraining-sidecar/qwen3-8b/router_head.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d0332bd1c37ef498de4b3157f7403d96709b4f641c5a765134fa45ae71d45d98
+size 21060122

request-level/offline-v2/qwen3-8b/router_config.json

@@ -0,0 +1,211 @@
+{
+  "artifact_id": "offline-v2-qwen3-8b",
+  "domain_outputs": [
+    {
+      "domain_id": 0,
+      "expert_id": "code",
+      "label": "code"
+    },
+    {
+      "domain_id": 1,
+      "expert_id": "math",
+      "label": "math"
+    },
+    {
+      "domain_id": 2,
+      "expert_id": "factual_qa",
+      "label": "factualqa"
+    },
+    {
+      "domain_id": 3,
+      "expert_id": "creative_writing",
+      "label": "creativewriting"
+    },
+    {
+      "domain_id": 4,
+      "expert_id": "general",
+      "label": "general"
+    }
+  ],
+  "feature_contract": {
+    "concatenation_order": "pool-major-over-concatenated-layers",
+    "feature_dim": 61440,
+    "hidden_size_per_layer": 4096,
+    "hidden_state_offset": 1,
+    "max_length": 3072,
+    "pooling": [
+      "mean",
+      "max",
+      "last"
+    ],
+    "pooling_scope": "all-attended-prompt-tokens",
+    "prompt_template": "<|im_start|>system\\nYou are a helpful assistant.<|im_end|>\\n<|im_start|>user\\n{content}<|im_end|>\\n<|im_start|>assistant\\n",
+    "standardization": {
+      "clamp": [
+        -10.0,
+        10.0
+      ],
+      "dead_dimension_value": 0.0,
+      "dead_std_threshold": 2e-06,
+      "mean_tensor": "feature_mean",
+      "std_floor": 1e-06,
+      "std_tensor": "feature_std"
+    },
+    "target_layer_ids": [
+      1,
+      9,
+      17,
+      25,
+      33
+    ]
+  },
+  "head": {
+    "architecture": "zscore->LayerNorm->Linear(d,h)->GELU->Dropout->Linear(h,5)",
+    "dropout": 0.3,
+    "dropout_at_evaluation": false,
+    "hidden_dim": 512,
+    "input_dim": 61440,
+    "output_dim": 5
+  },
+  "router_kind": "request-level",
+  "schema_version": "1.0",
+  "selection_metrics": {
+    "confusion": [
+      [
+        84,
+        0,
+        2,
+        1,
+        2
+      ],
+      [
+        0,
+        34,
+        0,
+        0,
+        1
+      ],
+      [
+        1,
+        0,
+        42,
+        1,
+        3
+      ],
+      [
+        0,
+        0,
+        0,
+        26,
+        4
+      ],
+      [
+        2,
+        4,
+        7,
+        6,
+        36
+      ]
+    ],
+    "overall": 0.8671875,
+    "per_class_recall": [
+      0.9438202247191011,
+      0.9714285714285714,
+      0.8936170212765957,
+      0.8666666666666667,
+      0.6545454545454545
+    ]
+  },
+  "status": "experimental",
+  "target_model": {
+    "repo_id": "Qwen/Qwen3-8B",
+    "revision": "b968826d9c46dd6066d109eabc6255188de91218"
+  },
+  "training_hyperparameters": {
+    "bs": 256,
+    "ep": 100,
+    "focal": true,
+    "gamma": 2,
+    "genw": 1.6,
+    "lr": 0.001,
+    "ls": 0.0,
+    "use_pools": [
+      "mean",
+      "max",
+      "last"
+    ],
+    "wd": 0.01
+  },
+  "weights": {
+    "conversion": {
+      "loader_policy": "torch.load(weights_only=True)",
+      "source_container_published": false,
+      "source_container_sha256": "0621f22b66a778e1e3a7a4d8d35411d7293b699a233f1e1e983fdb5afb4359d0",
+      "tensor_equality_verified": true
+    },
+    "filename": "router_head.safetensors",
+    "format": "safetensors",
+    "sha256": "007a5298d372db09fcb577b9e437227c8773430b2702e7e55f57f15efeafda2b",
+    "size_bytes": 126825196,
+    "tensor_info": {
+      "f1.bias": {
+        "dtype": "float32",
+        "sha256": "36f71391a40475a8034100b352c84a80f61c7cceb63bec4c6050f660d9d6d3e9",
+        "shape": [
+          512
+        ]
+      },
+      "f1.weight": {
+        "dtype": "float32",
+        "sha256": "4cc3edfd26e621c8fb5b36aa0b952a54e1fca56c40e20e402be4342bdbd184a1",
+        "shape": [
+          512,
+          61440
+        ]
+      },
+      "f2.bias": {
+        "dtype": "float32",
+        "sha256": "8d314d9a61c6bc2467711956729f38a8a1a919a5e8c5cf14c4ad7c3db4e7de00",
+        "shape": [
+          5
+        ]
+      },
+      "f2.weight": {
+        "dtype": "float32",
+        "sha256": "027a31a5c6198ac046e22cf6dc2d4701de94d6cd145e89dad015ddf10e11620e",
+        "shape": [
+          5,
+          512
+        ]
+      },
+      "feature_mean": {
+        "dtype": "float32",
+        "sha256": "0311eaec869dad77a8add17c36bd1a4db1cfbb010ed6456faf232a730c9b5473",
+        "shape": [
+          61440
+        ]
+      },
+      "feature_std": {
+        "dtype": "float32",
+        "sha256": "1703e25da7eb4d6a3ca024bb78bf47a844abcf70f55ce65c675d0e5016f1f6c2",
+        "shape": [
+          61440
+        ]
+      },
+      "n.bias": {
+        "dtype": "float32",
+        "sha256": "f45b2861c3770f0c22b2349920c1f1947b399b9f222b8c6b3b6dcdbcdd174e0a",
+        "shape": [
+          61440
+        ]
+      },
+      "n.weight": {
+        "dtype": "float32",
+        "sha256": "2f8998fc8e47a5bc193a32d14a5549a519d1f3d5815acf3b061b748e7e0b8249",
+        "shape": [
+          61440
+        ]
+      }
+    }
+  }
+}

request-level/offline-v2/qwen3-8b/router_head.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:007a5298d372db09fcb577b9e437227c8773430b2702e7e55f57f15efeafda2b
+size 126825196

request-level/offline-v2/qwen3-8b/selection_sweep.json

@@ -0,0 +1,193 @@
+{
+  "results": [
+    {
+      "ho_overall": 0.8515625,
+      "ho_recall": [
+        0.9438202247191011,
+        0.9428571428571428,
+        0.8723404255319149,
+        0.9333333333333333,
+        0.5818181818181818
+      ],
+      "name": "meanlast ce gw1.3 d.2",
+      "pools": [
+        "mean",
+        "last"
+      ],
+      "val": 0.8585016131401062
+    },
+    {
+      "ho_overall": 0.8515625,
+      "ho_recall": [
+        0.9213483146067416,
+        0.9142857142857143,
+        0.851063829787234,
+        0.9333333333333333,
+        0.6545454545454545
+      ],
+      "name": "full ce gw1.3 d.3",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8573335409164429
+    },
+    {
+      "ho_overall": 0.859375,
+      "ho_recall": [
+        0.9325842696629213,
+        0.9428571428571428,
+        0.8936170212765957,
+        0.9333333333333333,
+        0.6181818181818182
+      ],
+      "name": "full ce gw1.6 d.3",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8556649684906006
+    },
+    {
+      "ho_overall": 0.859375,
+      "ho_recall": [
+        0.9325842696629213,
+        0.9142857142857143,
+        0.8723404255319149,
+        0.9333333333333333,
+        0.6545454545454545
+      ],
+      "name": "full ce gw2.0 d.3",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8563323616981506
+    },
+    {
+      "ho_overall": 0.84765625,
+      "ho_recall": [
+        0.9213483146067416,
+        0.8857142857142857,
+        0.8297872340425532,
+        0.9333333333333333,
+        0.6727272727272727
+      ],
+      "name": "full focal gw1.0 d.3",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8516602516174316
+    },
+    {
+      "ho_overall": 0.84375,
+      "ho_recall": [
+        0.9325842696629213,
+        0.9142857142857143,
+        0.8297872340425532,
+        0.9,
+        0.6363636363636364
+      ],
+      "name": "full focal gw1.3 d.3",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8531620502471924
+    },
+    {
+      "ho_overall": 0.8671875,
+      "ho_recall": [
+        0.9438202247191011,
+        0.9714285714285714,
+        0.8936170212765957,
+        0.8666666666666667,
+        0.6545454545454545
+      ],
+      "name": "full focal gw1.6 d.3",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8536626100540161
+    },
+    {
+      "ho_overall": 0.84765625,
+      "ho_recall": [
+        0.898876404494382,
+        0.9428571428571428,
+        0.8723404255319149,
+        0.8666666666666667,
+        0.6727272727272727
+      ],
+      "name": "full focal gw2.0 d.3",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8543300628662109
+    },
+    {
+      "ho_overall": 0.84765625,
+      "ho_recall": [
+        0.9213483146067416,
+        0.9142857142857143,
+        0.7872340425531915,
+        0.8666666666666667,
+        0.7272727272727273
+      ],
+      "name": "full focal gw1.6 d.4 wd3e-2",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8523277044296265
+    },
+    {
+      "ho_overall": 0.8671875,
+      "ho_recall": [
+        0.9213483146067416,
+        0.9714285714285714,
+        0.8936170212765957,
+        0.9333333333333333,
+        0.6545454545454545
+      ],
+      "name": "full ce gw1.6 d.4 wd3e-2",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8581678867340088
+    },
+    {
+      "ho_overall": 0.83984375,
+      "ho_recall": [
+        0.898876404494382,
+        0.9142857142857143,
+        0.8085106382978723,
+        0.9333333333333333,
+        0.6727272727272727
+      ],
+      "name": "full focal gw2.5 d.3",
+      "pools": [
+        "mean",
+        "max",
+        "last"
+      ],
+      "val": 0.8521608710289001
+    }
+  ],
+  "schema_version": "1.0",
+  "selection_rule": "highest held-out overall accuracy",
+  "source_sha256": "3d742dde0322f7d57f81b7902c41bfb9b58b1030c3edb0c9b473659705473d5a"
+}

requirements.txt

@@ -0,0 +1,3 @@
+torch>=2.1
+safetensors>=0.4
+

router_loader.py

@@ -0,0 +1,126 @@
+"""Minimal loaders for the public MoS/DFlash request-level router artifacts."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import torch
+from safetensors.torch import load_file
+from torch import nn
+
+
+class OfflineV2Head(nn.Module):
+    def __init__(self, input_dim: int, hidden_dim: int, output_dim: int, dropout: float):
+        super().__init__()
+        self.n = nn.LayerNorm(input_dim)
+        self.f1 = nn.Linear(input_dim, hidden_dim)
+        self.dropout = nn.Dropout(dropout)
+        self.f2 = nn.Linear(hidden_dim, output_dim)
+
+    def forward(self, features: torch.Tensor) -> torch.Tensor:
+        hidden = torch.nn.functional.gelu(self.f1(self.n(features)))
+        return self.f2(self.dropout(hidden))
+
+
+class SidecarHead(nn.Module):
+    def __init__(self, input_dim: int, hidden_dim: int, output_dim: int, dropout: float):
+        super().__init__()
+        self.router_head = nn.Sequential(
+            nn.LayerNorm(input_dim),
+            nn.Linear(input_dim, hidden_dim),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(hidden_dim, output_dim),
+        )
+
+    def forward(self, features: torch.Tensor) -> torch.Tensor:
+        return self.router_head(features)
+
+
+def _read_config(path: str | Path) -> dict[str, Any]:
+    value = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError("router config must be a JSON object")
+    return value
+
+
+def load_offline_v2(
+    weights_path: str | Path,
+    config_path: str | Path,
+    *,
+    device: str | torch.device = "cpu",
+) -> tuple[OfflineV2Head, torch.Tensor, torch.Tensor, dict[str, Any]]:
+    config = _read_config(config_path)
+    tensors = load_file(str(weights_path), device=str(device))
+    expected = {
+        "n.weight",
+        "n.bias",
+        "f1.weight",
+        "f1.bias",
+        "f2.weight",
+        "f2.bias",
+        "feature_mean",
+        "feature_std",
+    }
+    if set(tensors) != expected:
+        raise ValueError(f"unexpected offline-v2 tensor keys: {sorted(tensors)}")
+    head_config = config["head"]
+    head = OfflineV2Head(
+        input_dim=int(head_config["input_dim"]),
+        hidden_dim=int(head_config["hidden_dim"]),
+        output_dim=int(head_config["output_dim"]),
+        dropout=float(head_config["dropout"]),
+    )
+    head.load_state_dict(
+        {key: value for key, value in tensors.items() if key not in {"feature_mean", "feature_std"}},
+        strict=True,
+    )
+    head.to(device).eval()
+    return head, tensors["feature_mean"], tensors["feature_std"], config
+
+
+def prepare_offline_features(
+    features: torch.Tensor,
+    feature_mean: torch.Tensor,
+    feature_std: torch.Tensor,
+    *,
+    dead_std_threshold: float = 2e-6,
+    clamp_abs: float = 10.0,
+) -> torch.Tensor:
+    safe_std = feature_std.clamp_min(1e-6)
+    normalized = (features - feature_mean) / safe_std
+    normalized = normalized.masked_fill(feature_std <= dead_std_threshold, 0)
+    return normalized.clamp(-clamp_abs, clamp_abs)
+
+
+def load_sidecar(
+    weights_path: str | Path,
+    config_path: str | Path,
+    *,
+    device: str | torch.device = "cpu",
+) -> tuple[SidecarHead, dict[str, Any]]:
+    config = _read_config(config_path)
+    tensors = load_file(str(weights_path), device=str(device))
+    expected = {
+        "router_head.0.weight",
+        "router_head.0.bias",
+        "router_head.1.weight",
+        "router_head.1.bias",
+        "router_head.4.weight",
+        "router_head.4.bias",
+    }
+    if set(tensors) != expected:
+        raise ValueError(f"unexpected sidecar tensor keys: {sorted(tensors)}")
+    head_config = config["head"]
+    head = SidecarHead(
+        input_dim=int(head_config["input_dim"]),
+        hidden_dim=int(head_config["hidden_dim"]),
+        output_dim=int(head_config["output_dim"]),
+        dropout=float(head_config["dropout"]),
+    )
+    head.load_state_dict(tensors, strict=True)
+    head.to(device).eval()
+    return head, config
+

schema/router_config.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://huggingface.co/ryan-0608/MoS-DFlash-Routers/raw/main/schema/router_config.schema.json",
+  "title": "MoS DFlash request-level router config",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "artifact_id",
+    "router_kind",
+    "status",
+    "target_model",
+    "domain_outputs",
+    "feature_contract",
+    "head",
+    "weights"
+  ],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "artifact_id": {"type": "string", "minLength": 1},
+    "router_kind": {"const": "request-level"},
+    "status": {"const": "experimental"},
+    "target_model": {
+      "type": "object",
+      "required": ["repo_id", "revision"],
+      "properties": {
+        "repo_id": {"type": "string", "minLength": 1},
+        "revision": {"type": "string", "pattern": "^[0-9a-f]{40}$"}
+      },
+      "additionalProperties": false
+    },
+    "domain_outputs": {
+      "type": "array",
+      "minItems": 5,
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "required": ["domain_id", "label", "expert_id"],
+        "properties": {
+          "domain_id": {"type": "integer", "minimum": 0, "maximum": 4},
+          "label": {"type": "string"},
+          "expert_id": {"type": "string"}
+        },
+        "additionalProperties": false
+      }
+    },
+    "feature_contract": {"type": "object"},
+    "head": {
+      "type": "object",
+      "required": ["input_dim", "hidden_dim", "output_dim", "dropout"],
+      "properties": {
+        "input_dim": {"type": "integer", "minimum": 1},
+        "hidden_dim": {"type": "integer", "minimum": 1},
+        "output_dim": {"const": 5},
+        "dropout": {"type": "number", "minimum": 0, "maximum": 1}
+      },
+      "additionalProperties": true
+    },
+    "weights": {
+      "type": "object",
+      "required": ["filename", "format", "sha256", "size_bytes"],
+      "properties": {
+        "filename": {"const": "router_head.safetensors"},
+        "format": {"const": "safetensors"},
+        "sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+        "size_bytes": {"type": "integer", "minimum": 1}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}
+

verification/structural_validation.json

@@ -0,0 +1,28 @@
+{
+  "c3_qwen3_4b": {
+    "finite_forward": true,
+    "safetensors_structure": true,
+    "strict_loader": true
+  },
+  "excluded": [
+    "raw-pickle-checkpoints",
+    "hidden-state-features",
+    "raw-prompts",
+    "per-sample-routing-records",
+    "training-logs"
+  ],
+  "intraining_sidecar_qwen3_8b": {
+    "finite_forward": true,
+    "safetensors_structure": true,
+    "strict_loader": true
+  },
+  "offline_v2": {
+    "finite_forward": true,
+    "strict_loader": true,
+    "tensor_equality_after_conversion": true,
+    "weights_only_source_load": true
+  },
+  "schema_version": "1.0",
+  "scope": "conversion-and-structural-load-only",
+  "task_level_parity_verified": false
+}