doppler-gpu 0.5.1 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (953) hide show
  1. package/CHANGELOG.md +33 -577
  2. package/LICENSE +21 -201
  3. package/README.md +165 -222
  4. package/models/catalog.json +241 -33
  5. package/package.json +106 -87
  6. package/src/capsule-runtime.d.ts +25 -0
  7. package/src/capsule-runtime.js +24 -0
  8. package/src/capsule.d.ts +8 -0
  9. package/src/capsule.js +4 -0
  10. package/src/cli/argument-contract.js +200 -0
  11. package/src/cli/browser-report-output.js +24 -0
  12. package/src/cli/cli-model-resolution.js +2 -2
  13. package/src/cli/cli-output.js +10 -0
  14. package/src/cli/commands/bundle.js +828 -0
  15. package/src/cli/doppler-cli.js +50 -1457
  16. package/src/cli/doppler-serve.js +18 -244
  17. package/src/cli/output/manifest.js +368 -0
  18. package/src/cli/runtime-profiles.js +1 -1
  19. package/src/cli/serve/capsule-handler.d.ts +33 -0
  20. package/src/cli/serve/capsule-handler.js +105 -0
  21. package/src/cli/serve/capsule-http.js +102 -0
  22. package/src/cli/serve/receipt.js +269 -0
  23. package/src/client/capsule-host.browser.js +2 -0
  24. package/src/client/capsule-host.d.ts +5 -0
  25. package/src/client/capsule-host.js +2 -0
  26. package/src/client/doppler-api.browser.js +42 -0
  27. package/src/client/doppler-api.d.ts +38 -1
  28. package/src/client/doppler-api.js +41 -1
  29. package/src/client/doppler-registry.js +15 -7
  30. package/src/client/electron/index.d.ts +4 -0
  31. package/src/client/electron/index.js +13 -0
  32. package/src/client/electron/ipc-contract.d.ts +9 -0
  33. package/src/client/electron/ipc-contract.js +56 -0
  34. package/src/client/electron/release-state.d.ts +53 -0
  35. package/src/client/electron/release-state.js +425 -0
  36. package/src/client/electron/renderer-runtime.d.ts +19 -0
  37. package/src/client/electron/renderer-runtime.js +104 -0
  38. package/src/client/failure-taxonomy.js +1 -28
  39. package/src/client/fault-injection.js +0 -8
  40. package/src/client/inspection.js +1 -1
  41. package/src/client/model-host/index.d.ts +140 -0
  42. package/src/client/model-host/index.js +548 -0
  43. package/src/client/model-host/model-evidence.js +255 -0
  44. package/src/client/model-host/model-session.d.ts +323 -0
  45. package/src/client/{runtime → model-host}/model-session.js +202 -148
  46. package/src/client/provider.d.ts +18 -2
  47. package/src/client/provider.js +26 -3
  48. package/src/client/receipt.js +30 -72
  49. package/src/client/runtime/capsule-acquisition.d.ts +18 -0
  50. package/src/client/runtime/capsule-acquisition.js +103 -0
  51. package/src/client/runtime/capsule-adapter-execution.d.ts +17 -0
  52. package/src/client/runtime/capsule-adapter-execution.js +63 -0
  53. package/src/client/runtime/capsule-artifact-source.js +62 -0
  54. package/src/client/runtime/capsule-embedding.d.ts +29 -0
  55. package/src/client/runtime/capsule-embedding.js +76 -0
  56. package/src/client/runtime/capsule-forecast-program.d.ts +2 -0
  57. package/src/client/runtime/capsule-forecast-program.js +85 -0
  58. package/src/client/runtime/capsule-forecast.d.ts +17 -0
  59. package/src/client/runtime/capsule-forecast.js +31 -0
  60. package/src/client/runtime/capsule-operation-adapters.d.ts +12 -0
  61. package/src/client/runtime/capsule-operation-adapters.js +69 -0
  62. package/src/client/runtime/capsule-operation-executor.d.ts +25 -0
  63. package/src/client/runtime/capsule-operation-executor.js +101 -0
  64. package/src/client/runtime/capsule-program-adapter.js +153 -0
  65. package/src/client/runtime/capsule-release-authorization.js +25 -0
  66. package/src/client/runtime/capsule-rerank.d.ts +50 -0
  67. package/src/client/runtime/capsule-rerank.js +105 -0
  68. package/src/client/runtime/capsule-session-execution.js +89 -0
  69. package/src/client/runtime/command-executor.d.ts +15 -0
  70. package/src/client/runtime/command-executor.js +128 -0
  71. package/src/client/runtime/composition-root.d.ts +77 -0
  72. package/src/client/runtime/composition-root.js +352 -0
  73. package/src/client/runtime/fetch-capsule-artifact-store.d.ts +10 -0
  74. package/src/client/runtime/fetch-capsule-artifact-store.js +25 -0
  75. package/src/client/runtime/index.d.ts +1 -117
  76. package/src/client/runtime/index.js +1 -433
  77. package/src/client/runtime/lora.d.ts +14 -0
  78. package/src/client/runtime/lora.js +19 -1
  79. package/src/client/runtime/model-manager.js +12 -0
  80. package/src/client/runtime/model-rerank.js +30 -0
  81. package/src/client/runtime/model-session.d.ts +1 -221
  82. package/src/client/runtime/model-source.d.ts +9 -0
  83. package/src/client/runtime/model-source.js +46 -17
  84. package/src/client/runtime/node-quickstart-cache.js +1 -1
  85. package/src/client/runtime/resolution-policy.d.ts +20 -0
  86. package/src/client/runtime/resolution-policy.js +84 -0
  87. package/src/client/runtime/resource-binder.d.ts +24 -0
  88. package/src/client/runtime/resource-binder.js +135 -0
  89. package/src/client/runtime/scoped-session.d.ts +10 -1
  90. package/src/client/runtime/scoped-session.js +20 -1
  91. package/src/client/runtime/session-controller.d.ts +19 -0
  92. package/src/client/runtime/session-controller.js +92 -0
  93. package/src/client/runtime/source-runtime.js +1 -1
  94. package/src/client/runtime/target-selector.d.ts +9 -0
  95. package/src/client/runtime/target-selector.js +2 -0
  96. package/src/client/runtime/types.d.ts +1 -0
  97. package/src/client/runtime/verified-capsule-artifact-store.js +101 -0
  98. package/src/client/wrap-pipeline-handle.js +3 -9
  99. package/src/config/backward-registry-loader.js +1 -1
  100. package/src/config/capsule-adapter-policy.js +30 -0
  101. package/src/config/capsule-adapters.d.ts +21 -0
  102. package/src/config/capsule-adapters.js +40 -0
  103. package/src/config/capsule-adapters.json +9 -0
  104. package/src/config/capsule-loading.d.ts +2 -0
  105. package/src/config/capsule-loading.js +14 -0
  106. package/src/config/capsule-loading.schema.json +12 -0
  107. package/src/config/capsule-operation.d.ts +19 -0
  108. package/src/config/capsule-operation.js +63 -0
  109. package/src/config/capsule-operations.json +17 -0
  110. package/src/config/capsule-release-contract.d.ts +66 -0
  111. package/src/config/capsule-release-contract.js +197 -0
  112. package/src/config/capsule-release-events.d.ts +53 -0
  113. package/src/config/capsule-release-events.js +172 -0
  114. package/src/config/capsule-sequence-receipt.js +19 -0
  115. package/src/config/capsule-serve.d.ts +9 -0
  116. package/src/config/capsule-serve.js +28 -0
  117. package/src/config/capsule-serve.schema.json +14 -0
  118. package/src/config/capsule-signature.d.ts +6 -0
  119. package/src/config/capsule-signature.js +50 -0
  120. package/src/config/capsule-v2.d.ts +70 -0
  121. package/src/config/capsule-v2.js +431 -0
  122. package/src/config/capsule-v3.d.ts +19 -0
  123. package/src/config/capsule-v3.js +72 -0
  124. package/src/config/capsule.d.ts +22 -0
  125. package/src/config/capsule.js +52 -0
  126. package/src/config/conversion/amplify/amplify-120m-f16-af32.json +1 -1
  127. package/src/config/conversion/diffusiongemma/diffusiongemma-26b-a4b-it-q4k-ehf16-af16.json +3 -3
  128. package/src/config/conversion/embeddinggemma/google-embeddinggemma-300m-q4k-ehf16-af32.json +2 -2
  129. package/src/config/conversion/esm/esm2-t12-35m-ur50d-f32-af32.json +62 -4
  130. package/src/config/conversion/esmc/esmc-300m-f32-af32.json +1 -1
  131. package/src/config/conversion/gemma3/gemma-3-1b-it-f16-af32.json +2 -2
  132. package/src/config/conversion/gemma3/gemma-3-1b-it-q4k-ehf16-af32.json +3 -3
  133. package/src/config/conversion/gemma3/gemma-3-270m-it-f16-af32.json +3 -3
  134. package/src/config/conversion/gemma3/gemma-3-270m-it-q4k-ehf16-af16.json +3 -3
  135. package/src/config/conversion/gemma3/gemma-3-270m-it-q4k-ehf16-af32.json +3 -3
  136. package/src/config/conversion/gemma3/translategemma-4b-1b-enes-q4k-ehf16-af32.json +3 -3
  137. package/src/config/conversion/gemma3/translategemma-4b-it-q4k-ehf16-af32.json +3 -3
  138. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-af16.json +5 -5
  139. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-af32.json +4 -4
  140. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-hq4k-af16.json +6 -6
  141. package/src/config/conversion/gemma4/gemma-4-12b-it-text-w4a16-ct-ehf16-af16.json +3 -3
  142. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af16.json +5 -5
  143. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af32.json +4 -4
  144. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af16-int4ple.json +6 -6
  145. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32-int4ple.json +3 -3
  146. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32.json +3 -3
  147. package/src/config/conversion/gemma4/gemma-4-moe-q4k-ehf16-af32.json +2 -2
  148. package/src/config/conversion/glmocr/glm-ocr-f16-af32.json +442 -0
  149. package/src/config/conversion/gpt-oss-20b-f16-xmxfp4.json +2 -2
  150. package/src/config/conversion/janus/janus-pro-1b-text-q4k-ehaf16.json +2 -2
  151. package/src/config/conversion/lfm2/lfm2.5-1.2b-instruct-q4k-ehf16-af32.json +2 -2
  152. package/src/config/conversion/minicpm/minicpm4-0-5b-f16-af32.json +3 -3
  153. package/src/config/conversion/muse-glimmer/muse-glimmer-30b-text-bf16-af32.json +529 -0
  154. package/src/config/conversion/muse-glimmer/muse-glimmer-30b-text-f16-af32.json +529 -0
  155. package/src/config/conversion/nucleotide-transformer/nucleotide-transformer-v2-50m-f32-af32.json +1 -1
  156. package/src/config/conversion/qwen3/qwen-3-5-0-8b-q4k-ehaf16.json +6 -6
  157. package/src/config/conversion/qwen3/qwen-3-5-2b-q4k-ehaf16.json +6 -6
  158. package/src/config/conversion/qwen3/qwen-3-5-9b-f16-af32.json +1 -1
  159. package/src/config/conversion/qwen3/qwen-3-5-9b-q4k-ehaf16.json +6 -6
  160. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-eaf16.json +7 -7
  161. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-ehaf16.json +6 -6
  162. package/src/config/conversion/qwen3/qwen-3-embedding-0-6b-f16-af32.json +463 -0
  163. package/src/config/conversion/qwen3/qwen-3-embedding-0-6b-q4k-ehf16-af32.json +3 -3
  164. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-f16-af32.json +3 -3
  165. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-f16-true-logit-af32.json +481 -0
  166. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-q4k-ehf16-af32.json +60 -8
  167. package/src/config/conversion/qwen3/qwen3.8-27b-text-f16-af32.json +561 -0
  168. package/src/config/conversion/qwen3/qwen3.8-27b-text-q4k-ehaf16.json +558 -0
  169. package/src/config/dtype-transition-contract.js +40 -0
  170. package/src/config/embedding-contract.js +26 -0
  171. package/src/config/embedding-reference.js +85 -0
  172. package/src/config/evidence/source-intake-policy.json +1 -1
  173. package/src/config/execution-contract-check.d.ts +16 -73
  174. package/src/config/execution-contract-check.js +7 -429
  175. package/src/config/forecast-manifest.js +56 -0
  176. package/src/config/generation-contract.d.ts +39 -0
  177. package/src/config/generation-contract.js +66 -0
  178. package/src/config/generation-contract.json +32 -0
  179. package/src/config/heterogeneous-attention-contract.js +46 -0
  180. package/src/config/initial-execution-identity.d.ts +58 -0
  181. package/src/config/initial-execution-identity.js +331 -0
  182. package/src/config/kernel-path-loader.d.ts +17 -0
  183. package/src/config/kernel-path-loader.js +42 -8
  184. package/src/config/kernel-registry-contract.d.ts +25 -0
  185. package/src/config/kernel-registry-contract.js +46 -0
  186. package/src/config/kernels/kernel-ref-digests.js +66 -18
  187. package/src/config/kernels/registry.js +1 -1
  188. package/src/config/kernels/registry.json +13617 -11377
  189. package/src/config/lora-layouts.d.ts +10 -0
  190. package/src/config/lora-layouts.js +17 -0
  191. package/src/config/lora-layouts.json +9 -0
  192. package/src/config/manifest-inference-validation.js +575 -0
  193. package/src/config/merge/execution-patches.js +12 -0
  194. package/src/config/{merge-helpers.js → merge/kernel-path-policy.js} +0 -52
  195. package/src/config/merge/value-selection.js +38 -0
  196. package/src/config/merge.js +43 -11
  197. package/src/config/model-ir-v2.d.ts +57 -0
  198. package/src/config/model-ir-v2.js +258 -0
  199. package/src/config/model-ir.d.ts +49 -0
  200. package/src/config/model-ir.js +180 -0
  201. package/src/config/param-validator.js +1 -1
  202. package/src/config/platforms/amd-strix-halo-gfx1151.json +17 -0
  203. package/src/config/platforms/loader.js +2 -1
  204. package/src/config/production-release-evidence.d.ts +23 -0
  205. package/src/config/production-release-evidence.js +423 -0
  206. package/src/config/production-release.js +321 -0
  207. package/src/{client/doppler-registry.json → config/quickstart-registry.json} +7 -7
  208. package/src/config/required-inference-fields-contract-check.js +2 -2
  209. package/src/config/rerank-reference.d.ts +28 -0
  210. package/src/config/rerank-reference.js +89 -0
  211. package/src/config/revocation-policy.d.ts +65 -0
  212. package/src/config/revocation-policy.js +290 -0
  213. package/src/config/revocation-registry.json +11 -0
  214. package/src/config/revocation-updates.d.ts +68 -0
  215. package/src/config/revocation-updates.js +440 -0
  216. package/src/config/runtime/profiles/gemma4-31b-f16-activations-probe.json +1 -1
  217. package/src/config/runtime/profiles/muse-glimmer-30b-source-parity-f32kv.json +30 -0
  218. package/src/config/runtime/profiles/muse-glimmer-30b-source-parity.json +110 -0
  219. package/src/config/runtime/profiles/qwen3-6-27b-f16-activations-probe.json +1 -1
  220. package/src/config/runtime/profiles/qwen3-8-27b-source-parity.json +87 -0
  221. package/src/config/runtime-merge.js +1 -1
  222. package/src/config/runtime.js +1 -1
  223. package/src/config/schema/browser-suite-metrics.schema.d.ts +1 -0
  224. package/src/config/schema/browser-suite-metrics.schema.js +2 -0
  225. package/src/config/schema/conversion-report.schema.d.ts +3 -0
  226. package/src/config/schema/conversion-report.schema.js +29 -0
  227. package/src/config/schema/converter.schema.d.ts +1 -0
  228. package/src/config/schema/debug.schema.d.ts +1 -0
  229. package/src/config/schema/doppler.schema.js +6 -5
  230. package/src/config/schema/emulation.schema.js +1 -1
  231. package/src/config/schema/execution-v1.schema.d.ts +3 -0
  232. package/src/config/schema/execution-v1.schema.js +19 -0
  233. package/src/config/schema/harness.schema.d.ts +13 -0
  234. package/src/config/schema/harness.schema.js +6 -0
  235. package/src/config/schema/inference.schema.d.ts +21 -2
  236. package/src/config/schema/kernel-thresholds.schema.js +1 -1
  237. package/src/config/schema/manifest.schema.d.ts +26 -7
  238. package/src/config/schema/manifest.schema.js +10 -1
  239. package/src/config/schema/program-bundle.schema.d.ts +52 -6
  240. package/src/config/schema/program-bundle.schema.js +145 -10
  241. package/src/config/sequence-reference.d.ts +26 -0
  242. package/src/config/sequence-reference.js +100 -0
  243. package/src/config/source-packages/litert/gemma-4-e2b-it.json +2 -2
  244. package/src/config/target-plan.d.ts +108 -0
  245. package/src/config/target-plan.js +411 -0
  246. package/src/config/training-defaults.js +1 -1
  247. package/src/config/transforms/capability-transform-resolver.js +4 -105
  248. package/src/config/transforms/execution-graph/dtype.js +591 -0
  249. package/src/config/transforms/execution-graph/fusion.js +436 -0
  250. package/src/config/transforms/execution-graph/validation.js +414 -0
  251. package/src/config/transforms/execution-graph-transforms.js +13 -1419
  252. package/src/converter/artifact-identity.js +475 -0
  253. package/src/converter/conversion-plan.js +1 -1
  254. package/src/converter/core.js +94 -2096
  255. package/src/converter/forge-candidate-evaluation.js +271 -0
  256. package/src/converter/forge-qualification.js +163 -0
  257. package/src/converter/forge-stages.js +800 -0
  258. package/src/converter/manifest-builder.js +683 -0
  259. package/src/converter/quantization-info.js +4 -1
  260. package/src/converter/quantizer.js +76 -13
  261. package/src/converter/shard-packer.d.ts +1 -1
  262. package/src/converter/shard-packer.js +2 -2
  263. package/src/converter/tensor-transform.js +640 -0
  264. package/src/converter/tokenizer-contract.js +243 -0
  265. package/src/converter/tokenizer-manifest.js +243 -0
  266. package/src/debug/history.js +0 -8
  267. package/src/debug/index.js +0 -10
  268. package/src/debug/tensor.js +1 -1
  269. package/src/debug/trace.js +0 -7
  270. package/src/experimental/adapters/adapter-manager.js +2 -0
  271. package/src/experimental/adapters/adapter-manifest.d.ts +6 -0
  272. package/src/experimental/adapters/adapter-manifest.js +11 -0
  273. package/src/experimental/adapters/artifact-contract.d.ts +2 -2
  274. package/src/experimental/adapters/artifact-contract.js +5 -2
  275. package/src/experimental/adapters/lora-loader.d.ts +10 -1
  276. package/src/experimental/adapters/lora-loader.js +110 -48
  277. package/src/{inference/pipelines → experimental}/audio/gemma4.js +9 -31
  278. package/src/experimental/bdpa/basis-decomposed-paged.d.ts +50 -0
  279. package/src/experimental/bdpa/basis-decomposed-paged.js +276 -0
  280. package/src/experimental/bridge/trainer-artifact-bridge.js +3 -3
  281. package/src/experimental/browser/browser-converter.js +11 -11
  282. package/src/experimental/diffusion/index.d.ts +1 -1
  283. package/src/experimental/diffusion/index.js +1 -1
  284. package/src/{inference/pipelines → experimental}/diffusion/pipeline.d.ts +2 -2
  285. package/src/{inference/pipelines → experimental}/diffusion/pipeline.js +17 -17
  286. package/src/{inference/pipelines → experimental}/diffusion/text-encoder-gpu.js +21 -19
  287. package/src/experimental/diffusion/vae.js +596 -0
  288. package/src/experimental/distribution/shard-delivery/receipt.js +588 -0
  289. package/src/experimental/distribution/shard-delivery/retry.js +392 -0
  290. package/src/experimental/distribution/shard-delivery/transport.js +831 -0
  291. package/src/experimental/distribution/shard-delivery.js +4 -1709
  292. package/src/experimental/energy/index.d.ts +2 -2
  293. package/src/experimental/energy/index.js +2 -2
  294. package/src/{inference/pipelines → experimental}/energy/pipeline.js +13 -13
  295. package/src/{inference/pipelines → experimental}/energy/types.d.ts +2 -2
  296. package/src/experimental/logits/cpu-output.d.ts +27 -0
  297. package/src/{inference/pipelines/text/logits/utils.js → experimental/logits/cpu-output.js} +19 -27
  298. package/src/experimental/logits/cpu.d.ts +87 -0
  299. package/src/experimental/logits/cpu.js +95 -0
  300. package/src/experimental/orchestration/energy-row-head-pipeline.d.ts +103 -0
  301. package/src/{inference/pipelines/energy-head/row-head-pipeline.js → experimental/orchestration/energy-row-head-pipeline.js} +13 -13
  302. package/src/experimental/orchestration/index.d.ts +1 -1
  303. package/src/experimental/orchestration/index.js +1 -1
  304. package/src/experimental/training/artifacts.js +2 -2
  305. package/src/experimental/training/checkpoint.js +2 -2
  306. package/src/experimental/training/distillation/artifacts.js +1 -1
  307. package/src/experimental/training/distillation/dataset.js +2 -2
  308. package/src/experimental/training/distillation/eval.js +1 -1
  309. package/src/experimental/training/distillation/runtime.js +2 -2
  310. package/src/experimental/training/distillation/student-fixture/execution.js +166 -0
  311. package/src/experimental/training/distillation/student-fixture/model.js +353 -0
  312. package/src/experimental/training/distillation/student-fixture.js +2 -469
  313. package/src/experimental/training/lora/checkpoint.js +746 -0
  314. package/src/experimental/training/lora/execution.js +550 -0
  315. package/src/experimental/training/lora/plan.js +387 -0
  316. package/src/experimental/training/lora/recovery.js +418 -0
  317. package/src/experimental/training/lora-pipeline.js +7 -1949
  318. package/src/experimental/training/operator-artifacts.js +2 -2
  319. package/src/experimental/training/operator-command.js +4 -4
  320. package/src/experimental/training/runner/evaluation.js +62 -0
  321. package/src/experimental/training/runner/lifecycle.js +257 -0
  322. package/src/experimental/training/runner.js +5 -268
  323. package/src/experimental/training/suite/execution.js +879 -0
  324. package/src/experimental/training/suite/plan.js +855 -0
  325. package/src/experimental/training/suite.js +5 -1659
  326. package/src/experimental/training/workloads.d.ts +5 -5
  327. package/src/experimental/training/workloads.js +6 -6
  328. package/src/experimental/turboquant/codebook.js +470 -0
  329. package/src/formats/quantization-constants.d.ts +11 -0
  330. package/src/formats/quantization-constants.js +11 -0
  331. package/src/formats/rdrr/integrity.js +1 -1
  332. package/src/formats/rdrr/lowerings.js +0 -29
  333. package/src/formats/rdrr/merkle.js +1 -1
  334. package/src/formats/rdrr/tensor-config-validator.js +25 -5
  335. package/src/formats/rdrr/validation.js +3 -3
  336. package/src/gpu/command-recorder.d.ts +10 -1
  337. package/src/gpu/command-recorder.js +58 -14
  338. package/src/gpu/constant-buffer.js +29 -0
  339. package/src/gpu/device-state.js +44 -0
  340. package/src/gpu/device.js +11 -41
  341. package/src/gpu/kernel-runtime.js +2 -1
  342. package/src/gpu/kernels/activation-static-qdq.js +1 -1
  343. package/src/gpu/kernels/append_embedding.wgsl +14 -0
  344. package/src/gpu/kernels/attention/executors.js +960 -0
  345. package/src/gpu/kernels/attention/plan.js +472 -0
  346. package/src/gpu/kernels/attention.d.ts +4 -0
  347. package/src/gpu/kernels/attention.js +145 -1545
  348. package/src/gpu/kernels/attention_relative.wgsl +59 -0
  349. package/src/gpu/kernels/backward/adam.js +2 -1
  350. package/src/gpu/kernels/backward/attention_backward.js +1 -1
  351. package/src/gpu/kernels/backward/bias_add_backward.d.ts +1 -1
  352. package/src/gpu/kernels/backward/bias_add_backward.js +1 -1
  353. package/src/gpu/kernels/backward/causal_conv1d_silu_backward.js +2 -1
  354. package/src/gpu/kernels/backward/conv2d_backward.d.ts +1 -1
  355. package/src/gpu/kernels/backward/conv2d_backward.js +2 -1
  356. package/src/gpu/kernels/backward/cross_entropy_backward.d.ts +1 -1
  357. package/src/gpu/kernels/backward/cross_entropy_backward.js +1 -1
  358. package/src/gpu/kernels/backward/embed_backward.js +2 -1
  359. package/src/gpu/kernels/backward/executor.d.ts +34 -0
  360. package/src/gpu/kernels/backward/executor.js +158 -0
  361. package/src/gpu/kernels/backward/gated_delta_recurrent_backward.js +2 -1
  362. package/src/gpu/kernels/backward/gated_rmsnorm_backward.js +2 -1
  363. package/src/gpu/kernels/backward/gelu_backward.d.ts +1 -1
  364. package/src/gpu/kernels/backward/gelu_backward.js +1 -1
  365. package/src/gpu/kernels/backward/groupnorm_backward.d.ts +1 -1
  366. package/src/gpu/kernels/backward/groupnorm_backward.js +1 -1
  367. package/src/gpu/kernels/backward/layernorm_backward.d.ts +1 -1
  368. package/src/gpu/kernels/backward/layernorm_backward.js +2 -1
  369. package/src/gpu/kernels/backward/matmul.js +133 -0
  370. package/src/gpu/kernels/backward/matmul_backward.d.ts +0 -1
  371. package/src/gpu/kernels/backward/matmul_backward.js +1 -1
  372. package/src/gpu/kernels/backward/pixel_shuffle_backward.d.ts +1 -1
  373. package/src/gpu/kernels/backward/pixel_shuffle_backward.js +1 -1
  374. package/src/gpu/kernels/backward/rmsnorm_backward.d.ts +1 -1
  375. package/src/gpu/kernels/backward/rmsnorm_backward.js +2 -1
  376. package/src/gpu/kernels/backward/rope_backward.d.ts +1 -1
  377. package/src/gpu/kernels/backward/rope_backward.js +2 -1
  378. package/src/gpu/kernels/backward/scale_backward.d.ts +1 -1
  379. package/src/gpu/kernels/backward/scale_backward.js +2 -1
  380. package/src/gpu/kernels/backward/silu_backward.d.ts +1 -1
  381. package/src/gpu/kernels/backward/silu_backward.js +1 -1
  382. package/src/gpu/kernels/backward/softmax_backward.d.ts +1 -1
  383. package/src/gpu/kernels/backward/softmax_backward.js +1 -1
  384. package/src/gpu/kernels/backward/upsample2d_backward.d.ts +1 -1
  385. package/src/gpu/kernels/backward/upsample2d_backward.js +1 -1
  386. package/src/gpu/kernels/backward/utils.js +2 -392
  387. package/src/gpu/kernels/bind-group-validation.js +16 -0
  388. package/src/gpu/kernels/cast.js +2 -1
  389. package/src/gpu/kernels/check-finiteness.js +13 -49
  390. package/src/gpu/kernels/check-hot-vocab-stop.js +13 -39
  391. package/src/gpu/kernels/check-stop.js +14 -33
  392. package/src/gpu/kernels/check_finiteness.wgsl +33 -0
  393. package/src/gpu/kernels/check_hot_vocab_stop.wgsl +29 -0
  394. package/src/gpu/kernels/check_stop.wgsl +20 -0
  395. package/src/gpu/kernels/clamp.js +1 -1
  396. package/src/gpu/kernels/conv2d.js +1 -1
  397. package/src/gpu/kernels/cross_entropy_loss.js +1 -1
  398. package/src/gpu/kernels/depthwise_conv1d.js +1 -1
  399. package/src/gpu/kernels/depthwise_conv2d.js +1 -1
  400. package/src/gpu/kernels/dequant.js +7 -2
  401. package/src/gpu/kernels/diffusion-gemma-sampling.js +3 -5
  402. package/src/gpu/kernels/dispatch.js +12 -1
  403. package/src/gpu/kernels/embedding-pool.js +72 -0
  404. package/src/gpu/kernels/embedding_pool_f16.wgsl +38 -0
  405. package/src/gpu/kernels/embedding_pool_f32.wgsl +36 -0
  406. package/src/gpu/kernels/energy.js +2 -1
  407. package/src/gpu/kernels/forecast_output.wgsl +17 -0
  408. package/src/gpu/kernels/fused-gate-up-gelu.js +1 -1
  409. package/src/gpu/kernels/fused_ffn.js +10 -220
  410. package/src/gpu/kernels/fused_matmul_residual.js +2 -1
  411. package/src/gpu/kernels/fused_matmul_rmsnorm.js +2 -1
  412. package/src/gpu/kernels/fused_normed_ffn_q4k.wgsl +208 -0
  413. package/src/gpu/kernels/gated-short-conv.js +11 -69
  414. package/src/gpu/kernels/gated_delta_conv.wgsl +66 -0
  415. package/src/gpu/kernels/gated_delta_conv_f16.wgsl +68 -0
  416. package/src/gpu/kernels/gated_delta_fused_decode.wgsl +173 -0
  417. package/src/gpu/kernels/gated_delta_fused_decode_f16.wgsl +175 -0
  418. package/src/gpu/kernels/gated_delta_recurrent.wgsl +165 -0
  419. package/src/gpu/kernels/gated_delta_recurrent_f16.wgsl +167 -0
  420. package/src/gpu/kernels/gated_short_conv.wgsl +47 -0
  421. package/src/gpu/kernels/gather.d.ts +1 -1
  422. package/src/gpu/kernels/gather.js +30 -6
  423. package/src/gpu/kernels/gather_bf16.wgsl +69 -0
  424. package/src/gpu/kernels/gelu.d.ts +4 -0
  425. package/src/gpu/kernels/gelu.js +12 -2
  426. package/src/gpu/kernels/gelu.wgsl +16 -0
  427. package/src/gpu/kernels/gelu_f16.wgsl +16 -0
  428. package/src/gpu/kernels/gemma4-route-expert.js +1 -1
  429. package/src/gpu/kernels/grouped_pointwise_conv2d.js +1 -1
  430. package/src/gpu/kernels/groupnorm.js +1 -1
  431. package/src/gpu/kernels/index.d.ts +38 -5
  432. package/src/gpu/kernels/index.js +18 -4
  433. package/src/gpu/kernels/instance_stats.wgsl +26 -0
  434. package/src/gpu/kernels/kernel-base.js +1 -1
  435. package/src/gpu/kernels/kernel-cache-lifecycle.d.ts +9 -0
  436. package/src/gpu/kernels/kernel-cache-lifecycle.js +26 -0
  437. package/src/gpu/kernels/kernel-configs.d.ts +10 -61
  438. package/src/gpu/kernels/kernel-configs.js +26 -54
  439. package/src/gpu/kernels/kernel-execution.js +141 -0
  440. package/src/gpu/kernels/kv-cache-write.js +4 -4
  441. package/src/gpu/kernels/kv-quantize.js +4 -1
  442. package/src/gpu/kernels/l2-normalize.js +36 -0
  443. package/src/gpu/kernels/l2_normalize.wgsl +53 -0
  444. package/src/gpu/kernels/layernorm.d.ts +4 -4
  445. package/src/gpu/kernels/layernorm.js +44 -7
  446. package/src/gpu/kernels/linear-attention-core.js +29 -449
  447. package/src/gpu/kernels/linear_attention.js +1 -1
  448. package/src/gpu/kernels/lm-head-argmax.js +2 -2
  449. package/src/gpu/kernels/lm-head-select-logits.js +2 -2
  450. package/src/gpu/kernels/logit-finalize.js +103 -0
  451. package/src/gpu/kernels/logit-merge.js +13 -125
  452. package/src/gpu/kernels/logit-scatter.js +40 -0
  453. package/src/gpu/kernels/logit_finalize_f16.wgsl +43 -0
  454. package/src/gpu/kernels/logit_finalize_f32.wgsl +41 -0
  455. package/src/gpu/kernels/logit_merge_geometric.wgsl +23 -0
  456. package/src/gpu/kernels/logit_merge_max.wgsl +23 -0
  457. package/src/gpu/kernels/logit_merge_weighted.wgsl +23 -0
  458. package/src/gpu/kernels/logit_scatter_f16.wgsl +26 -0
  459. package/src/gpu/kernels/logit_scatter_f32.wgsl +24 -0
  460. package/src/gpu/kernels/matmul-dispatch.js +6 -1
  461. package/src/gpu/kernels/matmul-selection.js +3 -2
  462. package/src/gpu/kernels/matmul.js +4 -15
  463. package/src/gpu/kernels/matmul_bf16w_f32a.wgsl +93 -0
  464. package/src/gpu/kernels/matmul_gemv_subgroup_bf16w.wgsl +433 -0
  465. package/src/gpu/kernels/modulate.js +1 -1
  466. package/src/gpu/kernels/moe.js +3 -1
  467. package/src/gpu/kernels/moe_router_bias_add_f16_f16.wgsl +23 -0
  468. package/src/gpu/kernels/moe_router_bias_add_f16_f32.wgsl +23 -0
  469. package/src/gpu/kernels/moe_router_bias_add_f32_f16.wgsl +23 -0
  470. package/src/gpu/kernels/moe_router_bias_add_f32_f32.wgsl +21 -0
  471. package/src/gpu/kernels/patch_context.wgsl +29 -0
  472. package/src/gpu/kernels/pipeline-cache.js +3 -1
  473. package/src/gpu/kernels/pixel_shuffle.js +1 -1
  474. package/src/gpu/kernels/probe_shader_f16.wgsl +7 -0
  475. package/src/gpu/kernels/relu.js +1 -1
  476. package/src/gpu/kernels/rep-penalty.js +30 -5
  477. package/src/gpu/kernels/rep_penalty.wgsl +25 -30
  478. package/src/gpu/kernels/rep_penalty_f16.wgsl +24 -25
  479. package/src/gpu/kernels/repeat_channels.js +1 -1
  480. package/src/gpu/kernels/residual.js +2 -2
  481. package/src/gpu/kernels/rmsnorm-pair.js +1 -1
  482. package/src/gpu/kernels/rmsnorm-qk.js +1 -1
  483. package/src/gpu/kernels/rmsnorm-stats.js +14 -113
  484. package/src/gpu/kernels/rmsnorm.js +1 -1
  485. package/src/gpu/kernels/rmsnorm_serial.wgsl +19 -0
  486. package/src/gpu/kernels/rmsnorm_stats.wgsl +59 -0
  487. package/src/gpu/kernels/rmsnorm_stats_subgroups.wgsl +76 -0
  488. package/src/gpu/kernels/rope-precompute.js +160 -0
  489. package/src/gpu/kernels/rope-qk.js +1 -1
  490. package/src/gpu/kernels/rope.js +2 -2
  491. package/src/gpu/kernels/rope_precompute.wgsl +74 -0
  492. package/src/gpu/kernels/sample.d.ts +1 -0
  493. package/src/gpu/kernels/sample.js +36 -17
  494. package/src/gpu/kernels/sample.wgsl +112 -157
  495. package/src/gpu/kernels/sample_f16.wgsl +168 -162
  496. package/src/gpu/kernels/scale.js +1 -1
  497. package/src/gpu/kernels/shader-cache.js +8 -4
  498. package/src/gpu/kernels/shader-source-scope.js +68 -0
  499. package/src/gpu/kernels/silu.js +2 -1
  500. package/src/gpu/kernels/soft-embedding.js +3 -1
  501. package/src/gpu/kernels/softmax.js +4 -2
  502. package/src/gpu/kernels/split-qkv-rmsnorm-qk.js +1 -1
  503. package/src/gpu/kernels/split-qkv-rmsnorm-rope-qk.js +1 -1
  504. package/src/gpu/kernels/split_qg.js +1 -1
  505. package/src/gpu/kernels/split_qkv.d.ts +2 -0
  506. package/src/gpu/kernels/split_qkv.js +18 -3
  507. package/src/gpu/kernels/split_qkv.wgsl +5 -2
  508. package/src/gpu/kernels/split_qkv_f16.wgsl +5 -2
  509. package/src/gpu/kernels/submit_probe.wgsl +6 -0
  510. package/src/gpu/kernels/transpose.js +1 -1
  511. package/src/gpu/kernels/turboquant-codebook.js +4 -535
  512. package/src/gpu/kernels/uniform-utils.js +7 -2
  513. package/src/gpu/kernels/upsample2d.js +1 -1
  514. package/src/gpu/kernels/utils.js +9 -330
  515. package/src/gpu/kernels/vision-average-pool.d.ts +13 -0
  516. package/src/gpu/kernels/vision-average-pool.js +68 -0
  517. package/src/gpu/kernels/vision-patch-embed.d.ts +17 -0
  518. package/src/gpu/kernels/vision-patch-embed.js +117 -0
  519. package/src/gpu/kernels/vision-position-embedding.d.ts +13 -0
  520. package/src/gpu/kernels/vision-position-embedding.js +79 -0
  521. package/src/gpu/kernels/vision-rope-2d.d.ts +16 -0
  522. package/src/gpu/kernels/vision-rope-2d.js +73 -0
  523. package/src/gpu/kernels/vision-spatial-merge.d.ts +19 -0
  524. package/src/gpu/kernels/vision-spatial-merge.js +100 -0
  525. package/src/gpu/kernels/vision_average_pool.wgsl +42 -0
  526. package/src/gpu/kernels/vision_patch_embed.wgsl +59 -0
  527. package/src/gpu/kernels/vision_patch_embed_f16w.wgsl +61 -0
  528. package/src/gpu/kernels/vision_position_embedding.wgsl +33 -0
  529. package/src/gpu/kernels/vision_position_embedding_f16.wgsl +35 -0
  530. package/src/gpu/kernels/vision_rope_2d.wgsl +60 -0
  531. package/src/gpu/kernels/vision_spatial_merge.wgsl +48 -0
  532. package/src/gpu/readback-buffer.js +20 -0
  533. package/src/gpu/submit-probe.js +2 -26
  534. package/src/gpu/weight-buffer.d.ts +1 -0
  535. package/src/gpu/weight-buffer.js +7 -0
  536. package/src/index.d.ts +12 -0
  537. package/src/index.js +2 -0
  538. package/src/inference/browser-harness/benchmark-execution.js +872 -0
  539. package/src/inference/browser-harness/benchmark-rerank.js +284 -0
  540. package/src/inference/browser-harness/decode-diagnostics.js +241 -0
  541. package/src/inference/browser-harness/diffusion-performance.js +102 -0
  542. package/src/inference/browser-harness/inference-execution.js +543 -0
  543. package/src/inference/{browser-harness-model-helpers.js → browser-harness/model-initialization.js} +14 -145
  544. package/src/inference/browser-harness/model-resolution.js +137 -0
  545. package/src/inference/browser-harness/report.js +338 -0
  546. package/src/inference/browser-harness/request.js +263 -0
  547. package/src/inference/browser-harness/runtime-config.d.ts +25 -0
  548. package/src/inference/browser-harness/runtime-config.js +255 -0
  549. package/src/inference/browser-harness/runtime-isolation.d.ts +13 -0
  550. package/src/inference/browser-harness/runtime-isolation.js +45 -0
  551. package/src/inference/browser-harness/runtime-report.d.ts +26 -0
  552. package/src/inference/browser-harness/runtime-report.js +117 -0
  553. package/src/inference/browser-harness/suite-summary.js +39 -0
  554. package/src/inference/browser-harness/text-evidence.js +694 -0
  555. package/src/inference/browser-harness/text-execution.js +757 -0
  556. package/src/inference/browser-harness/text-input.js +725 -0
  557. package/src/inference/{browser-harness-suite-helpers.js → browser-harness/timing-diagnostics.js} +1 -379
  558. package/src/inference/browser-harness-contract-helpers.js +1 -1
  559. package/src/inference/browser-harness-diffusion-energy-suites.js +8 -3
  560. package/src/inference/browser-harness-runtime-helpers.d.ts +3 -56
  561. package/src/inference/browser-harness-runtime-helpers.js +3 -423
  562. package/src/inference/browser-harness-text-helpers.js +31 -2199
  563. package/src/inference/browser-harness.d.ts +15 -2
  564. package/src/inference/browser-harness.js +38 -1952
  565. package/src/inference/kv-cache/base.js +67 -381
  566. package/src/inference/kv-cache/basis-decomposed-paged.d.ts +2 -50
  567. package/src/inference/kv-cache/basis-decomposed-paged.js +1 -276
  568. package/src/inference/kv-cache/quantized.d.ts +2 -2
  569. package/src/inference/kv-cache/quantized.js +4 -8
  570. package/src/inference/kv-cache/update.js +309 -0
  571. package/src/inference/model-checkpoint-evidence.d.ts +75 -0
  572. package/src/inference/model-checkpoint-evidence.js +264 -0
  573. package/src/inference/moe-router.js +36 -216
  574. package/src/inference/multi-model-network.js +5 -341
  575. package/src/inference/pipelines/audio/index.js +1 -20
  576. package/src/inference/pipelines/audio/mel.js +0 -38
  577. package/src/inference/pipelines/context.js +6 -2
  578. package/src/inference/pipelines/diffusion/profile-timing.js +10 -0
  579. package/src/inference/pipelines/diffusion/runtime-resources.js +54 -0
  580. package/src/inference/pipelines/diffusion/sd3/execution.js +805 -0
  581. package/src/inference/pipelines/diffusion/sd3/plan.js +125 -0
  582. package/src/inference/pipelines/diffusion/sd3-transformer.js +44 -895
  583. package/src/inference/pipelines/diffusion/{vae.js → vae/execution.js} +46 -618
  584. package/src/inference/pipelines/diffusion/{helpers.js → weight-contract.js} +1 -68
  585. package/src/inference/pipelines/energy-head/row-head-pipeline.d.ts +1 -103
  586. package/src/inference/pipelines/factory.js +14 -3
  587. package/src/inference/pipelines/shader-scoped-pipeline.js +29 -0
  588. package/src/inference/pipelines/structured/json-grammar-mask.d.ts +2 -0
  589. package/src/inference/pipelines/structured/json-grammar-mask.js +115 -124
  590. package/src/inference/pipelines/text/abort-contract.js +22 -0
  591. package/src/inference/pipelines/text/attention/attn-config.js +1 -16
  592. package/src/inference/pipelines/text/attention/gate-projection.js +30 -0
  593. package/src/inference/pipelines/text/attention/heterogeneous-contract.js +8 -0
  594. package/src/inference/pipelines/text/attention/interpreter/immediate.js +211 -0
  595. package/src/inference/pipelines/text/attention/interpreter/recorded.js +451 -0
  596. package/src/inference/pipelines/text/attention/interpreter.js +89 -439
  597. package/src/inference/pipelines/text/attention/plan.d.ts +1 -0
  598. package/src/inference/pipelines/text/attention/plan.js +17 -0
  599. package/src/inference/pipelines/text/attention/projection-executor.js +331 -0
  600. package/src/inference/pipelines/text/attention/projection-plan.js +259 -0
  601. package/src/inference/pipelines/text/attention/projections.js +20 -537
  602. package/src/inference/pipelines/text/attention/query-transform.js +11 -0
  603. package/src/inference/pipelines/text/attention/record.js +0 -6
  604. package/src/inference/pipelines/text/attention/recorded-health.js +21 -0
  605. package/src/inference/pipelines/text/attention/rope-observation.js +40 -0
  606. package/src/inference/pipelines/text/attention/run.js +0 -6
  607. package/src/inference/pipelines/text/attention/types.js +3 -31
  608. package/src/inference/pipelines/text/chat-format.d.ts +3 -0
  609. package/src/inference/pipelines/text/chat-format.js +42 -0
  610. package/src/inference/pipelines/text/config/normalization.js +729 -0
  611. package/src/inference/pipelines/text/config/validation.js +9 -0
  612. package/src/inference/pipelines/text/config.d.ts +12 -1
  613. package/src/inference/pipelines/text/config.js +14 -1228
  614. package/src/inference/pipelines/text/debug-utils/health-metrics.js +57 -0
  615. package/src/inference/pipelines/text/debug-utils/index.js +3 -8
  616. package/src/inference/pipelines/text/debug-utils/profiles.js +8 -0
  617. package/src/inference/pipelines/text/debug-utils/readback-decoding.js +24 -0
  618. package/src/inference/pipelines/text/debug-utils/tensor.js +1 -1
  619. package/src/inference/pipelines/text/dtype-contract.js +1 -68
  620. package/src/inference/pipelines/text/embed.js +178 -241
  621. package/src/inference/pipelines/text/embedding-contract.d.ts +7 -0
  622. package/src/inference/pipelines/text/embedding-contract.js +21 -0
  623. package/src/inference/pipelines/text/embedding-extraction.js +225 -0
  624. package/src/inference/pipelines/text/embedding-normalization.js +39 -0
  625. package/src/inference/pipelines/text/execution-runtime-builders.js +0 -32
  626. package/src/inference/pipelines/text/execution-v1/plan.js +69 -0
  627. package/src/inference/pipelines/text/execution-v1/validation.js +233 -0
  628. package/src/inference/pipelines/text/execution-v1.js +7 -283
  629. package/src/inference/pipelines/text/execution.js +517 -0
  630. package/src/inference/pipelines/text/ffn/dense-executor.js +723 -0
  631. package/src/inference/pipelines/text/ffn/dense-plan.js +327 -0
  632. package/src/inference/pipelines/text/ffn/dense.js +6 -970
  633. package/src/inference/pipelines/text/ffn/sandwich.js +10 -9
  634. package/src/inference/pipelines/text/ffn/standard.js +2 -1
  635. package/src/inference/pipelines/text/generator/attention-lifecycle.js +24 -0
  636. package/src/inference/pipelines/text/generator/decode-runtime.js +985 -0
  637. package/src/inference/pipelines/text/generator/decode.js +964 -0
  638. package/src/inference/pipelines/text/generator/diffusion.js +607 -0
  639. package/src/inference/pipelines/text/generator/logits-config.js +63 -0
  640. package/src/inference/pipelines/text/generator/prefill-observation.js +29 -0
  641. package/src/inference/pipelines/text/generator/prefill-policy.js +56 -0
  642. package/src/inference/pipelines/text/generator/prefill-runtime.js +896 -0
  643. package/src/inference/pipelines/text/{generator-prefill-helpers.js → generator/prefix-embedding.js} +16 -121
  644. package/src/inference/pipelines/text/generator/prompt-input.js +47 -0
  645. package/src/inference/pipelines/text/generator/recovery.js +310 -0
  646. package/src/inference/pipelines/text/{generator-helpers.js → generator/session-context.js} +42 -110
  647. package/src/inference/pipelines/text/generator/text.js +448 -0
  648. package/src/inference/pipelines/text/generator/training.js +753 -0
  649. package/src/inference/pipelines/text/generator-decode-policy.js +1 -1
  650. package/src/inference/pipelines/text/generator-logits-observation.js +48 -0
  651. package/src/inference/pipelines/text/generator-runtime.js +23 -154
  652. package/src/inference/pipelines/text/generator-steps.js +45 -980
  653. package/src/inference/pipelines/text/generator.js +179 -3552
  654. package/src/inference/pipelines/text/image-transcription.js +304 -0
  655. package/src/inference/pipelines/text/init-qkv-fusion.js +18 -9
  656. package/src/inference/pipelines/text/init-rope.js +37 -189
  657. package/src/inference/pipelines/text/init.d.ts +8 -3
  658. package/src/inference/pipelines/text/init.js +6 -216
  659. package/src/inference/pipelines/text/layer-execution-contract.js +97 -0
  660. package/src/inference/pipelines/text/layer-input-execution.js +435 -0
  661. package/src/inference/pipelines/text/layer-plan-gpu.js +13 -6
  662. package/src/inference/pipelines/text/layer-plan.d.ts +21 -5
  663. package/src/inference/pipelines/text/layer-plan.js +45 -3
  664. package/src/inference/pipelines/text/layer.js +52 -522
  665. package/src/inference/pipelines/text/lifecycle.js +839 -0
  666. package/src/inference/pipelines/text/linear-attention/plan.js +554 -0
  667. package/src/inference/pipelines/text/linear-attention-ab-fusion.js +2 -2
  668. package/src/inference/pipelines/text/linear-attention.d.ts +2 -2
  669. package/src/inference/pipelines/text/linear-attention.js +28 -534
  670. package/src/inference/pipelines/text/logits/cpu-output.d.ts +1 -0
  671. package/src/inference/pipelines/text/logits/cpu-output.js +5 -0
  672. package/src/inference/pipelines/text/logits/cpu.d.ts +1 -87
  673. package/src/inference/pipelines/text/logits/cpu.js +8 -95
  674. package/src/inference/pipelines/text/logits/gpu-executor.js +368 -0
  675. package/src/inference/pipelines/text/logits/gpu.d.ts +27 -0
  676. package/src/inference/pipelines/text/logits/gpu.js +116 -579
  677. package/src/inference/pipelines/text/logits/index.d.ts +2 -1
  678. package/src/inference/pipelines/text/logits/index.js +62 -102
  679. package/src/inference/pipelines/text/logits/output-transform.js +54 -0
  680. package/src/inference/pipelines/text/logits/plan.js +184 -0
  681. package/src/inference/pipelines/text/logits/readback.d.ts +6 -0
  682. package/src/inference/pipelines/text/logits/readback.js +9 -0
  683. package/src/inference/pipelines/text/logits/scale-policy.js +20 -0
  684. package/src/inference/pipelines/text/logits/types.d.ts +1 -0
  685. package/src/inference/pipelines/text/lora-apply.js +12 -4
  686. package/src/inference/pipelines/text/lora-types.d.ts +12 -0
  687. package/src/inference/pipelines/text/modality-token-contract.js +115 -0
  688. package/src/inference/pipelines/text/model-load.js +0 -20
  689. package/src/inference/pipelines/text/moe/expert-loading.js +9 -0
  690. package/src/inference/pipelines/text/moe/gpu-executor.js +513 -0
  691. package/src/inference/pipelines/text/moe/plan.js +47 -0
  692. package/src/inference/pipelines/text/moe-cpu.js +9 -135
  693. package/src/inference/pipelines/text/moe-gpu.js +21 -545
  694. package/src/inference/pipelines/text/normalization-contract.js +17 -0
  695. package/src/inference/pipelines/text/per-layer/materialize.js +736 -0
  696. package/src/inference/pipelines/text/per-layer/plan.js +362 -0
  697. package/src/inference/pipelines/text/per-layer-inputs.js +4 -1037
  698. package/src/inference/pipelines/text/pipeline-load-timing.js +77 -0
  699. package/src/inference/pipelines/text/probes.js +20 -0
  700. package/src/inference/pipelines/text/sampling-config.js +22 -113
  701. package/src/inference/pipelines/text/sampling.d.ts +9 -1
  702. package/src/inference/pipelines/text/sampling.js +18 -375
  703. package/src/inference/pipelines/text/state.d.ts +8 -0
  704. package/src/inference/pipelines/text/state.js +1 -0
  705. package/src/inference/pipelines/text/tsir-fixture-writer.js +88 -16
  706. package/src/inference/pipelines/text/types.d.ts +7 -3
  707. package/src/inference/pipelines/text/weight-loading-config.js +194 -0
  708. package/src/inference/pipelines/text.d.ts +2 -2
  709. package/src/inference/pipelines/text.js +46 -1633
  710. package/src/inference/pipelines/video/frame-sampler.js +0 -13
  711. package/src/inference/pipelines/video/index.js +0 -21
  712. package/src/inference/pipelines/vision/attention.js +59 -0
  713. package/src/inference/pipelines/vision/encoder.js +254 -369
  714. package/src/inference/pipelines/vision/gemma4.js +204 -318
  715. package/src/inference/pipelines/vision/glmocr-preprocess.js +273 -0
  716. package/src/inference/pipelines/vision/glmocr-rope.js +106 -0
  717. package/src/inference/pipelines/vision/glmocr.js +557 -0
  718. package/src/inference/pipelines/vision/image-preprocess.js +0 -27
  719. package/src/inference/pipelines/vision/index.js +8 -27
  720. package/src/inference/pipelines/vision/ops.js +11 -33
  721. package/src/inference/pipelines/vision/patch-embed.js +51 -145
  722. package/src/inference/pipelines/vision/spatial-merge.js +78 -0
  723. package/src/inference/pipelines/vision/weight-loading.js +79 -0
  724. package/src/inference/refactor-receipt.js +2 -2
  725. package/src/inference/rerank.js +182 -0
  726. package/src/inference/token-sampling.js +319 -0
  727. package/src/inference/tokenizer.js +1 -1
  728. package/src/inference/tokenizers/behavior-flags.js +6 -3
  729. package/src/inference/tokenizers/bundled/decoders.js +133 -0
  730. package/src/inference/tokenizers/bundled/registry.js +216 -0
  731. package/src/inference/tokenizers/bundled.js +23 -353
  732. package/src/loader/doppler-loader.d.ts +4 -0
  733. package/src/loader/doppler-loader.js +119 -930
  734. package/src/loader/embedding-limit-preflight.js +11 -4
  735. package/src/loader/embedding-loader.js +1 -3
  736. package/src/loader/gpu-tensor-materialization.js +20 -0
  737. package/src/loader/layer-loader.js +15 -119
  738. package/src/loader/layer-tensor-aliases.js +99 -0
  739. package/src/loader/layer-weight-shape.js +29 -0
  740. package/src/loader/load-timing.js +64 -0
  741. package/src/loader/loader-types.d.ts +3 -0
  742. package/src/loader/model-executor.js +819 -0
  743. package/src/loader/model-load-validation.js +15 -0
  744. package/src/loader/quantization-constants.d.ts +11 -29
  745. package/src/loader/quantization-constants.js +1 -2
  746. package/src/loader/shard-resolver.js +0 -14
  747. package/src/loader/tensor-load-error.js +14 -0
  748. package/src/loader/tensor-shard-indices.js +8 -0
  749. package/src/loader/tensors/bf16-loader.js +125 -0
  750. package/src/loader/tensors/functional-descriptor-loader.js +3 -375
  751. package/src/loader/tensors/load-executor.js +577 -0
  752. package/src/loader/tensors/source-transform/executor.js +123 -0
  753. package/src/loader/tensors/source-transform/plan.js +107 -0
  754. package/src/loader/tensors/source-transform.js +15 -264
  755. package/src/loader/tensors/tensor-loader.d.ts +4 -4
  756. package/src/loader/tensors/tensor-loader.js +7 -653
  757. package/src/memory/buffer-pool.js +7 -29
  758. package/src/rules/capability-transform-resolver.js +80 -0
  759. package/src/rules/execution-contract.d.ts +73 -0
  760. package/src/rules/execution-contract.js +429 -0
  761. package/src/rules/execution-rules-contract-check.js +1 -1
  762. package/src/rules/generated/rule-bundle.json +4305 -0
  763. package/src/rules/inference/capability-transforms.rules.json +3 -3
  764. package/src/rules/layer-pattern-contract-check.js +1 -1
  765. package/src/rules/rule-registry.js +70 -57
  766. package/src/storage/artifact-storage-context.js +2 -2
  767. package/src/storage/backend-selection.js +43 -0
  768. package/src/storage/backends/opfs-store.d.ts +41 -0
  769. package/src/storage/distribution-transport.js +5 -0
  770. package/src/storage/download/integrity.d.ts +33 -0
  771. package/src/storage/download/integrity.js +130 -0
  772. package/src/storage/download/resume-inspection.d.ts +22 -0
  773. package/src/storage/download/resume-inspection.js +134 -0
  774. package/src/storage/download/retry.js +57 -0
  775. package/src/storage/download/state.js +131 -0
  776. package/src/storage/download/transport.js +99 -0
  777. package/src/storage/downloader.js +74 -453
  778. package/src/storage/model-cache.d.ts +1 -0
  779. package/src/storage/model-cache.js +51 -11
  780. package/src/storage/shard-manager.d.ts +5 -0
  781. package/src/storage/shard-manager.js +50 -369
  782. package/src/storage/shards/index.js +60 -0
  783. package/src/storage/shards/integrity.js +225 -0
  784. package/src/storage/shards/lifecycle.js +22 -0
  785. package/src/storage/source-artifact-store.js +14 -4
  786. package/src/tooling/boundary-evidence.d.ts +4 -4
  787. package/src/tooling/boundary-evidence.js +20 -20
  788. package/src/tooling/browser-command-runner.js +13 -6
  789. package/src/tooling/capsule-v2.d.ts +11 -0
  790. package/src/tooling/capsule-v2.js +58 -0
  791. package/src/tooling/capsule.js +20 -0
  792. package/src/tooling/command-api-constants.js +1 -1
  793. package/src/tooling/command-api-family-normalizers.js +163 -5
  794. package/src/tooling/command-api.d.ts +42 -3
  795. package/src/tooling/command-api.js +7 -2
  796. package/src/tooling/command-envelope.js +1 -1
  797. package/src/tooling/{command-api-helpers.js → command-request-normalization.js} +1 -1
  798. package/src/tooling/command-runner.html +49 -1
  799. package/src/tooling/command-validation.js +1 -24
  800. package/src/tooling/conversion-run-timing.js +24 -0
  801. package/src/tooling/diagnose-runner.js +11 -9
  802. package/src/tooling/distribution-shard-transport.js +11 -0
  803. package/src/tooling/execution-cost-ledger.d.ts +76 -2
  804. package/src/tooling/execution-cost-ledger.js +197 -15
  805. package/src/tooling/hf-registry/catalog-io.js +63 -0
  806. package/src/tooling/litert/package.js +863 -0
  807. package/src/tooling/litert-package-runtime.js +3 -849
  808. package/src/tooling/model-capsule-forge.js +478 -0
  809. package/src/tooling/node-browser/execution.d.ts +40 -0
  810. package/src/tooling/node-browser/execution.js +308 -0
  811. package/src/tooling/node-browser/static-server.js +189 -0
  812. package/src/tooling/node-browser/transport.d.ts +80 -0
  813. package/src/tooling/node-browser/transport.js +622 -0
  814. package/src/tooling/node-browser-command-runner.d.ts +18 -78
  815. package/src/tooling/node-browser-command-runner.js +10 -1112
  816. package/src/tooling/node-capsule-artifact-store.js +44 -0
  817. package/src/tooling/node-command-execution.js +237 -0
  818. package/src/tooling/node-command-runner.js +26 -205
  819. package/src/tooling/node-converter/input.js +521 -0
  820. package/src/tooling/node-converter/output.js +244 -0
  821. package/src/tooling/node-converter-chunk-batches.js +21 -0
  822. package/src/tooling/node-converter.js +7 -720
  823. package/src/tooling/node-source-runtime.js +16 -276
  824. package/src/tooling/node-webgpu-provider.v1.json +33 -0
  825. package/src/tooling/node-webgpu.js +178 -453
  826. package/src/tooling/opfs-cache.d.ts +5 -0
  827. package/src/tooling/opfs-cache.js +4 -0
  828. package/src/tooling/production-release.d.ts +19 -0
  829. package/src/tooling/production-release.js +647 -0
  830. package/src/tooling/program-bundle/embedding-reference.js +19 -0
  831. package/src/tooling/program-bundle/materialize.js +324 -0
  832. package/src/tooling/program-bundle/rerank-reference.js +22 -0
  833. package/src/tooling/program-bundle/sequence-reference.js +42 -0
  834. package/src/tooling/program-bundle/validation.js +31 -0
  835. package/src/tooling/program-bundle/wgsl-closure.js +254 -0
  836. package/src/tooling/program-bundle-parity.d.ts +11 -4
  837. package/src/tooling/program-bundle-parity.js +262 -109
  838. package/src/tooling/program-bundle.d.ts +7 -0
  839. package/src/tooling/program-bundle.js +186 -591
  840. package/src/tooling/provider-v1-contract.d.ts +61 -0
  841. package/src/tooling/provider-v1-contract.js +192 -0
  842. package/src/tooling/registered-variant-calibration-job.d.ts +98 -0
  843. package/src/tooling/registered-variant-calibration-job.js +210 -0
  844. package/src/tooling/registered-variant-calibration.d.ts +167 -7
  845. package/src/tooling/registered-variant-calibration.js +57 -7
  846. package/src/tooling/runtime-optimization/candidates.js +664 -0
  847. package/src/tooling/runtime-optimization-campaign.js +166 -0
  848. package/src/tooling/runtime-optimization-index.js +16 -1
  849. package/src/tooling/runtime-optimization.d.ts +44 -0
  850. package/src/tooling/runtime-optimization.js +13 -656
  851. package/src/tooling/source-intake.d.ts +1 -1
  852. package/src/tooling/source-intake.js +34 -17
  853. package/src/tooling/source-package-profiles.js +1 -1
  854. package/src/tooling/source-runtime/bundle-materialize.js +298 -0
  855. package/src/tooling/source-runtime/bundle-plan.js +121 -0
  856. package/src/tooling/source-runtime/node-loader.js +258 -0
  857. package/src/tooling/source-runtime-bundle.js +26 -411
  858. package/src/tooling/source-runtime-converter-config.js +1 -1
  859. package/src/tooling-experimental-exports.js +0 -5
  860. package/src/tooling-exports/evidence.d.ts +14 -3
  861. package/src/tooling-exports/evidence.js +14 -3
  862. package/src/tooling-exports/storage.d.ts +7 -0
  863. package/src/tooling-exports/storage.js +5 -0
  864. package/src/tooling-exports.d.ts +3 -0
  865. package/src/tooling-exports.js +2 -0
  866. package/src/tooling-exports.shared.d.ts +17 -3
  867. package/src/tooling-exports.shared.js +9 -3
  868. package/src/training.d.ts +6 -6
  869. package/src/training.js +4 -4
  870. package/src/version.js +1 -1
  871. package/tests/kernels/browser/kernel-suite.js +512 -0
  872. package/tests/kernels/browser/test-page.js +170 -14
  873. package/tests/kernels/harness/tolerance.js +1 -0
  874. package/tests/kernels/reference/index.js +13 -1
  875. package/tests/kernels/reference/vision.js +160 -0
  876. package/src/converter/quantizer.d.ts +0 -121
  877. package/src/gpu/kernels/backward/utils.d.ts +0 -90
  878. package/src/gpu/kernels/uniform-utils.d.ts +0 -66
  879. package/src/gpu/kernels/utils.d.ts +0 -147
  880. package/src/inference/pipelines/text/debug-utils/utils.js +0 -118
  881. package/src/inference/pipelines/text/logits/utils.d.ts +0 -58
  882. package/src/inference/pipelines/text/moe-cpu-gptoss.js +0 -115
  883. package/src/inference/pipelines/text/moe-helpers.js +0 -21
  884. package/src/rules/converter/execution.rules.json +0 -20
  885. package/src/rules/converter/tensor-roles.rules.json +0 -13
  886. package/src/rules/converter/tokenizer.rules.json +0 -12
  887. package/src/rules/inference/attention.rules.json +0 -69
  888. package/src/rules/inference/config.rules.json +0 -82
  889. package/src/rules/inference/dtype.rules.json +0 -113
  890. package/src/rules/inference/execution.rules.json +0 -195
  891. package/src/rules/inference/ffn.rules.json +0 -123
  892. package/src/rules/inference/layer-pattern.rules.json +0 -16
  893. package/src/rules/inference/layer.rules.json +0 -7
  894. package/src/rules/inference/moe.rules.json +0 -145
  895. package/src/rules/kernels/attention.rules.json +0 -68
  896. package/src/rules/kernels/conv2d.rules.json +0 -6
  897. package/src/rules/kernels/depthwise-conv2d.rules.json +0 -6
  898. package/src/rules/kernels/dequant.rules.json +0 -58
  899. package/src/rules/kernels/energy.rules.json +0 -22
  900. package/src/rules/kernels/fused-ffn.rules.json +0 -15
  901. package/src/rules/kernels/fused-matmul-residual.rules.json +0 -6
  902. package/src/rules/kernels/fused-matmul-rmsnorm.rules.json +0 -8
  903. package/src/rules/kernels/gather.rules.json +0 -93
  904. package/src/rules/kernels/gelu.rules.json +0 -11
  905. package/src/rules/kernels/grouped-pointwise-conv2d.rules.json +0 -6
  906. package/src/rules/kernels/groupnorm.rules.json +0 -10
  907. package/src/rules/kernels/kv_quantize.rules.json +0 -9
  908. package/src/rules/kernels/layernorm.rules.json +0 -6
  909. package/src/rules/kernels/linear-attention.rules.json +0 -6
  910. package/src/rules/kernels/lm-head-argmax.rules.json +0 -10
  911. package/src/rules/kernels/matmul.rules.json +0 -95
  912. package/src/rules/kernels/modulate.rules.json +0 -6
  913. package/src/rules/kernels/moe.rules.gptoss.json +0 -105
  914. package/src/rules/kernels/moe.rules.json +0 -14
  915. package/src/rules/kernels/moe.rules.mixtral.json +0 -75
  916. package/src/rules/kernels/pixel_shuffle.rules.json +0 -6
  917. package/src/rules/kernels/relu.rules.json +0 -6
  918. package/src/rules/kernels/rep-penalty.rules.json +0 -6
  919. package/src/rules/kernels/repeat-channels.rules.json +0 -6
  920. package/src/rules/kernels/residual.rules.json +0 -12
  921. package/src/rules/kernels/rmsnorm-qk.rules.json +0 -6
  922. package/src/rules/kernels/rmsnorm.rules.json +0 -46
  923. package/src/rules/kernels/rope-qk.rules.json +0 -6
  924. package/src/rules/kernels/rope.rules.json +0 -6
  925. package/src/rules/kernels/sample.rules.json +0 -6
  926. package/src/rules/kernels/scale.rules.json +0 -8
  927. package/src/rules/kernels/silu.rules.json +0 -22
  928. package/src/rules/kernels/softmax.rules.json +0 -25
  929. package/src/rules/kernels/split-qg.rules.json +0 -6
  930. package/src/rules/kernels/split-qkv.rules.json +0 -6
  931. package/src/rules/kernels/upsample2d.rules.json +0 -6
  932. package/src/rules/loader/tensor-loader.rules.json +0 -42
  933. package/src/rules/loader/weights.rules.json +0 -42
  934. package/src/rules/tooling/command-runtime.rules.json +0 -65
  935. package/src/tooling/hf-registry-utils.js +0 -395
  936. /package/src/converter/{tokenizer-utils.js → tokenizer-special-tokens.js} +0 -0
  937. /package/src/{inference/pipelines/text/bdpa-steamroller.js → experimental/bdpa/steamroller.js} +0 -0
  938. /package/src/{inference/pipelines → experimental}/diffusion/scheduler.js +0 -0
  939. /package/src/{inference/pipelines → experimental}/energy/pipeline.d.ts +0 -0
  940. /package/src/{inference/pipelines → experimental}/energy/quintel.d.ts +0 -0
  941. /package/src/{inference/pipelines → experimental}/energy/quintel.js +0 -0
  942. /package/src/{utils → formats}/array-buffer.js +0 -0
  943. /package/src/{utils → formats}/canonical-hash.js +0 -0
  944. /package/src/{utils → formats}/clone-json.js +0 -0
  945. /package/src/{utils → formats}/encode-utf8.js +0 -0
  946. /package/src/{utils → formats}/load-json.js +0 -0
  947. /package/src/{utils → formats}/plain-object.js +0 -0
  948. /package/src/{utils → formats}/sha256.js +0 -0
  949. /package/src/{utils → formats}/stable-sort-object.js +0 -0
  950. /package/src/{gpu/kernels → rules}/rule-matcher.js +0 -0
  951. /package/src/{utils → storage}/hf-resolve-url.js +0 -0
  952. /package/src/{utils → storage}/runtime-env.js +0 -0
  953. /package/src/tooling/{command-runner-shared.js → command-runtime-execution.js} +0 -0
@@ -15,7 +15,7 @@ import { trainStep } from './trainer.js';
15
15
  import { crossEntropyLoss } from './loss.js';
16
16
  import { clipGradients } from './clip.js';
17
17
  import { exportLoRAAdapter } from './export.js';
18
- import { sha256Hex } from '../../utils/sha256.js';
18
+ import { sha256Hex } from '../../formats/sha256.js';
19
19
  import { computeSampleStats } from '../../debug/stats.js';
20
20
  import { parseJsonl } from './datasets/jsonl.js';
21
21
  import {
@@ -32,76 +32,10 @@ import { initializeInference } from '../../inference/test-harness.js';
32
32
  import { createPipeline } from '../../inference/pipelines/text.js';
33
33
  import { parseManifest } from '../../formats/rdrr/index.js';
34
34
  import { openModelStore, loadManifestFromStore } from '../../storage/shard-manager.js';
35
-
36
- const LEGACY_BROWSER_TESTS = Object.freeze([
37
- 'loss-forward',
38
- 'softmax-backward',
39
- 'cross-entropy-backward',
40
- 'rmsnorm-backward',
41
- 'layernorm-backward',
42
- 'conv2d-backward',
43
- 'matmul-backward',
44
- 'embed-backward',
45
- 'ebm-state-optimize',
46
- 'ebm-recorded-bench',
47
- 'parity-fixture',
48
- 'training-leak-perf',
49
- 'autograd-branching',
50
- ]);
51
- const TRAINING_COMMAND_SCHEMA_VERSION = 1;
52
- const DISTILL_ADAPTER_TOP_K = 64;
53
- const DISTILL_LOGIT_FALLBACK = -80;
54
- const DISTILL_STUDENT_GRAPH_PROJECTION = 'projection_head';
55
- const DISTILL_STUDENT_GRAPH_FULL = 'transformer_full';
56
-
57
- function buildSuiteSummary(suiteName, results, startTimeMs) {
58
- let passed = 0;
59
- let failed = 0;
60
- let skipped = 0;
61
- for (const result of results) {
62
- if (result.skipped) {
63
- skipped++;
64
- } else if (result.passed) {
65
- passed++;
66
- } else {
67
- failed++;
68
- }
69
- }
70
- return {
71
- suite: suiteName,
72
- passed,
73
- failed,
74
- skipped,
75
- duration: Math.max(0, performance.now() - startTimeMs),
76
- results,
77
- };
78
- }
79
-
80
- function normalizeTrainingTestNames(names) {
81
- if (!Array.isArray(names)) return null;
82
- const normalized = names
83
- .map((name) => String(name || '').trim())
84
- .filter(Boolean);
85
- return normalized.length > 0 ? normalized : null;
86
- }
87
-
88
- function assertTrainingSchemaVersion(value) {
89
- if (value === undefined || value === null) {
90
- return TRAINING_COMMAND_SCHEMA_VERSION;
91
- }
92
- const parsed = Number(value);
93
- if (!Number.isInteger(parsed) || parsed !== TRAINING_COMMAND_SCHEMA_VERSION) {
94
- throw new Error(`trainingSchemaVersion must be ${TRAINING_COMMAND_SCHEMA_VERSION}.`);
95
- }
96
- return parsed;
97
- }
98
-
99
- function makeTensorFromFloat32(values, shape, label) {
100
- const data = values instanceof Float32Array ? values : new Float32Array(values);
101
- const buffer = acquireBuffer(data.byteLength, undefined, label || 'train_tensor');
102
- uploadData(buffer, data);
103
- return createTensor(buffer, 'f32', shape, label || 'train_tensor');
104
- }
35
+ import { DISTILL_ADAPTER_TOP_K, UL_STAGE_SET, buildDistillTrainingOverrides, clampDistillTopK, createDistillRuntimeContext, createToyModelFixture, loadDistillDatasetFromJsonl, normalizeTrainingConfigOverride, normalizeTrainingStage } from './suite/plan.js';
36
+ import { assertTrainingSchemaVersion, buildSuiteSummary, buildUlTrainingOverrides, isFiniteNumber, normalizeAdapterActivationConfig, resolveBenchProgressSummary, resolveDistillDatasetPath, resolveDistillShardProgressContext, trainingHarness, tryActivateAdapterPayload } from './suite/execution.js';
37
+ export { runTrainingSuite, trainingHarness } from './suite/execution.js';
38
+ export { buildDistillTrainingOverrides, createDistillRuntimeContext, createToyModelFixture, loadDistillDatasetFromJsonl, loadDistillModelHandle, normalizeDistillStudentGraphMode } from './suite/plan.js';
105
39
 
106
40
  function makeTensorFromF16Bits(values, shape, label) {
107
41
  const data = values instanceof Uint16Array ? values : new Uint16Array(values);
@@ -110,886 +44,10 @@ function makeTensorFromF16Bits(values, shape, label) {
110
44
  return createTensor(buffer, 'f16', shape, label || 'train_tensor_f16');
111
45
  }
112
46
 
113
- function makeTensorFromUint32(values, shape, label) {
114
- const data = values instanceof Uint32Array ? values : new Uint32Array(values);
115
- const buffer = acquireBuffer(data.byteLength, undefined, label || 'train_tokens');
116
- uploadData(buffer, data);
117
- // Token tensors are wrapped as f32 by contract; kernels read the underlying u32 bytes.
118
- return createTensor(buffer, 'f32', shape, label || 'train_tokens');
119
- }
120
-
121
- function releaseTensor(tensor) {
122
- if (!tensor?.buffer) return;
123
- releaseBuffer(tensor.buffer);
124
- }
125
-
126
- function isFiniteNumber(value) {
127
- return typeof value === 'number' && Number.isFinite(value);
128
- }
129
-
130
- function isNodeRuntime() {
131
- return typeof process !== 'undefined' && !!process.versions?.node;
132
- }
133
-
134
47
  export { buildDistillPrompt, resolveDistillDataScope };
135
48
 
136
- function toFiniteNumber(value, fallback) {
137
- const parsed = Number(value);
138
- return Number.isFinite(parsed) ? parsed : fallback;
139
- }
140
-
141
- function clampDistillTopK(value) {
142
- const parsed = Math.floor(toFiniteNumber(value, DISTILL_ADAPTER_TOP_K));
143
- return Math.max(2, Math.min(256, parsed));
144
- }
145
-
146
- export function normalizeDistillStudentGraphMode(value) {
147
- const normalized = normalizeOptionalString(value);
148
- if (!normalized) return DISTILL_STUDENT_GRAPH_FULL;
149
- const compact = normalized.toLowerCase().replace(/[-\s]/g, '_');
150
- if (compact === 'projection_head' || compact === 'projection') {
151
- return DISTILL_STUDENT_GRAPH_PROJECTION;
152
- }
153
- return DISTILL_STUDENT_GRAPH_FULL;
154
- }
155
-
156
- function toFloat32Array(values, label = 'values') {
157
- if (values instanceof Float32Array) return values;
158
- if (ArrayBuffer.isView(values)) {
159
- return new Float32Array(values.buffer.slice(values.byteOffset, values.byteOffset + values.byteLength));
160
- }
161
- if (Array.isArray(values)) {
162
- return new Float32Array(values);
163
- }
164
- throw new Error(`Distill ${label} must be an array-like float buffer.`);
165
- }
166
-
167
- function selectTopKIndices(logits, topK) {
168
- const k = Math.max(1, Math.floor(topK));
169
- const indices = new Int32Array(k);
170
- const values = new Float32Array(k);
171
- indices.fill(-1);
172
- values.fill(-Infinity);
173
-
174
- for (let i = 0; i < logits.length; i += 1) {
175
- const value = Number.isFinite(logits[i]) ? logits[i] : DISTILL_LOGIT_FALLBACK;
176
- if (value <= values[k - 1]) continue;
177
- let insert = k - 1;
178
- while (insert > 0 && value > values[insert - 1]) {
179
- values[insert] = values[insert - 1];
180
- indices[insert] = indices[insert - 1];
181
- insert -= 1;
182
- }
183
- values[insert] = value;
184
- indices[insert] = i;
185
- }
186
-
187
- for (let i = 0; i < k; i += 1) {
188
- if (indices[i] >= 0) continue;
189
- indices[i] = i < logits.length ? i : -1;
190
- }
191
- return indices;
192
- }
193
-
194
- function gatherLogitsByIndices(logits, indices, fallback = DISTILL_LOGIT_FALLBACK) {
195
- const gathered = new Float32Array(indices.length);
196
- for (let i = 0; i < indices.length; i += 1) {
197
- const tokenIndex = indices[i];
198
- if (tokenIndex >= 0 && tokenIndex < logits.length) {
199
- const value = logits[tokenIndex];
200
- gathered[i] = Number.isFinite(value) ? value : fallback;
201
- continue;
202
- }
203
- gathered[i] = fallback;
204
- }
205
- return gathered;
206
- }
207
-
208
- function argmax(values) {
209
- let bestIndex = 0;
210
- let bestValue = Number.NEGATIVE_INFINITY;
211
- for (let i = 0; i < values.length; i += 1) {
212
- const value = Number.isFinite(values[i]) ? values[i] : Number.NEGATIVE_INFINITY;
213
- if (value > bestValue) {
214
- bestValue = value;
215
- bestIndex = i;
216
- }
217
- }
218
- return bestIndex;
219
- }
220
-
221
- function softmax(values, temperature = 1) {
222
- const t = Math.max(1e-4, toFiniteNumber(temperature, 1));
223
- let max = Number.NEGATIVE_INFINITY;
224
- for (let i = 0; i < values.length; i += 1) {
225
- const candidate = values[i] / t;
226
- if (candidate > max) max = candidate;
227
- }
228
- const exps = new Float32Array(values.length);
229
- let sum = 0;
230
- for (let i = 0; i < values.length; i += 1) {
231
- const value = Math.exp((values[i] / t) - max);
232
- exps[i] = value;
233
- sum += value;
234
- }
235
- if (!Number.isFinite(sum) || sum <= 0) {
236
- const uniform = 1 / Math.max(1, values.length);
237
- exps.fill(uniform);
238
- return exps;
239
- }
240
- for (let i = 0; i < exps.length; i += 1) {
241
- exps[i] /= sum;
242
- }
243
- return exps;
244
- }
245
-
246
- function disposePrefillSnapshot(result) {
247
- const cache = result?.cache;
248
- if (cache && typeof cache.clear === 'function') {
249
- cache.clear();
250
- }
251
- }
252
-
253
- function buildShuffledIndices(length, seed = 1337) {
254
- const indices = Array.from({ length }, (_, idx) => idx);
255
- let state = (Number(seed) >>> 0) || 0x6d2b79f5;
256
- for (let i = indices.length - 1; i > 0; i -= 1) {
257
- state = ((state * 1664525) + 1013904223) >>> 0;
258
- const j = state % (i + 1);
259
- const tmp = indices[i];
260
- indices[i] = indices[j];
261
- indices[j] = tmp;
262
- }
263
- return indices;
264
- }
265
-
266
- function normalizeDistillStage(value) {
267
- const stage = String(value || '').trim();
268
- return stage === 'stage_b' ? 'stage_b' : 'stage_a';
269
- }
270
-
271
- async function computeTeacherPromptDistillFeatures(sample, prompt, runtime) {
272
- const teacherResult = await runtime.teacherPipeline.prefillWithLogits(prompt, {
273
- useChatTemplate: false,
274
- });
275
- try {
276
- const teacherLogits = toFloat32Array(teacherResult?.logits, 'teacher logits');
277
- const topTokenIndices = selectTopKIndices(teacherLogits, runtime.topK);
278
- const teacherTopLogits = gatherLogitsByIndices(teacherLogits, topTokenIndices, DISTILL_LOGIT_FALLBACK);
279
- const teacherTopProbs = softmax(teacherTopLogits, runtime.temperature);
280
- const targetClass = argmax(teacherTopLogits);
281
- return {
282
- source: sample.source,
283
- direction: sample.direction,
284
- targetClass,
285
- topTokenIndices: Array.from(topTokenIndices),
286
- teacherTopLogits,
287
- teacherTopProbs,
288
- };
289
- } finally {
290
- disposePrefillSnapshot(teacherResult);
291
- runtime.teacherPipeline.reset();
292
- }
293
- }
294
-
295
- function createDistillTensorDataset(samples, options = {}) {
296
- if (!Array.isArray(samples) || samples.length === 0) {
297
- throw new Error('Distill dataset has no usable rows.');
298
- }
299
- const distillRuntime = options.distillRuntime && typeof options.distillRuntime === 'object'
300
- ? options.distillRuntime
301
- : null;
302
- if (!distillRuntime?.teacherPipeline) {
303
- throw new Error('Distill dataset requires teacherPipeline.');
304
- }
305
- const batchSize = Math.max(1, Math.floor(Number(options.batchSize) || 1));
306
- const shuffle = options.shuffle === true;
307
- const seed = Number.isInteger(options.seed) ? options.seed : 1337;
308
- const stage = normalizeDistillStage(distillRuntime.stage);
309
- const topK = clampDistillTopK(distillRuntime.topK);
310
-
311
- return {
312
- async *batches() {
313
- const order = shuffle
314
- ? buildShuffledIndices(samples.length, seed)
315
- : Array.from({ length: samples.length }, (_, idx) => idx);
316
- let inputTensor = null;
317
- let targetTensor = null;
318
- let tensorBatchSize = 0;
319
- try {
320
- for (let offset = 0; offset < order.length; offset += batchSize) {
321
- const batchIndices = order.slice(offset, offset + batchSize);
322
- const features = new Float32Array(batchIndices.length * topK);
323
- const targets = new Uint32Array(batchIndices.length);
324
- const teacherTopProbs = [];
325
- const teacherTopTokenIndices = [];
326
- const teacherTopLogits = [];
327
- const teacherTargetIndices = [];
328
- const teacherTargetTokenIds = [];
329
- const prompts = [];
330
- const tripletPositivePrompts = [];
331
- const tripletNegativePrompts = [];
332
- const tripletMask = [];
333
- const directionCounts = {};
334
-
335
- for (let i = 0; i < batchIndices.length; i += 1) {
336
- const sample = samples[batchIndices[i]];
337
- const prompt = buildDistillPrompt(sample);
338
- const baseDistill = await computeTeacherPromptDistillFeatures(sample, prompt, {
339
- ...distillRuntime,
340
- topK,
341
- });
342
-
343
- const baseOffset = i * topK;
344
- features.set(baseDistill.teacherTopLogits, baseOffset);
345
- const targetClass = baseDistill.targetClass;
346
- const targetToken = Number.isInteger(baseDistill.topTokenIndices?.[targetClass])
347
- ? baseDistill.topTokenIndices[targetClass]
348
- : targetClass;
349
- const targetTokenMode = distillRuntime.targetTokenMode === 'teacher_top_token';
350
- targets[i] = targetTokenMode ? targetToken : targetClass;
351
- teacherTargetIndices.push(targetClass);
352
- teacherTargetTokenIds.push(targetToken);
353
- teacherTopProbs.push(baseDistill.teacherTopProbs);
354
- teacherTopTokenIndices.push(baseDistill.topTokenIndices);
355
- teacherTopLogits.push(baseDistill.teacherTopLogits);
356
- prompts.push(prompt);
357
-
358
- if (stage === 'stage_b') {
359
- const posPrompt = buildDistillCandidatePrompt(sample, sample.targetPos);
360
- const negPrompt = sample.targetNeg
361
- ? buildDistillCandidatePrompt(sample, sample.targetNeg)
362
- : null;
363
- tripletPositivePrompts.push(posPrompt);
364
- tripletNegativePrompts.push(negPrompt || posPrompt);
365
- tripletMask.push(Boolean(negPrompt));
366
- }
367
-
368
- directionCounts[sample.direction] = (directionCounts[sample.direction] || 0) + 1;
369
- }
370
-
371
- if (!inputTensor || !targetTensor || tensorBatchSize !== batchIndices.length) {
372
- releaseTensor(inputTensor);
373
- releaseTensor(targetTensor);
374
- inputTensor = makeTensorFromFloat32(
375
- features,
376
- [batchIndices.length, topK],
377
- 'distill_jsonl_input'
378
- );
379
- targetTensor = makeTensorFromUint32(
380
- targets,
381
- [batchIndices.length],
382
- 'distill_jsonl_targets'
383
- );
384
- tensorBatchSize = batchIndices.length;
385
- } else {
386
- uploadData(inputTensor.buffer, features);
387
- uploadData(targetTensor.buffer, targets);
388
- }
389
- yield {
390
- input: inputTensor,
391
- targets: targetTensor,
392
- distill: {
393
- prompts,
394
- tripletPositivePrompts,
395
- tripletNegativePrompts,
396
- tripletMask,
397
- teacherTopProbs,
398
- teacherTopTokenIndices,
399
- teacherTopLogits,
400
- teacherTargetIndices,
401
- teacherTargetTokenIds,
402
- targetTokenMode: distillRuntime.targetTokenMode || 'topk_class',
403
- batchSampleCount: batchIndices.length,
404
- directionCounts,
405
- distillStage: stage,
406
- temperature: toFiniteNumber(distillRuntime.temperature, 1),
407
- alphaKd: toFiniteNumber(distillRuntime.alphaKd, 1),
408
- alphaCe: toFiniteNumber(distillRuntime.alphaCe, 0),
409
- tripletMargin: Math.max(0, toFiniteNumber(distillRuntime.tripletMargin, 0.2)),
410
- teacherModelId: distillRuntime.teacherModelId || null,
411
- studentModelId: distillRuntime.studentModelId || null,
412
- },
413
- };
414
- }
415
- } finally {
416
- releaseTensor(inputTensor);
417
- releaseTensor(targetTensor);
418
- }
419
- },
420
- };
421
- }
422
-
423
- export async function loadDistillDatasetFromJsonl(datasetPath, scopeOptions = null) {
424
- const normalizedPath = normalizeDistillDatasetPath(datasetPath);
425
- if (!normalizedPath) return null;
426
- if (!isNodeRuntime()) {
427
- throw new Error('distillDatasetPath currently requires Node runtime.');
428
- }
429
- const normalizedScope = (
430
- scopeOptions && typeof scopeOptions === 'object'
431
- ? scopeOptions
432
- : resolveDistillDataScope()
433
- );
434
-
435
- const [{ readFile }, { resolve, dirname, isAbsolute, join, sep }] = await Promise.all([
436
- import('node:fs/promises'),
437
- import('node:path'),
438
- ]);
439
-
440
- const isShardManifest = (candidate) => {
441
- if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) return false;
442
- if (!Array.isArray(candidate.shards) || candidate.shards.length === 0) return false;
443
- return candidate.shards.every((entry) => {
444
- if (typeof entry === 'string' && entry.trim()) return true;
445
- if (entry && typeof entry === 'object' && typeof entry.path === 'string' && entry.path.trim()) return true;
446
- return false;
447
- });
448
- };
449
- const resolveShardPath = (entry, manifestDir) => {
450
- const rawPath = typeof entry === 'string' ? entry : entry.path;
451
- const normalized = String(rawPath || '').trim();
452
- if (!normalized) return null;
453
- if (isAbsolute(normalized)) return normalized;
454
- if (normalized.startsWith(`.${sep}`) || normalized.startsWith(`..${sep}`)) {
455
- return resolve(manifestDir, normalized);
456
- }
457
- const projectsPrefix = `projects${sep}`;
458
- if (normalized.startsWith(projectsPrefix)) {
459
- const marker = `${sep}projects${sep}`;
460
- const markerIndex = manifestDir.lastIndexOf(marker);
461
- if (markerIndex >= 0) {
462
- const workspaceRoot = manifestDir.slice(0, markerIndex);
463
- return join(workspaceRoot, normalized);
464
- }
465
- }
466
- return join(manifestDir, normalized);
467
- };
468
- const loadEncodedRows = (rawRows, contextLabel) => {
469
- const encodedRows = [];
470
- for (let i = 0; i < rawRows.length; i += 1) {
471
- let encoded = null;
472
- try {
473
- encoded = encodeDistillRow(rawRows[i], i, normalizedScope);
474
- } catch (error) {
475
- const message = error?.message ? String(error.message) : String(error);
476
- throw new Error(`${contextLabel}: row ${i + 1}: ${message}`);
477
- }
478
- if (encoded) encodedRows.push(encoded);
479
- }
480
- return encodedRows;
481
- };
482
-
483
- const absolutePath = resolve(normalizedPath);
484
- let raw;
485
- try {
486
- raw = await readFile(absolutePath, 'utf8');
487
- } catch (error) {
488
- const message = error?.message ? String(error.message) : String(error);
489
- throw new Error(`Failed to read distillDatasetPath "${absolutePath}": ${message}`);
490
- }
491
-
492
- let parsedJson = null;
493
- try {
494
- parsedJson = JSON.parse(raw);
495
- } catch {
496
- parsedJson = null;
497
- }
498
- if (isShardManifest(parsedJson)) {
499
- const manifestDir = dirname(absolutePath);
500
- const shardPaths = parsedJson.shards
501
- .map((entry) => resolveShardPath(entry, manifestDir))
502
- .filter(Boolean);
503
- if (shardPaths.length === 0) {
504
- throw new Error(`Distill shard manifest "${absolutePath}" has no valid shard paths.`);
505
- }
506
- let rowCount = 0;
507
- let sampleCount = 0;
508
- const directionCounts = {};
509
- for (const shardPath of shardPaths) {
510
- const shardRaw = await readFile(shardPath, 'utf8');
511
- const shardRows = parseJsonl(shardRaw);
512
- const encodedRows = loadEncodedRows(shardRows, `distill shard "${shardPath}"`);
513
- rowCount += shardRows.length;
514
- sampleCount += encodedRows.length;
515
- const shardDirections = summarizeDirectionCounts(encodedRows);
516
- for (const [direction, count] of Object.entries(shardDirections)) {
517
- directionCounts[direction] = (directionCounts[direction] || 0) + count;
518
- }
519
- }
520
- if (sampleCount <= 0) {
521
- throw new Error(`Distill shard manifest "${absolutePath}" has no usable rows across shards.`);
522
- }
523
- return {
524
- absolutePath,
525
- rowCount,
526
- sampleCount,
527
- directionCounts,
528
- dataScope: {
529
- sourceLangs: normalizedScope.sourceLangs || null,
530
- targetLangs: normalizedScope.targetLangs || null,
531
- pairAllowlist: normalizedScope.pairAllowlist || null,
532
- strictPairContract: normalizedScope.strictPairContract === true,
533
- },
534
- shardCount: shardPaths.length,
535
- shardPaths,
536
- createDataset(runOptions = {}) {
537
- const shardSeedBase = Number.isInteger(runOptions.seed) ? runOptions.seed : 1337;
538
- return {
539
- async *batches() {
540
- for (let shardIndex = 0; shardIndex < shardPaths.length; shardIndex += 1) {
541
- const shardPath = shardPaths[shardIndex];
542
- const shardRaw = await readFile(shardPath, 'utf8');
543
- const shardRows = parseJsonl(shardRaw);
544
- const encodedRows = loadEncodedRows(shardRows, `distill shard "${shardPath}"`);
545
- if (encodedRows.length === 0) continue;
546
- const shardDataset = createDistillTensorDataset(encodedRows, {
547
- ...runOptions,
548
- seed: shardSeedBase + shardIndex,
549
- });
550
- for await (const batch of shardDataset.batches()) {
551
- if (batch?.distill && typeof batch.distill === 'object') {
552
- batch.distill.datasetShardIndex = shardIndex + 1;
553
- batch.distill.datasetShardCount = shardPaths.length;
554
- batch.distill.datasetShardPath = shardPath;
555
- }
556
- yield batch;
557
- }
558
- }
559
- },
560
- };
561
- },
562
- };
563
- }
564
-
565
- const rows = parseJsonl(raw);
566
- const encodedRows = loadEncodedRows(rows, `distill dataset "${absolutePath}"`);
567
- if (encodedRows.length === 0) {
568
- throw new Error(`Distill dataset "${absolutePath}" has no usable rows.`);
569
- }
570
-
571
- return {
572
- absolutePath,
573
- rowCount: rows.length,
574
- sampleCount: encodedRows.length,
575
- directionCounts: summarizeDirectionCounts(encodedRows),
576
- dataScope: {
577
- sourceLangs: normalizedScope.sourceLangs || null,
578
- targetLangs: normalizedScope.targetLangs || null,
579
- pairAllowlist: normalizedScope.pairAllowlist || null,
580
- strictPairContract: normalizedScope.strictPairContract === true,
581
- },
582
- createDataset(runOptions = {}) {
583
- return createDistillTensorDataset(encodedRows, runOptions);
584
- },
585
- };
586
- }
587
-
588
- function looksLikeUrl(value) {
589
- return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(String(value || '').trim());
590
- }
591
-
592
- function looksLikeFilesystemPath(value) {
593
- const normalized = String(value || '').trim();
594
- return normalized.startsWith('/') || normalized.startsWith('./') || normalized.startsWith('../');
595
- }
596
-
597
- async function resolveNodeModelUrlFromRef(modelRef) {
598
- if (!isNodeRuntime()) return null;
599
- const [{ access, constants }, { resolve, join }, { pathToFileURL }] = await Promise.all([
600
- import('node:fs/promises'),
601
- import('node:path'),
602
- import('node:url'),
603
- ]);
604
-
605
- const normalized = String(modelRef || '').trim();
606
- if (!normalized) return null;
607
- const candidates = [
608
- normalized,
609
- join('models', 'local', normalized),
610
- join('models', 'curated', normalized),
611
- ];
612
- for (const candidate of candidates) {
613
- const absolutePath = resolve(candidate);
614
- const manifestPath = join(absolutePath, 'manifest.json');
615
- try {
616
- await access(manifestPath, constants.R_OK);
617
- return pathToFileURL(absolutePath).href;
618
- } catch {
619
- // Try next candidate.
620
- }
621
- }
622
- return null;
623
- }
624
-
625
- async function initializeInferenceFromStore(modelId) {
626
- await openModelStore(modelId);
627
- const manifestText = await loadManifestFromStore();
628
- if (!manifestText) {
629
- throw new Error(`Manifest not found in store for model "${modelId}".`);
630
- }
631
- const manifest = parseManifest(manifestText);
632
- const pipeline = await createPipeline(manifest, {
633
- gpu: { device: getDevice() },
634
- });
635
- return { pipeline, manifest };
636
- }
637
-
638
- export async function loadDistillModelHandle(modelRef, role, loadOptions = {}) {
639
- const normalizedRef = normalizeOptionalString(modelRef);
640
- if (!normalizedRef) {
641
- throw new Error(`Distill ${role} model reference is required.`);
642
- }
643
-
644
- const loadFromUrl = async (url) => {
645
- const initialized = await initializeInference(url, {
646
- log: () => {},
647
- onProgress: () => {},
648
- runtime: loadOptions.runtime || undefined,
649
- });
650
- return {
651
- modelRef: normalizedRef,
652
- modelUrl: url,
653
- manifest: initialized.manifest,
654
- pipeline: initialized.pipeline,
655
- };
656
- };
657
-
658
- if (looksLikeUrl(normalizedRef)) {
659
- return loadFromUrl(normalizedRef);
660
- }
661
-
662
- if (isNodeRuntime()) {
663
- const localUrl = await resolveNodeModelUrlFromRef(normalizedRef);
664
- if (localUrl) {
665
- return loadFromUrl(localUrl);
666
- }
667
- }
668
-
669
- if (looksLikeFilesystemPath(normalizedRef) && isNodeRuntime()) {
670
- const [{ resolve }, { pathToFileURL }] = await Promise.all([
671
- import('node:path'),
672
- import('node:url'),
673
- ]);
674
- return loadFromUrl(pathToFileURL(resolve(normalizedRef)).href);
675
- }
676
-
677
- const { pipeline, manifest } = await initializeInferenceFromStore(normalizedRef);
678
- return {
679
- modelRef: normalizedRef,
680
- modelUrl: null,
681
- manifest,
682
- pipeline,
683
- };
684
- }
685
-
686
- function resolveDistillModelRefs(options = {}, trainingConfig = null) {
687
- const distillConfig = trainingConfig?.distill || {};
688
- return {
689
- teacherModelRef: normalizeOptionalString(options.teacherModelId ?? distillConfig.teacherModelId),
690
- studentModelRef: normalizeOptionalString(options.studentModelId ?? distillConfig.studentModelId),
691
- };
692
- }
693
-
694
- export async function createDistillRuntimeContext(options = {}, trainingConfig = null) {
695
- const { teacherModelRef, studentModelRef } = resolveDistillModelRefs(options, trainingConfig);
696
- if (!teacherModelRef || !studentModelRef) {
697
- throw new Error('Distill stage requires teacherModelId and studentModelId.');
698
- }
699
-
700
- const distillConfig = trainingConfig?.distill || {};
701
- const studentGraphMode = normalizeDistillStudentGraphMode(
702
- options.studentGraphMode
703
- ?? distillConfig.studentGraphMode
704
- );
705
- const teacher = await loadDistillModelHandle(teacherModelRef, 'teacher');
706
- const studentRuntime = studentGraphMode === DISTILL_STUDENT_GRAPH_FULL
707
- ? {
708
- runtimeConfig: {
709
- shared: {
710
- debug: {
711
- logLevel: {
712
- defaultLogLevel: 'debug',
713
- },
714
- },
715
- },
716
- inference: {
717
- compute: {
718
- activationDtype: 'f32',
719
- keepF32Weights: true,
720
- },
721
- },
722
- },
723
- }
724
- : null;
725
- let student = null;
726
- try {
727
- student = await loadDistillModelHandle(studentModelRef, 'student', {
728
- runtime: studentRuntime,
729
- });
730
- } catch (error) {
731
- if (teacher?.pipeline && typeof teacher.pipeline.unload === 'function') {
732
- await teacher.pipeline.unload();
733
- }
734
- throw error;
735
- }
736
-
737
- const runtime = {
738
- stage: normalizeDistillStage(options.trainingStage || distillConfig.stage),
739
- teacherPipeline: teacher.pipeline,
740
- studentPipeline: student.pipeline,
741
- teacherModelId: teacher.manifest?.modelId || teacherModelRef,
742
- studentModelId: student.manifest?.modelId || studentModelRef,
743
- teacherModelUrl: teacher.modelUrl || null,
744
- studentModelUrl: student.modelUrl || null,
745
- topK: clampDistillTopK(distillConfig.topK ?? DISTILL_ADAPTER_TOP_K),
746
- temperature: Math.max(1e-4, toFiniteNumber(distillConfig.temperature, 1)),
747
- alphaKd: toFiniteNumber(distillConfig.alphaKd, 1),
748
- alphaCe: toFiniteNumber(distillConfig.alphaCe, 0),
749
- tripletMargin: Math.max(0, toFiniteNumber(distillConfig.tripletMargin, 0.2)),
750
- studentGraphMode,
751
- targetTokenMode: studentGraphMode === DISTILL_STUDENT_GRAPH_FULL
752
- ? 'teacher_top_token'
753
- : 'topk_class',
754
- async cleanup() {
755
- if (teacher?.pipeline && typeof teacher.pipeline.unload === 'function') {
756
- await teacher.pipeline.unload();
757
- }
758
- if (student?.pipeline && typeof student.pipeline.unload === 'function') {
759
- await student.pipeline.unload();
760
- }
761
- },
762
- };
763
- return runtime;
764
- }
765
-
766
- function resolveDistillDatasetPath(options = {}, trainingConfig = null) {
767
- return normalizeDistillDatasetPath(
768
- options.distillDatasetPath ?? trainingConfig?.distill?.datasetPath ?? null
769
- );
770
- }
771
-
772
- function resolveRuntimeUrl(pathname) {
773
- if (typeof globalThis.location !== 'undefined' && globalThis.location?.href) {
774
- return pathname;
775
- }
776
- return new URL(pathname, import.meta.url).toString();
777
- }
778
-
779
- async function ensureTrainingGpuRuntime() {
780
- setPlatformsBaseUrl(resolveRuntimeUrl('../../config/platforms/'));
781
- setRegistryUrl(resolveRuntimeUrl('../../config/kernels/registry.json'));
782
- await initDevice();
783
- }
784
-
785
- export function createToyModelFixture(overrides = {}) {
786
- const config = createTrainingConfig({
787
- ...overrides,
788
- training: {
789
- enabled: true,
790
- lossScaling: { enabled: false },
791
- gradient: { maxNorm: 0 },
792
- ...(overrides.training || {}),
793
- },
794
- });
795
-
796
- const encoderWeight = makeTensorFromFloat32(
797
- [0.1, -0.2, 0.3, 0.4, 0.05, -0.1],
798
- [3, 2],
799
- 'training_suite_encoder_weight'
800
- );
801
- const priorWeight = makeTensorFromFloat32(
802
- [0.02, -0.01, 0.03, -0.05, 0.04, -0.02],
803
- [3, 2],
804
- 'training_suite_prior_weight'
805
- );
806
- const decoderWeight = makeTensorFromFloat32(
807
- [0.03, 0.02, -0.01, 0.06, -0.04, 0.02],
808
- [3, 2],
809
- 'training_suite_decoder_weight'
810
- );
811
- const baseWeight = makeTensorFromFloat32(
812
- [0.08, -0.12, 0.16, 0.22, -0.03, 0.09],
813
- [3, 2],
814
- 'training_suite_base_weight'
815
- );
816
- const input = makeTensorFromFloat32([0.5, 0.1, -0.3, 0.2, 0.4, -0.1], [2, 3], 'training_suite_input');
817
- const targets = makeTensorFromUint32([1, 0], [2], 'training_suite_targets');
818
- const batch = { input, targets };
819
-
820
- const model = {
821
- async forward(inputTensor, tape) {
822
- return tape.record(
823
- OpType.MATMUL,
824
- (a, b) => runMatmul(a, b, 2, 2, 3, { transposeB: false, outputDtype: 'f32' }),
825
- [inputTensor, baseWeight],
826
- { M: 2, N: 2, K: 3, transposeB: false }
827
- );
828
- },
829
- loraParams() {
830
- return [baseWeight];
831
- },
832
- paramGroups() {
833
- return {
834
- encoder: [encoderWeight],
835
- prior: [priorWeight],
836
- decoder: [decoderWeight],
837
- base: [baseWeight],
838
- lora: [baseWeight],
839
- };
840
- },
841
- };
842
-
843
- return {
844
- config,
845
- model,
846
- batch,
847
- cleanup() {
848
- releaseTensor(encoderWeight);
849
- releaseTensor(priorWeight);
850
- releaseTensor(decoderWeight);
851
- releaseTensor(baseWeight);
852
- releaseTensor(input);
853
- releaseTensor(targets);
854
- },
855
- };
856
- }
857
-
858
49
  export { createDistillStudentRuntimeModelFixture };
859
50
 
860
- async function runRunnerSmokeTest() {
861
- const fixture = createToyModelFixture();
862
- try {
863
- const runner = new TrainingRunner(fixture.config, {
864
- optimizer: new AdamOptimizer(fixture.config),
865
- crossEntropyLoss,
866
- clipGradients,
867
- });
868
- const dataset = {
869
- async *batches() {
870
- for (let i = 0; i < 3; i += 1) {
871
- yield fixture.batch;
872
- }
873
- },
874
- };
875
-
876
- const metrics = await runner.run(fixture.model, dataset, {
877
- epochs: 1,
878
- batchSize: 1,
879
- shuffle: false,
880
- maxSteps: 3,
881
- });
882
- if (!Array.isArray(metrics) || metrics.length === 0) {
883
- return { passed: false, error: 'Training runner produced no metrics.' };
884
- }
885
- for (const entry of metrics) {
886
- if (!isFiniteNumber(entry.total_loss) || !isFiniteNumber(entry.step_time_ms)) {
887
- return { passed: false, error: 'Training runner emitted non-finite metrics.' };
888
- }
889
- }
890
-
891
- return { passed: true };
892
- } finally {
893
- fixture.cleanup();
894
- }
895
- }
896
-
897
- async function runTrainStepMetricsTest() {
898
- const fixture = createToyModelFixture();
899
- try {
900
- const result = await trainStep(fixture.model, fixture.batch, fixture.config, {
901
- crossEntropyLoss,
902
- clipGradients,
903
- optimizer: new AdamOptimizer(fixture.config),
904
- });
905
-
906
- if (!isFiniteNumber(result.forward_ms) || !isFiniteNumber(result.backward_ms)) {
907
- return { passed: false, error: 'trainStep did not report finite phase timings.' };
908
- }
909
- if (!result.clipMetrics || !isFiniteNumber(result.clipMetrics.gradient_norm_unclipped)) {
910
- return { passed: false, error: 'trainStep did not report clipping metrics.' };
911
- }
912
- if (!result.optimizerMetrics || !isFiniteNumber(result.optimizerMetrics.optimizer_ms)) {
913
- return { passed: false, error: 'trainStep did not report optimizer metrics.' };
914
- }
915
-
916
- return { passed: true };
917
- } finally {
918
- fixture.cleanup();
919
- }
920
- }
921
-
922
- const UL_STAGE_SET = Object.freeze(['stage1_joint', 'stage2_base']);
923
- const DISTILL_STAGE_SET = Object.freeze(['stage_a', 'stage_b']);
924
- const TRAINING_STAGE_SET = Object.freeze([...UL_STAGE_SET, ...DISTILL_STAGE_SET]);
925
-
926
- function normalizeTrainingStage(stage) {
927
- const normalized = String(stage || '').trim();
928
- if (!normalized) return null;
929
- if (!TRAINING_STAGE_SET.includes(normalized)) {
930
- throw new Error(`Unknown training stage "${normalized}". Expected one of: ${TRAINING_STAGE_SET.join(', ')}.`);
931
- }
932
- return normalized;
933
- }
934
-
935
- function isUlStage(stage) {
936
- return UL_STAGE_SET.includes(String(stage || ''));
937
- }
938
-
939
- function isDistillStage(stage) {
940
- return DISTILL_STAGE_SET.includes(String(stage || ''));
941
- }
942
-
943
- function normalizeTrainingConfigOverride(value) {
944
- if (!value) return null;
945
- if (typeof value !== 'object' || Array.isArray(value)) {
946
- throw new Error('trainingConfig must be an object when provided.');
947
- }
948
- return value;
949
- }
950
-
951
- function normalizeAdapterActivationConfig(options = {}) {
952
- const runtimeConfig = normalizeTrainingConfigOverride(options.trainingConfig);
953
- const direct = options.adapterActivation;
954
- const nested = runtimeConfig?.adapterActivation;
955
- const config = direct && typeof direct === 'object' ? direct : (nested && typeof nested === 'object' ? nested : null);
956
- if (!config) {
957
- return {
958
- enabled: false,
959
- autoActivate: false,
960
- adapterPayload: null,
961
- exportConfig: null,
962
- };
963
- }
964
- const exportConfig = config.export && typeof config.export === 'object'
965
- ? config.export
966
- : null;
967
- const adapterPayload = (() => {
968
- if (config.adapterManifest && typeof config.adapterManifest === 'object') {
969
- return { adapterManifest: config.adapterManifest };
970
- }
971
- if (typeof config.adapterManifestJson === 'string' && config.adapterManifestJson.trim()) {
972
- return { adapterManifestJson: config.adapterManifestJson };
973
- }
974
- if (typeof config.adapterManifestUrl === 'string' && config.adapterManifestUrl.trim()) {
975
- return { adapterManifestUrl: config.adapterManifestUrl };
976
- }
977
- if (typeof config.adapterManifestPath === 'string' && config.adapterManifestPath.trim()) {
978
- return { adapterManifestPath: config.adapterManifestPath };
979
- }
980
- if (config.adapter != null) {
981
- return { adapter: config.adapter };
982
- }
983
- return null;
984
- })();
985
- return {
986
- enabled: config.enabled !== false,
987
- autoActivate: config.autoActivate === true,
988
- adapterPayload,
989
- exportConfig,
990
- };
991
- }
992
-
993
51
  function normalizeLoRAExportConfig(value) {
994
52
  if (!value || typeof value !== 'object' || Array.isArray(value)) {
995
53
  return null;
@@ -1083,626 +141,6 @@ async function exportLoRAAdapterFromModel(model, exportConfig, runIndex = null)
1083
141
  };
1084
142
  }
1085
143
 
1086
- async function tryActivateAdapterPayload(payload) {
1087
- if (!payload) {
1088
- return {
1089
- activated: false,
1090
- adapterName: null,
1091
- source: null,
1092
- reason: 'no_adapter_payload',
1093
- };
1094
- }
1095
- const { activateLoRAFromTrainingOutput } = await import('../../client/runtime/model-manager.js');
1096
- try {
1097
- return await activateLoRAFromTrainingOutput(payload);
1098
- } catch (error) {
1099
- return {
1100
- activated: false,
1101
- adapterName: null,
1102
- source: null,
1103
- reason: String(error?.message || error),
1104
- };
1105
- }
1106
- }
1107
-
1108
- function buildUlTrainingOverrides(options = {}) {
1109
- const trainingConfig = normalizeTrainingConfigOverride(options.trainingConfig);
1110
- const explicitStage = normalizeTrainingStage(options.trainingStage || trainingConfig?.ul?.stage);
1111
- const ulEnabled = isUlStage(explicitStage) || trainingConfig?.ul?.enabled === true;
1112
- if (!ulEnabled) {
1113
- return trainingConfig || null;
1114
- }
1115
- const stage = isUlStage(explicitStage) ? explicitStage : 'stage1_joint';
1116
- const ulOverride = {
1117
- ...(trainingConfig?.ul || {}),
1118
- enabled: true,
1119
- stage,
1120
- stage1Artifact: options.stage1Artifact ?? trainingConfig?.ul?.stage1Artifact ?? null,
1121
- stage1ArtifactHash: options.stage1ArtifactHash ?? trainingConfig?.ul?.stage1ArtifactHash ?? null,
1122
- artifactDir: options.ulArtifactDir ?? trainingConfig?.ul?.artifactDir ?? 'reports/training/ul',
1123
- };
1124
- if (stage === 'stage2_base') {
1125
- ulOverride.freeze = {
1126
- encoder: true,
1127
- prior: true,
1128
- decoder: true,
1129
- base: false,
1130
- lora: false,
1131
- ...(trainingConfig?.ul?.freeze || {}),
1132
- };
1133
- }
1134
- return {
1135
- ...(trainingConfig || {}),
1136
- ul: ulOverride,
1137
- };
1138
- }
1139
-
1140
- export function buildDistillTrainingOverrides(options = {}) {
1141
- const trainingConfig = normalizeTrainingConfigOverride(options.trainingConfig);
1142
- const explicitStage = normalizeTrainingStage(options.trainingStage || trainingConfig?.distill?.stage);
1143
- const distillEnabled = isDistillStage(explicitStage) || trainingConfig?.distill?.enabled === true;
1144
- if (!distillEnabled) {
1145
- return trainingConfig || null;
1146
- }
1147
- const stage = isDistillStage(explicitStage) ? explicitStage : 'stage_a';
1148
- const distillOverride = {
1149
- ...(trainingConfig?.distill || {}),
1150
- enabled: true,
1151
- stage,
1152
- teacherModelId: options.teacherModelId ?? trainingConfig?.distill?.teacherModelId ?? null,
1153
- studentModelId: options.studentModelId ?? trainingConfig?.distill?.studentModelId ?? null,
1154
- datasetId: options.distillDatasetId ?? trainingConfig?.distill?.datasetId ?? null,
1155
- datasetPath: options.distillDatasetPath ?? trainingConfig?.distill?.datasetPath ?? null,
1156
- languagePair: options.distillLanguagePair ?? trainingConfig?.distill?.languagePair ?? null,
1157
- sourceLangs: (
1158
- options.distillSourceLangs
1159
- ?? trainingConfig?.distill?.sourceLangs
1160
- ?? null
1161
- ),
1162
- targetLangs: (
1163
- options.distillTargetLangs
1164
- ?? trainingConfig?.distill?.targetLangs
1165
- ?? null
1166
- ),
1167
- pairAllowlist: (
1168
- options.distillPairAllowlist
1169
- ?? trainingConfig?.distill?.pairAllowlist
1170
- ?? null
1171
- ),
1172
- strictPairContract: (
1173
- options.strictPairContract === true
1174
- || trainingConfig?.distill?.strictPairContract === true
1175
- ),
1176
- shardIndex: options.distillShardIndex ?? trainingConfig?.distill?.shardIndex ?? null,
1177
- shardCount: options.distillShardCount ?? trainingConfig?.distill?.shardCount ?? null,
1178
- resumeFrom: options.resumeFrom ?? trainingConfig?.distill?.resumeFrom ?? null,
1179
- stageAArtifact: options.stageAArtifact ?? trainingConfig?.distill?.stageAArtifact ?? null,
1180
- stageAArtifactHash: options.stageAArtifactHash ?? trainingConfig?.distill?.stageAArtifactHash ?? null,
1181
- artifactDir: options.distillArtifactDir ?? trainingConfig?.distill?.artifactDir ?? 'reports/training/distill',
1182
- };
1183
- if (stage === 'stage_b') {
1184
- distillOverride.freeze = {
1185
- encoder: true,
1186
- prior: true,
1187
- decoder: true,
1188
- base: false,
1189
- lora: false,
1190
- ...(trainingConfig?.distill?.freeze || {}),
1191
- };
1192
- }
1193
- return {
1194
- ...(trainingConfig || {}),
1195
- distill: distillOverride,
1196
- };
1197
- }
1198
-
1199
- async function computeNodeFileHash(filePath) {
1200
- if (!(typeof process !== 'undefined' && process.versions?.node)) {
1201
- return null;
1202
- }
1203
- const [{ readFile }, { resolve }] = await Promise.all([
1204
- import('node:fs/promises'),
1205
- import('node:path'),
1206
- ]);
1207
- const absolutePath = resolve(String(filePath));
1208
- const raw = await readFile(absolutePath, 'utf8');
1209
- return {
1210
- absolutePath,
1211
- hash: sha256Hex(raw),
1212
- };
1213
- }
1214
-
1215
- async function runUlStageTest(stage, options = {}) {
1216
- const ulTraining = buildUlTrainingOverrides({
1217
- ...options,
1218
- trainingStage: stage,
1219
- });
1220
- const fixture = createToyModelFixture({
1221
- training: ulTraining || undefined,
1222
- });
1223
-
1224
- try {
1225
- const runner = new TrainingRunner(fixture.config, {
1226
- optimizer: new AdamOptimizer(fixture.config),
1227
- crossEntropyLoss,
1228
- clipGradients,
1229
- });
1230
- const dataset = {
1231
- async *batches() {
1232
- for (let i = 0; i < 2; i += 1) {
1233
- yield fixture.batch;
1234
- }
1235
- },
1236
- };
1237
- const ulArtifactDir = normalizeOptionalString(options.ulArtifactDir)
1238
- || normalizeOptionalString(fixture.config.training?.ul?.artifactDir)
1239
- || 'reports/training/ul';
1240
- const metrics = await runner.run(fixture.model, dataset, {
1241
- epochs: 1,
1242
- batchSize: 1,
1243
- shuffle: false,
1244
- maxSteps: 2,
1245
- modelId: options.modelId || 'training',
1246
- modelUrl: options.modelUrl || null,
1247
- runtimeProfile: options.runtimeProfile || null,
1248
- trainingStage: stage,
1249
- command: options.command || null,
1250
- surface: options.surface || null,
1251
- forceResume: options.forceResume === true,
1252
- forceResumeReason: options.forceResumeReason || null,
1253
- forceResumeSource: options.forceResumeSource || null,
1254
- checkpointOperator: options.checkpointOperator || null,
1255
- checkpointEvery: options.checkpointEvery ?? null,
1256
- gpuAdapterInfo: getKernelCapabilities(),
1257
- timestamp: options.timestamp || null,
1258
- ulArtifactDir,
1259
- });
1260
- if (!Array.isArray(metrics) || metrics.length === 0) {
1261
- return { passed: false, error: `UL ${stage} produced no metrics.` };
1262
- }
1263
- const requiredFields = [
1264
- 'loss_prior',
1265
- 'loss_decoder',
1266
- 'loss_recon',
1267
- 'lambda',
1268
- 'latent_bitrate_proxy',
1269
- 'loss_total',
1270
- 'coeff_ce',
1271
- 'coeff_prior',
1272
- 'coeff_decoder',
1273
- 'coeff_recon',
1274
- ];
1275
- if (stage === 'stage1_joint') {
1276
- requiredFields.push(
1277
- 'schedule_step_index',
1278
- 'latent_clean_mean',
1279
- 'latent_clean_std',
1280
- 'latent_noise_mean',
1281
- 'latent_noise_std',
1282
- 'latent_noisy_mean',
1283
- 'latent_noisy_std',
1284
- 'latent_shape',
1285
- 'latent_clean_values',
1286
- 'latent_noise_values',
1287
- 'latent_noisy_values'
1288
- );
1289
- }
1290
- if (stage === 'stage2_base') {
1291
- requiredFields.push('stage1_latent_count');
1292
- }
1293
- for (const field of requiredFields) {
1294
- if (!(field in metrics[0])) {
1295
- return { passed: false, error: `UL ${stage} missing metric field "${field}".` };
1296
- }
1297
- }
1298
- const artifact = runner.lastArtifact;
1299
- if (!artifact || !artifact.manifestPath) {
1300
- return { passed: false, error: `UL ${stage} did not produce artifacts.` };
1301
- }
1302
- return {
1303
- passed: true,
1304
- artifact: {
1305
- ...artifact,
1306
- resumeAudits: Array.isArray(runner.resumeState?.resumeAudits)
1307
- ? runner.resumeState.resumeAudits
1308
- : [],
1309
- },
1310
- metrics: {
1311
- stage,
1312
- steps: metrics.length,
1313
- manifestPath: artifact.manifestPath,
1314
- manifestHash: artifact.manifestHash,
1315
- manifestContentHash: artifact.manifestContentHash,
1316
- manifestFileHash: artifact.manifestFileHash ?? null,
1317
- ulResolvedConfig: {
1318
- enabled: fixture.config.training?.ul?.enabled === true,
1319
- stage: fixture.config.training?.ul?.stage ?? null,
1320
- lambda0: fixture.config.training?.ul?.lambda0 ?? null,
1321
- seed: fixture.config.training?.ul?.seed ?? null,
1322
- noiseSchedule: fixture.config.training?.ul?.noiseSchedule ?? null,
1323
- priorAlignment: fixture.config.training?.ul?.priorAlignment ?? null,
1324
- decoderSigmoidWeight: fixture.config.training?.ul?.decoderSigmoidWeight ?? null,
1325
- freeze: fixture.config.training?.ul?.freeze ?? null,
1326
- },
1327
- resumeAuditCount: Number.isInteger(runner.resumeState?.resumeAuditCount)
1328
- ? runner.resumeState.resumeAuditCount
1329
- : 0,
1330
- },
1331
- };
1332
- } finally {
1333
- fixture.cleanup();
1334
- }
1335
- }
1336
-
1337
- async function runUlStage1Test(options = {}) {
1338
- return runUlStageTest('stage1_joint', options);
1339
- }
1340
-
1341
- async function runUlStage2Test(options = {}) {
1342
- const explicitStage1Artifact = String(options.stage1Artifact || '').trim();
1343
- let stage1Artifact = explicitStage1Artifact || null;
1344
- let stage1ArtifactHash = String(options.stage1ArtifactHash || '').trim() || null;
1345
-
1346
- if (!stage1Artifact) {
1347
- const stage1 = await runUlStage1Test({
1348
- ...options,
1349
- trainingStage: 'stage1_joint',
1350
- });
1351
- if (!stage1?.passed || !stage1?.artifact?.manifestPath) {
1352
- return { passed: false, error: 'UL stage2 preflight failed to generate stage1 artifact.' };
1353
- }
1354
- stage1Artifact = stage1.artifact.manifestPath;
1355
- stage1ArtifactHash = stage1.artifact.manifestHash;
1356
- const nodeHash = await computeNodeFileHash(stage1Artifact);
1357
- if (nodeHash?.hash) {
1358
- stage1ArtifactHash = nodeHash.hash;
1359
- stage1Artifact = nodeHash.absolutePath;
1360
- }
1361
- }
1362
-
1363
- return runUlStageTest('stage2_base', {
1364
- ...options,
1365
- stage1Artifact,
1366
- stage1ArtifactHash,
1367
- });
1368
- }
1369
-
1370
- async function runDistillStageTest(stage, options = {}) {
1371
- const distillTraining = buildDistillTrainingOverrides({
1372
- ...options,
1373
- trainingStage: stage,
1374
- });
1375
- const distillOutputDim = clampDistillTopK(distillTraining?.distill?.topK ?? DISTILL_ADAPTER_TOP_K);
1376
- const resolvedTrainingConfig = createTrainingConfig({
1377
- training: distillTraining || undefined,
1378
- }).training;
1379
- let fixture = null;
1380
- let distillRuntime = null;
1381
-
1382
- try {
1383
- const distillDatasetPath = resolveDistillDatasetPath(options, resolvedTrainingConfig);
1384
- if (!distillDatasetPath) {
1385
- throw new Error('Distill stage requires --distill-dataset-path (training.distill.datasetPath).');
1386
- }
1387
- const distillDataScope = resolveDistillDataScope(options, resolvedTrainingConfig);
1388
- const distillDatasetReport = await loadDistillDatasetFromJsonl(distillDatasetPath, distillDataScope);
1389
- distillRuntime = await createDistillRuntimeContext({
1390
- ...options,
1391
- trainingStage: stage,
1392
- }, resolvedTrainingConfig);
1393
- fixture = await createDistillStudentRuntimeModelFixture({
1394
- training: distillTraining || undefined,
1395
- }, {
1396
- outputDim: distillOutputDim,
1397
- distillRuntime,
1398
- });
1399
-
1400
- const runner = new TrainingRunner(fixture.config, {
1401
- optimizer: new AdamOptimizer(fixture.config),
1402
- crossEntropyLoss,
1403
- clipGradients,
1404
- });
1405
- const distillMaxSteps = Number.isInteger(options.trainingBenchSteps) && options.trainingBenchSteps > 0
1406
- ? options.trainingBenchSteps
1407
- : 2;
1408
- const dataset = distillDatasetReport.createDataset({
1409
- batchSize: 1,
1410
- shuffle: false,
1411
- seed: 1337,
1412
- distillRuntime,
1413
- });
1414
- const distillRunStartMs = performance.now();
1415
- const distillArtifactDir = normalizeOptionalString(options.distillArtifactDir)
1416
- || normalizeOptionalString(fixture.config.training?.distill?.artifactDir)
1417
- || 'reports/training/distill';
1418
- const metrics = await runner.run(fixture.model, dataset, {
1419
- epochs: 1,
1420
- batchSize: 1,
1421
- shuffle: false,
1422
- maxSteps: distillMaxSteps,
1423
- modelId: options.modelId || distillRuntime.studentModelId || 'training',
1424
- modelUrl: options.modelUrl || distillRuntime.studentModelUrl || null,
1425
- runtimeProfile: options.runtimeProfile || null,
1426
- trainingStage: stage,
1427
- command: options.command || null,
1428
- surface: options.surface || null,
1429
- forceResume: options.forceResume === true,
1430
- forceResumeReason: options.forceResumeReason || null,
1431
- forceResumeSource: options.forceResumeSource || null,
1432
- checkpointOperator: options.checkpointOperator || null,
1433
- checkpointEvery: options.checkpointEvery ?? null,
1434
- gpuAdapterInfo: getKernelCapabilities(),
1435
- timestamp: options.timestamp || null,
1436
- distillArtifactDir,
1437
- stageAArtifact: options.stageAArtifact || null,
1438
- stageAArtifactHash: options.stageAArtifactHash || null,
1439
- teacherModelId: distillRuntime.teacherModelId || null,
1440
- studentModelId: distillRuntime.studentModelId || null,
1441
- distillDatasetId: options.distillDatasetId || null,
1442
- distillDatasetPath: distillDatasetReport.absolutePath,
1443
- distillLanguagePair: options.distillLanguagePair || null,
1444
- distillSourceLangs: distillDataScope.sourceLangs || null,
1445
- distillTargetLangs: distillDataScope.targetLangs || null,
1446
- distillPairAllowlist: distillDataScope.pairAllowlist || null,
1447
- strictPairContract: distillDataScope.strictPairContract === true,
1448
- distillShardIndex: options.distillShardIndex ?? fixture.config.training?.distill?.shardIndex ?? null,
1449
- distillShardCount: options.distillShardCount ?? fixture.config.training?.distill?.shardCount ?? null,
1450
- resumeFrom: options.resumeFrom ?? fixture.config.training?.distill?.resumeFrom ?? null,
1451
- });
1452
- if (!Array.isArray(metrics) || metrics.length === 0) {
1453
- return { passed: false, error: `Distill ${stage} produced no metrics.` };
1454
- }
1455
- const requiredFields = stage === 'stage_a'
1456
- ? ['loss_kd', 'distill_stage']
1457
- : ['loss_triplet', 'distill_stage', 'distill_triplet_margin'];
1458
- for (const field of requiredFields) {
1459
- if (!(field in metrics[0])) {
1460
- return { passed: false, error: `Distill ${stage} missing metric field "${field}".` };
1461
- }
1462
- }
1463
- const artifact = runner.lastArtifact;
1464
- if (!artifact || !artifact.manifestPath) {
1465
- return { passed: false, error: `Distill ${stage} did not produce artifacts.` };
1466
- }
1467
- const progress = resolveBenchProgressSummary(
1468
- metrics,
1469
- resolveDistillShardProgressContext(
1470
- options,
1471
- fixture.config.training,
1472
- distillMaxSteps,
1473
- distillDatasetReport?.shardCount ?? null
1474
- ),
1475
- distillRunStartMs
1476
- );
1477
- return {
1478
- passed: true,
1479
- artifact: {
1480
- ...artifact,
1481
- resumeAudits: Array.isArray(runner.resumeState?.resumeAudits)
1482
- ? runner.resumeState.resumeAudits
1483
- : [],
1484
- },
1485
- metrics: {
1486
- stage,
1487
- steps: metrics.length,
1488
- progress,
1489
- manifestPath: artifact.manifestPath,
1490
- manifestHash: artifact.manifestHash,
1491
- manifestContentHash: artifact.manifestContentHash,
1492
- manifestFileHash: artifact.manifestFileHash ?? null,
1493
- distillResolvedConfig: {
1494
- enabled: fixture.config.training?.distill?.enabled === true,
1495
- stage: fixture.config.training?.distill?.stage ?? null,
1496
- teacherModelId: fixture.config.training?.distill?.teacherModelId ?? null,
1497
- studentModelId: fixture.config.training?.distill?.studentModelId ?? null,
1498
- datasetId: fixture.config.training?.distill?.datasetId ?? null,
1499
- datasetPath: fixture.config.training?.distill?.datasetPath ?? null,
1500
- languagePair: fixture.config.training?.distill?.languagePair ?? null,
1501
- sourceLangs: fixture.config.training?.distill?.sourceLangs ?? null,
1502
- targetLangs: fixture.config.training?.distill?.targetLangs ?? null,
1503
- pairAllowlist: fixture.config.training?.distill?.pairAllowlist ?? null,
1504
- strictPairContract: fixture.config.training?.distill?.strictPairContract === true,
1505
- shardIndex: fixture.config.training?.distill?.shardIndex ?? null,
1506
- shardCount: fixture.config.training?.distill?.shardCount ?? null,
1507
- resumeFrom: fixture.config.training?.distill?.resumeFrom ?? null,
1508
- temperature: fixture.config.training?.distill?.temperature ?? null,
1509
- alphaKd: fixture.config.training?.distill?.alphaKd ?? null,
1510
- alphaCe: fixture.config.training?.distill?.alphaCe ?? null,
1511
- tripletMargin: fixture.config.training?.distill?.tripletMargin ?? null,
1512
- studentGraphMode: fixture.config.training?.distill?.studentGraphMode ?? null,
1513
- topK: fixture.config.training?.distill?.topK ?? distillOutputDim,
1514
- freeze: fixture.config.training?.distill?.freeze ?? null,
1515
- },
1516
- distillRuntime: {
1517
- teacherModelId: distillRuntime.teacherModelId || null,
1518
- studentModelId: distillRuntime.studentModelId || null,
1519
- teacherModelUrl: distillRuntime.teacherModelUrl || null,
1520
- studentModelUrl: distillRuntime.studentModelUrl || null,
1521
- topK: distillRuntime.topK,
1522
- studentGraphMode: distillRuntime.studentGraphMode || null,
1523
- targetTokenMode: distillRuntime.targetTokenMode || null,
1524
- },
1525
- distillDataset: {
1526
- path: distillDatasetReport.absolutePath,
1527
- rowCount: distillDatasetReport.rowCount,
1528
- sampleCount: distillDatasetReport.sampleCount,
1529
- shardCount: distillDatasetReport.shardCount ?? 1,
1530
- directionCounts: distillDatasetReport.directionCounts,
1531
- dataScope: distillDatasetReport.dataScope || null,
1532
- },
1533
- checkpoint: runner.lastCheckpoint || null,
1534
- resumeAuditCount: Number.isInteger(runner.resumeState?.resumeAuditCount)
1535
- ? runner.resumeState.resumeAuditCount
1536
- : 0,
1537
- },
1538
- };
1539
- } finally {
1540
- if (distillRuntime && typeof distillRuntime.cleanup === 'function') {
1541
- await distillRuntime.cleanup();
1542
- }
1543
- if (fixture) {
1544
- fixture.cleanup();
1545
- }
1546
- }
1547
- }
1548
-
1549
- async function runDistillStageATest(options = {}) {
1550
- return runDistillStageTest('stage_a', options);
1551
- }
1552
-
1553
- async function runDistillStageBTest(options = {}) {
1554
- const explicitStageAArtifact = String(options.stageAArtifact || '').trim();
1555
- let stageAArtifact = explicitStageAArtifact || null;
1556
- let stageAArtifactHash = String(options.stageAArtifactHash || '').trim() || null;
1557
-
1558
- if (!stageAArtifact) {
1559
- const stageA = await runDistillStageATest({
1560
- ...options,
1561
- trainingStage: 'stage_a',
1562
- });
1563
- if (!stageA?.passed || !stageA?.artifact?.manifestPath) {
1564
- return { passed: false, error: 'Distill stage_b preflight failed to generate stage_a artifact.' };
1565
- }
1566
- stageAArtifact = stageA.artifact.manifestPath;
1567
- stageAArtifactHash = stageA.artifact.manifestHash;
1568
- const nodeHash = await computeNodeFileHash(stageAArtifact);
1569
- if (nodeHash?.hash) {
1570
- stageAArtifactHash = nodeHash.hash;
1571
- stageAArtifact = nodeHash.absolutePath;
1572
- }
1573
- }
1574
-
1575
- return runDistillStageTest('stage_b', {
1576
- ...options,
1577
- stageAArtifact,
1578
- stageAArtifactHash,
1579
- });
1580
- }
1581
-
1582
- function createLegacySkippedTest(name) {
1583
- return async () => ({
1584
- passed: true,
1585
- skipped: true,
1586
- error: `Legacy browser-only test "${name}" remains in tests/training/browser/test-page.js.`,
1587
- });
1588
- }
1589
-
1590
- const CORE_TESTS = Object.freeze({
1591
- 'runner-smoke': runRunnerSmokeTest,
1592
- 'train-step-metrics': runTrainStepMetricsTest,
1593
- 'ul-stage1': runUlStage1Test,
1594
- 'ul-stage2': runUlStage2Test,
1595
- 'distill-stage-a': runDistillStageATest,
1596
- 'distill-stage-b': runDistillStageBTest,
1597
- });
1598
-
1599
- const TESTS = Object.freeze({
1600
- ...CORE_TESTS,
1601
- ...Object.fromEntries(LEGACY_BROWSER_TESTS.map((name) => [name, createLegacySkippedTest(name)])),
1602
- });
1603
-
1604
- export const trainingHarness = Object.freeze({
1605
- async getGPU() {
1606
- await ensureTrainingGpuRuntime();
1607
- return true;
1608
- },
1609
- async runTest(name, options = {}) {
1610
- const fn = TESTS[name];
1611
- if (!fn) {
1612
- return { passed: false, error: `Unknown training test: ${name}` };
1613
- }
1614
- return fn(options);
1615
- },
1616
- listTests() {
1617
- return Object.keys(TESTS);
1618
- },
1619
- });
1620
-
1621
- export async function runTrainingSuite(options = {}) {
1622
- const trainingSchemaVersion = assertTrainingSchemaVersion(options.trainingSchemaVersion);
1623
- const adapterActivation = normalizeAdapterActivationConfig(options);
1624
- const startTime = performance.now();
1625
- await trainingHarness.getGPU();
1626
-
1627
- const availableTests = trainingHarness.listTests();
1628
- const requestedTestsFromOptions = normalizeTrainingTestNames(options.trainingTests);
1629
- const requestedStage = normalizeTrainingStage(options.trainingStage);
1630
- const stageDefaultTests = requestedStage === 'stage1_joint'
1631
- ? ['ul-stage1']
1632
- : (
1633
- requestedStage === 'stage2_base'
1634
- ? ['ul-stage2']
1635
- : (
1636
- requestedStage === 'stage_a'
1637
- ? ['distill-stage-a']
1638
- : (requestedStage === 'stage_b' ? ['distill-stage-b'] : null)
1639
- )
1640
- );
1641
- const requestedTests = requestedTestsFromOptions || stageDefaultTests;
1642
- if (requestedTests) {
1643
- const unknownTests = requestedTests.filter((name) => !availableTests.includes(name));
1644
- if (unknownTests.length > 0) {
1645
- throw new Error(`Unknown training test(s): ${unknownTests.join(', ')}`);
1646
- }
1647
- }
1648
- const testsToRun = requestedTests ?? availableTests;
1649
-
1650
- const results = [];
1651
- for (const testName of testsToRun) {
1652
- const testStart = performance.now();
1653
- try {
1654
- const outcome = await trainingHarness.runTest(testName, options);
1655
- const passed = outcome?.passed === true;
1656
- const skipped = outcome?.skipped === true;
1657
- const errorMessage = skipped
1658
- ? (outcome?.error ? String(outcome.error) : undefined)
1659
- : (passed ? undefined : String(outcome?.error || 'Training test failed'));
1660
- const entry = {
1661
- name: testName,
1662
- passed,
1663
- skipped,
1664
- duration: Math.max(0, performance.now() - testStart),
1665
- ...(errorMessage ? { error: errorMessage } : {}),
1666
- };
1667
- if (outcome?.metrics && typeof outcome.metrics === 'object') {
1668
- entry.metrics = outcome.metrics;
1669
- }
1670
- if (outcome?.artifact && typeof outcome.artifact === 'object') {
1671
- entry.artifact = outcome.artifact;
1672
- }
1673
- results.push(entry);
1674
- } catch (error) {
1675
- results.push({
1676
- name: testName,
1677
- passed: false,
1678
- duration: Math.max(0, performance.now() - testStart),
1679
- error: String(error?.message || error),
1680
- });
1681
- }
1682
- }
1683
-
1684
- const summary = buildSuiteSummary('training', results, startTime);
1685
- const adapterActivationResult = (
1686
- adapterActivation.enabled
1687
- && adapterActivation.autoActivate
1688
- )
1689
- ? await tryActivateAdapterPayload(adapterActivation.adapterPayload)
1690
- : null;
1691
- return {
1692
- ...summary,
1693
- modelId: options.modelId || options.modelUrl || 'training',
1694
- metrics: {
1695
- testsRun: results.length,
1696
- selectedTests: testsToRun,
1697
- availableTests,
1698
- trainingStage: requestedStage || null,
1699
- trainingSchemaVersion,
1700
- adapterActivation: adapterActivationResult,
1701
- },
1702
- deviceInfo: getKernelCapabilities(),
1703
- };
1704
- }
1705
-
1706
144
  function toPositiveInteger(value, fallback) {
1707
145
  const parsed = Number(value);
1708
146
  if (!Number.isFinite(parsed)) return fallback;
@@ -1710,98 +148,6 @@ function toPositiveInteger(value, fallback) {
1710
148
  return floored > 0 ? floored : fallback;
1711
149
  }
1712
150
 
1713
- function toPositiveIntegerOrNull(value) {
1714
- const parsed = Number(value);
1715
- if (!Number.isFinite(parsed)) return null;
1716
- const floored = Math.floor(parsed);
1717
- return floored > 0 ? floored : null;
1718
- }
1719
-
1720
- function resolveDistillShardProgressContext(
1721
- options = {},
1722
- trainingOverrides = null,
1723
- stepsPerShard = null,
1724
- fallbackShardCount = null
1725
- ) {
1726
- const distillConfig = trainingOverrides?.distill || {};
1727
- const shardIndexInput = toPositiveIntegerOrNull(
1728
- options.distillShardIndex ?? distillConfig.shardIndex ?? null
1729
- );
1730
- const shardCountInput = toPositiveIntegerOrNull(
1731
- options.distillShardCount ?? distillConfig.shardCount ?? null
1732
- );
1733
- const fallbackShardCountInput = toPositiveIntegerOrNull(fallbackShardCount);
1734
- if (
1735
- shardIndexInput !== null
1736
- && shardCountInput !== null
1737
- && shardIndexInput > shardCountInput
1738
- ) {
1739
- throw new Error('distillShardIndex must be <= distillShardCount.');
1740
- }
1741
- const shardCount = shardCountInput ?? fallbackShardCountInput ?? 1;
1742
- const shardIndex = shardIndexInput ?? 1;
1743
- const normalizedStepsPerShard = toPositiveIntegerOrNull(stepsPerShard);
1744
- const totalGlobalSteps = normalizedStepsPerShard
1745
- ? (normalizedStepsPerShard * shardCount)
1746
- : null;
1747
- return {
1748
- shardIndex: Math.min(Math.max(1, shardIndex), shardCount),
1749
- shardCount: Math.max(1, shardCount),
1750
- stepsPerShard: normalizedStepsPerShard,
1751
- totalGlobalSteps,
1752
- };
1753
- }
1754
-
1755
- function resolveBenchProgressSummary(stepEntries, context, startTimeMs) {
1756
- const entries = Array.isArray(stepEntries) ? stepEntries : [];
1757
- const lastEntry = entries.length > 0 ? entries[entries.length - 1] : null;
1758
- const shardIndex = context?.shardIndex ?? 1;
1759
- const shardCount = context?.shardCount ?? 1;
1760
- const stepsPerShard = context?.stepsPerShard ?? null;
1761
- const totalGlobalSteps = context?.totalGlobalSteps ?? null;
1762
- const fallbackGlobalStep = stepsPerShard
1763
- ? (((shardIndex - 1) * stepsPerShard) + Math.min(entries.length, stepsPerShard))
1764
- : null;
1765
- const completedGlobalSteps = Number.isFinite(lastEntry?.progress_global_step)
1766
- ? lastEntry.progress_global_step
1767
- : fallbackGlobalStep;
1768
- const resolvedTotalGlobalSteps = Number.isFinite(lastEntry?.progress_global_steps)
1769
- ? lastEntry.progress_global_steps
1770
- : totalGlobalSteps;
1771
- const percentComplete = Number.isFinite(lastEntry?.progress_percent_complete)
1772
- ? lastEntry.progress_percent_complete
1773
- : (
1774
- Number.isFinite(completedGlobalSteps)
1775
- && Number.isFinite(resolvedTotalGlobalSteps)
1776
- && resolvedTotalGlobalSteps > 0
1777
- ? Math.min(100, (completedGlobalSteps / resolvedTotalGlobalSteps) * 100)
1778
- : null
1779
- );
1780
- const etaMs = Number.isFinite(lastEntry?.progress_eta_ms)
1781
- ? Math.max(0, lastEntry.progress_eta_ms)
1782
- : (
1783
- Number.isFinite(percentComplete)
1784
- && percentComplete >= 100
1785
- ? 0
1786
- : null
1787
- );
1788
- const elapsedMs = Number.isFinite(lastEntry?.progress_elapsed_ms)
1789
- ? Math.max(0, lastEntry.progress_elapsed_ms)
1790
- : Math.max(0, performance.now() - startTimeMs);
1791
- return {
1792
- shardIndex,
1793
- shardCount,
1794
- stepsPerShard,
1795
- completedGlobalSteps: Number.isFinite(completedGlobalSteps) ? completedGlobalSteps : null,
1796
- totalGlobalSteps: Number.isFinite(resolvedTotalGlobalSteps) ? resolvedTotalGlobalSteps : null,
1797
- percentComplete,
1798
- etaMs,
1799
- etaIso: Number.isFinite(etaMs) ? new Date(Date.now() + etaMs).toISOString() : null,
1800
- elapsedMs,
1801
- updatedAt: new Date().toISOString(),
1802
- };
1803
- }
1804
-
1805
151
  function appendTimelineEvent(timeline, type, details = {}) {
1806
152
  timeline.push({
1807
153
  index: timeline.length + 1,