mlx-bun 0.2.0 → 0.4.0

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 (433) hide show
  1. package/README.md +71 -588
  2. package/docs/README.md +94 -0
  3. package/docs/{design → archive/investigations}/audio-input-plan.md +4 -4
  4. package/docs/{design → archive/investigations}/diffusion-gemma-port.md +3 -3
  5. package/docs/{design → archive/investigations}/faithful-l1-consolidation.md +4 -4
  6. package/docs/{design → archive/investigations}/minicpm5-decode-megakernel.md +11 -11
  7. package/docs/archive/investigations/openjarvis-fit.md +198 -0
  8. package/docs/{design → archive/investigations}/optimization_plan.md +1 -1
  9. package/docs/{design → archive/investigations}/pre-colibri-stabilization.md +5 -5
  10. package/docs/archive/investigations/qwen38-27b-campaign-log.md +1092 -0
  11. package/docs/{design → archive/investigations}/the-dreaming-handoff.md +2 -2
  12. package/docs/archive/planning/release-notes-v0.3.0.md +35 -0
  13. package/docs/design/batching.md +1841 -0
  14. package/docs/design/decode-speed-program.md +2346 -169
  15. package/docs/design/dreaming-nightly-pipeline.md +675 -282
  16. package/docs/design/generic-model-support.md +655 -334
  17. package/docs/design/kv-cache.md +824 -0
  18. package/docs/design/orpo-training.md +673 -1239
  19. package/docs/design/speculative-decoding.md +1990 -0
  20. package/docs/design/turboquant.md +2212 -0
  21. package/docs/design/unified-engine-frontier-plan.md +1833 -727
  22. package/docs/design/web-chat-redesign.md +666 -1083
  23. package/docs/planning/PRODUCT_ROADMAP.md +50 -1
  24. package/docs/planning/release-notes-v0.4.0.md +45 -0
  25. package/docs/planning/video-series.md +2 -2
  26. package/docs/reference/benchmarks.md +3613 -0
  27. package/docs/reference/cli.md +434 -160
  28. package/docs/reference/distribution.md +328 -182
  29. package/docs/reference/environment.md +398 -0
  30. package/docs/reference/glossary.md +39 -0
  31. package/docs/reference/library-api.md +566 -168
  32. package/docs/reference/memory.md +227 -64
  33. package/docs/reference/models.md +113 -6
  34. package/docs/reference/server-api.md +944 -429
  35. package/docs/reference/server-config.md +740 -338
  36. package/docs/reference/training.md +393 -254
  37. package/docs/reference/troubleshooting.md +158 -0
  38. package/package.json +9 -4
  39. package/src/audio/decode.ts +2 -2
  40. package/src/audio/features.ts +2 -2
  41. package/src/backends/mlx/assistant-target.ts +46 -0
  42. package/src/backends/mlx/autoregressive-draft-rows.ts +120 -0
  43. package/src/backends/mlx/autoregressive.ts +108 -0
  44. package/src/backends/mlx/batch-group.ts +1790 -0
  45. package/src/backends/mlx/cache-attachment.ts +67 -0
  46. package/src/backends/mlx/cache-layout.ts +31 -0
  47. package/src/backends/mlx/checkpoint-state.ts +53 -0
  48. package/src/backends/mlx/continuation-persistence.ts +106 -0
  49. package/src/backends/mlx/continuation-request.ts +43 -0
  50. package/src/backends/mlx/continuation.ts +77 -0
  51. package/src/backends/mlx/diffusion.ts +39 -0
  52. package/src/backends/mlx/draft-target.ts +32 -0
  53. package/src/backends/mlx/evaluation.ts +105 -0
  54. package/src/backends/mlx/fill-append.ts +45 -0
  55. package/src/backends/mlx/full-kv-row-append.ts +32 -0
  56. package/src/backends/mlx/full-kv-row-donor.ts +54 -0
  57. package/src/backends/mlx/full-transitioning-kv-rows.ts +65 -0
  58. package/src/backends/mlx/gateway-binding.ts +130 -0
  59. package/src/backends/mlx/graph.ts +38 -0
  60. package/src/backends/mlx/kv-codec.ts +9 -0
  61. package/src/backends/mlx/kv-maintenance.ts +133 -0
  62. package/src/backends/mlx/kv-tensor-rows.ts +212 -0
  63. package/src/backends/mlx/memory-client.ts +189 -0
  64. package/src/backends/mlx/methods.ts +90 -0
  65. package/src/backends/mlx/model-prompt.ts +164 -0
  66. package/src/backends/mlx/model-serving.ts +79 -0
  67. package/src/backends/mlx/prefill-cohort.ts +89 -0
  68. package/src/backends/mlx/prefill-rows.ts +200 -0
  69. package/src/backends/mlx/prefill.ts +33 -0
  70. package/src/backends/mlx/projected-context-rows.ts +72 -0
  71. package/src/backends/mlx/request-policy.ts +20 -0
  72. package/src/backends/mlx/request-state-policy.ts +41 -0
  73. package/src/backends/mlx/rollback.ts +89 -0
  74. package/src/backends/mlx/row-sampling.ts +49 -0
  75. package/src/backends/mlx/serial-executor.ts +242 -0
  76. package/src/backends/mlx/speculative-group.ts +359 -0
  77. package/src/backends/mlx/speculative-round.ts +161 -0
  78. package/src/backends/mlx/speculative.ts +114 -0
  79. package/src/backends/mlx/state-rows.ts +104 -0
  80. package/src/backends/mlx/state-views.ts +46 -0
  81. package/src/backends/mlx/target-layout-capability.ts +35 -0
  82. package/src/backends/mlx/text-engine.ts +73 -0
  83. package/src/backends/mlx/transitioning-kv-rows.ts +165 -0
  84. package/src/cli.ts +66 -58
  85. package/src/client.ts +66 -0
  86. package/src/config.ts +21 -4
  87. package/src/contracts/completion.ts +16 -0
  88. package/src/contracts/execution.ts +60 -0
  89. package/src/contracts/generation.ts +103 -0
  90. package/src/contracts/host.ts +7 -0
  91. package/src/contracts/jobs.ts +66 -0
  92. package/src/contracts/pi-provider.ts +30 -0
  93. package/src/contracts/pi.ts +259 -0
  94. package/src/contracts/prefix-cache.ts +23 -0
  95. package/src/contracts/resources.ts +25 -0
  96. package/src/contracts/sampling.ts +23 -0
  97. package/src/contracts/scheduling.ts +45 -0
  98. package/src/contracts/tsconfig.json +14 -0
  99. package/src/diffusion/diffusion-generate.ts +218 -153
  100. package/src/embed.ts +1 -1
  101. package/src/engine/admission.ts +59 -0
  102. package/src/engine/cancellation.ts +38 -0
  103. package/src/engine/engine.ts +56 -0
  104. package/src/engine/execution-coordinator.ts +70 -0
  105. package/src/engine/execution-plan.ts +53 -0
  106. package/src/engine/resources.ts +53 -0
  107. package/src/engine/scheduler.ts +72 -0
  108. package/src/engine/session.ts +247 -0
  109. package/src/eval/README.md +44 -1
  110. package/src/eval/kl.ts +236 -3
  111. package/src/eval/reference-logits.ts +207 -0
  112. package/src/eval/runner.ts +8 -96
  113. package/src/fill/echo-index.ts +188 -0
  114. package/src/fill/fill-session.ts +452 -0
  115. package/src/fill/proposal.ts +68 -0
  116. package/src/fill/schema-rows.ts +506 -0
  117. package/src/fill/tool-boundary.ts +103 -0
  118. package/src/fit.ts +30 -16
  119. package/src/generate.ts +709 -417
  120. package/src/grammar.ts +12 -7
  121. package/src/harness-pi.ts +14 -33
  122. package/src/hub-rest.ts +4 -4
  123. package/src/index.ts +7 -0
  124. package/src/inference/denoising.ts +17 -0
  125. package/src/inference/draft-acceptance.ts +41 -0
  126. package/src/inference/draft-output.ts +49 -0
  127. package/src/inference/graph.ts +33 -0
  128. package/src/inference/prefill.ts +39 -0
  129. package/src/inference/rollback.ts +7 -0
  130. package/src/jobs/db.ts +4 -0
  131. package/src/jobs/index.ts +2 -0
  132. package/src/jobs/job-entry.ts +12 -12
  133. package/src/jobs/runner.ts +98 -13
  134. package/src/jobs/task-client.ts +19 -0
  135. package/src/jobs/types.ts +2 -58
  136. package/src/kv-scheme.ts +70 -12
  137. package/src/kv-store.ts +177 -63
  138. package/src/lab/README.md +18 -0
  139. package/src/{assets → lab/curve}/curve-designer.html +2 -2
  140. package/src/{curve-sampler.ts → lab/curve/curve-sampler.ts} +2 -2
  141. package/src/{expert-trace.ts → lab/expert-trace/expert-trace.ts} +5 -5
  142. package/src/lab/paged-kv/paged-kv-rows.ts +83 -0
  143. package/src/{model → lab/paged-kv}/paged-kv.ts +32 -15
  144. package/src/library.ts +40 -0
  145. package/src/lora.ts +18 -0
  146. package/src/media-fetch.ts +1 -1
  147. package/src/memory/article.ts +1 -1
  148. package/src/memory/chunk.ts +1 -1
  149. package/src/memory/model.ts +30 -169
  150. package/src/memory/prompts.ts +1 -1
  151. package/src/memory/rest.ts +1 -1
  152. package/src/memory/schedule.ts +1 -1
  153. package/src/memory/stages.ts +4 -1
  154. package/src/memory/vault.ts +1 -3
  155. package/src/mlx/array.ts +11 -11
  156. package/src/mlx/compile.ts +12 -2
  157. package/src/mlx/ffi.ts +58 -11
  158. package/src/mlx/materialize.ts +23 -0
  159. package/src/mlx/metal-kernel.ts +10 -11
  160. package/src/mlx/ops.ts +33 -13
  161. package/src/mlx/quantized-rows.ts +36 -0
  162. package/src/mlx/token-bitmask.ts +52 -0
  163. package/src/mlx/turboquant-kv-decode.ts +82 -0
  164. package/src/mlx/turboquant-kv-inverse.ts +122 -0
  165. package/src/mlx/turboquant-ops.ts +33 -3
  166. package/src/mlx/turboquant-tables.ts +2 -2
  167. package/src/model/artifact-identity.ts +73 -0
  168. package/src/model/batched-kv.ts +235 -0
  169. package/src/model/batched-mask.ts +20 -6
  170. package/src/model/batched-quant.ts +9 -3
  171. package/src/model/batched-quantized-kv.ts +144 -0
  172. package/src/model/batched-rotating-quant.ts +78 -17
  173. package/src/model/batched-rotating-state.ts +76 -0
  174. package/src/model/batched-rotating.ts +65 -23
  175. package/src/model/batched-row-storage.ts +52 -0
  176. package/src/model/batched-ssm.ts +52 -0
  177. package/src/model/batched-turboquant-kv.ts +93 -0
  178. package/src/model/compiled-decode.ts +8 -2
  179. package/src/model/decoded-kv-donor.ts +12 -0
  180. package/src/model/delayed-quantized-kv.ts +72 -0
  181. package/src/model/delayed-rotating-quantized-kv.ts +93 -0
  182. package/src/model/delayed-turboquant-kv.ts +55 -0
  183. package/src/model/diffusion-gemma.ts +8 -8
  184. package/src/model/factory.ts +76 -33
  185. package/src/model/fingerprint.ts +1 -1
  186. package/src/model/flash-attention.ts +3 -3
  187. package/src/model/full-prefill-padding.ts +56 -0
  188. package/src/model/full-prefill-row.ts +105 -0
  189. package/src/model/gemma4-base.ts +179 -80
  190. package/src/model/gemma4.ts +40 -32
  191. package/src/model/generated/gemma4-12b.ts +6 -3
  192. package/src/model/generated/gemma4-26b.ts +6 -3
  193. package/src/model/generated/gemma4-e4b.ts +6 -3
  194. package/src/model/glm52-cache.ts +80 -4
  195. package/src/model/glm52-dsa.ts +13 -9
  196. package/src/model/glm52-memory.ts +1 -1
  197. package/src/model/glm52-mla.ts +12 -6
  198. package/src/model/glm52.ts +19 -40
  199. package/src/model/implementation.ts +69 -0
  200. package/src/model/kv-attention-view.ts +67 -0
  201. package/src/model/minicpm5.ts +17 -15
  202. package/src/model/profile.ts +12 -2
  203. package/src/model/qwen-append.ts +12 -0
  204. package/src/model/qwen-conv.ts +52 -0
  205. package/src/model/qwen3-delta-state.ts +74 -0
  206. package/src/model/qwen3-delta.ts +59 -36
  207. package/src/model/qwen3_5-checkpoint.ts +164 -0
  208. package/src/model/qwen3_5.ts +202 -78
  209. package/src/model/rotating-kv-donor.ts +35 -0
  210. package/src/model/rotating-kv-layout.ts +262 -0
  211. package/src/model/rotating-row-transaction.ts +35 -0
  212. package/src/model/speculative-rotating-kv.ts +101 -0
  213. package/src/model/ssm-prefill-padding.ts +39 -0
  214. package/src/model/support.ts +1 -1
  215. package/src/model/trellis-balanced-scatter.ts +51 -0
  216. package/src/model/trellis-linear.ts +672 -0
  217. package/src/model/trellis-shared-m.ts +151 -0
  218. package/src/model/trellis-shared-scatter.ts +144 -0
  219. package/src/model/trellis-splitk-prefill.ts +158 -0
  220. package/src/model/trellis-tiled-prefill.ts +136 -0
  221. package/src/model/trellis-vector-expand.ts +62 -0
  222. package/src/model/trellis-wide-prefill.ts +94 -0
  223. package/src/model/turboquant-codec.ts +83 -0
  224. package/src/model/universal/dense.ts +15 -14
  225. package/src/model/universal/modules.ts +8 -1
  226. package/src/native-pack.ts +6 -5
  227. package/src/pi-provider.ts +6 -64
  228. package/src/pi-web.ts +8 -315
  229. package/src/preflight.ts +31 -15
  230. package/src/prompt-cache.ts +110 -69
  231. package/src/quantize/allocator.ts +1 -1
  232. package/src/quantize/config-writer.ts +10 -3
  233. package/src/quantize/rotate.ts +4 -4
  234. package/src/quantize/trellis.ts +586 -0
  235. package/src/responses.ts +28 -1
  236. package/src/runtime-config.ts +18 -4
  237. package/src/sampler.ts +40 -29
  238. package/src/serve/batch-scheduler.ts +8 -1671
  239. package/src/serve/chat-request.ts +391 -0
  240. package/src/serve/chat-stage.ts +195 -0
  241. package/src/serve/checkpoint-identity.ts +64 -0
  242. package/src/serve/completion-executor.ts +15 -7
  243. package/src/serve/discovery-routes.ts +12 -13
  244. package/src/serve/generation-gateway.ts +183 -213
  245. package/src/serve/http.ts +159 -0
  246. package/src/serve/inference-request.ts +79 -0
  247. package/src/serve/isolate.ts +297 -105
  248. package/src/serve/lab-routes.ts +3 -0
  249. package/src/serve/lane-registry.ts +2 -1
  250. package/src/serve/model-admin-routes.ts +7 -5
  251. package/src/serve/model-binding.ts +43 -0
  252. package/src/serve/model-host.ts +511 -0
  253. package/src/serve/openai-wire.ts +103 -0
  254. package/src/serve/parent-application.ts +56 -0
  255. package/src/serve/pipeline.ts +33 -0
  256. package/src/serve/preparation.ts +33 -0
  257. package/src/serve/request-plan.ts +23 -18
  258. package/src/serve/request-prep.ts +344 -0
  259. package/src/serve/response-lease.ts +24 -0
  260. package/src/serve/responses-client.ts +69 -0
  261. package/src/serve/session-completion-engine.ts +110 -0
  262. package/src/serve/session-search.ts +1 -1
  263. package/src/serve/static-routes.ts +5 -5
  264. package/src/serve/text-completion-stage.ts +104 -0
  265. package/src/serve/token-streams.ts +519 -0
  266. package/src/server.ts +335 -2711
  267. package/src/spec/assistant-rows.ts +92 -0
  268. package/src/spec/assistant-source.ts +31 -55
  269. package/src/spec/cache-identity.ts +22 -0
  270. package/src/spec/deepspec-rows.ts +29 -0
  271. package/src/spec/deepspec-source.ts +16 -14
  272. package/src/spec/dflash-source.ts +36 -12
  273. package/src/spec/drafter.ts +153 -142
  274. package/src/spec/dspark/ab-stats.ts +3 -3
  275. package/src/spec/dspark/calibration.ts +2 -2
  276. package/src/spec/dspark/deepspec-module.ts +97 -122
  277. package/src/spec/dspark/generate-dflash.ts +2 -2
  278. package/src/spec/dspark/generate.ts +2 -2
  279. package/src/spec/dspark/loader.ts +1 -1
  280. package/src/spec/dspark/module-dflash.ts +129 -172
  281. package/src/spec/dspark/module.ts +3 -3
  282. package/src/spec/dspark/quantize-drafter.ts +1 -1
  283. package/src/spec/generate.ts +1 -1
  284. package/src/spec/glm52-mtp-graph.ts +29 -0
  285. package/src/spec/glm52-mtp-rows.ts +132 -0
  286. package/src/spec/glm52-mtp-source.ts +54 -137
  287. package/src/spec/glm52-mtp-state.ts +33 -0
  288. package/src/spec/ngram-source.ts +93 -21
  289. package/src/spec/projected-draft-rows.ts +73 -0
  290. package/src/spec/qwen-mtp-module.ts +171 -0
  291. package/src/spec/qwen-mtp-rows.ts +219 -0
  292. package/src/spec/qwen-mtp-source.ts +147 -195
  293. package/src/spec/qwen-mtp-state.ts +30 -0
  294. package/src/spec/serve-loop.ts +201 -201
  295. package/src/spec/source.ts +110 -13
  296. package/src/spec/two-model-rows.ts +61 -0
  297. package/src/spec/two-model.ts +44 -102
  298. package/src/ssd-cache.ts +99 -19
  299. package/src/ssd-durability.ts +36 -20
  300. package/src/tool-call.ts +51 -14
  301. package/src/train/flash-cce.ts +2 -2
  302. package/src/train/forward.ts +6 -0
  303. package/src/train/loss.ts +1 -1
  304. package/src/train/prefix-shared.ts +5 -1
  305. package/src/train/segmented.ts +5 -3
  306. package/src/train/trainer.ts +6 -6
  307. package/src/vision/prompt.ts +1 -1
  308. package/src/vision/qwen3vl-tower.ts +52 -10
  309. package/src/web/app.html +1 -1
  310. package/src/web/app.js +62 -60
  311. package/src/web/src/adapters-panel.ts +3 -3
  312. package/src/web/src/assistant.ts +2 -36
  313. package/src/web/src/chat.ts +4 -4
  314. package/src/web/src/composer.ts +4 -4
  315. package/src/web/src/hub.ts +1 -1
  316. package/src/web/src/markdown.ts +0 -0
  317. package/src/web/src/memory-panel.ts +1 -1
  318. package/src/web/src/model-picker.ts +1 -1
  319. package/src/web/src/palette.ts +1 -1
  320. package/src/web/src/protocol.ts +3 -39
  321. package/src/web/src/sessions.ts +1 -1
  322. package/src/web/src/ui-catalog.ts +4 -18
  323. package/src/web-assets.ts +47 -0
  324. package/src/weights.ts +55 -9
  325. package/docs/archive/investigations/curve-runs/bisector-route.json +0 -98
  326. package/docs/archive/investigations/curve-runs/bisector-trace.json +0 -1393
  327. package/docs/archive/investigations/curve-runs/curve-terrain.json +0 -1179
  328. package/docs/archive/investigations/curve-runs/curve-terrain.svg +0 -42
  329. package/docs/archive/investigations/hlg-ab.html +0 -34
  330. package/docs/archive/investigations/hlg-explorer.html +0 -238
  331. package/docs/archive/investigations/hlg-figs/cliff.svg +0 -1
  332. package/docs/archive/investigations/hlg-figs/cross.svg +0 -1
  333. package/docs/archive/investigations/hlg-figs/edges.svg +0 -1
  334. package/docs/archive/investigations/hlg-figs/k20-grids.svg +0 -1
  335. package/docs/archive/investigations/hlg-figs/k20-peaks.svg +0 -1
  336. package/docs/archive/investigations/hlg-figs/lw-curve.svg +0 -1
  337. package/docs/archive/investigations/hlg-figs/terrain.svg +0 -1
  338. package/docs/archive/investigations/hlg-report.html +0 -262
  339. package/docs/archive/investigations/hlg-runs/hlg-ab.json +0 -149
  340. package/docs/archive/investigations/hlg-runs/hlg-blind-prompts.md +0 -87
  341. package/docs/archive/investigations/hlg-runs/hlg-blind.json +0 -107
  342. package/docs/archive/investigations/hlg-runs/hlg-cliff.json +0 -197
  343. package/docs/archive/investigations/hlg-runs/hlg-cross.json +0 -505
  344. package/docs/archive/investigations/hlg-runs/hlg-edge.json +0 -388
  345. package/docs/archive/investigations/hlg-runs/hlg-eval1.json +0 -25
  346. package/docs/archive/investigations/hlg-runs/hlg-frontier.json +0 -86
  347. package/docs/archive/investigations/hlg-runs/hlg-grid.json +0 -242
  348. package/docs/archive/investigations/hlg-runs/hlg-grid2.json +0 -343
  349. package/docs/archive/investigations/hlg-runs/hlg-lw-coarse.json +0 -110
  350. package/docs/archive/investigations/hlg-runs/hlg-map.json +0 -383
  351. package/docs/archive/investigations/hlg-runs/run0-original.log +0 -159
  352. package/docs/archive/investigations/hlg-runs/runA-recommended.log +0 -131
  353. package/docs/archive/investigations/hlg-runs/runAA-cliff-cpm5.log +0 -26
  354. package/docs/archive/investigations/hlg-runs/runAB-grid2-e4b.log +0 -18
  355. package/docs/archive/investigations/hlg-runs/runAC-peak-e4b-partial.log +0 -25
  356. package/docs/archive/investigations/hlg-runs/runAD-ab-samples.log +0 -8
  357. package/docs/archive/investigations/hlg-runs/runAE-edge-e4b.log +0 -51
  358. package/docs/archive/investigations/hlg-runs/runAF-logit-calibration.log +0 -10
  359. package/docs/archive/investigations/hlg-runs/runAG-eval-config2.log +0 -16
  360. package/docs/archive/investigations/hlg-runs/runB-gain-variants.log +0 -192
  361. package/docs/archive/investigations/hlg-runs/runC-pivots.log +0 -162
  362. package/docs/archive/investigations/hlg-runs/runD-oetf.log +0 -132
  363. package/docs/archive/investigations/hlg-runs/runE-eotf.log +0 -162
  364. package/docs/archive/investigations/hlg-runs/runF-shaper-working.log +0 -86
  365. package/docs/archive/investigations/hlg-runs/runG-shaper-sweep.log +0 -101
  366. package/docs/archive/investigations/hlg-runs/runH-wsweep.log +0 -176
  367. package/docs/archive/investigations/hlg-runs/runI-asweep.log +0 -176
  368. package/docs/archive/investigations/hlg-runs/runJ-knobmap.log +0 -49
  369. package/docs/archive/investigations/hlg-runs/runK-frontier.log +0 -19
  370. package/docs/archive/investigations/hlg-runs/runL-widemap.log +0 -65
  371. package/docs/archive/investigations/hlg-runs/runM-frontier-emb.log +0 -15
  372. package/docs/archive/investigations/hlg-runs/runN-verify.log +0 -116
  373. package/docs/archive/investigations/hlg-runs/runO-frontier-seed5000.log +0 -15
  374. package/docs/archive/investigations/hlg-runs/runP-grid-AxSm.log +0 -15
  375. package/docs/archive/investigations/hlg-runs/runQ-grid-tgW.log +0 -15
  376. package/docs/archive/investigations/hlg-runs/runR-blind-transcript.log +0 -79
  377. package/docs/archive/investigations/hlg-runs/runS-cross-coherence.log +0 -33
  378. package/docs/archive/investigations/hlg-runs/runT-cross-cpm5.log +0 -33
  379. package/docs/archive/investigations/hlg-runs/runU-cross-12b.log +0 -33
  380. package/docs/archive/investigations/hlg-runs/runV-lw-e4b.log +0 -22
  381. package/docs/archive/investigations/hlg-runs/runW-lw-12b.log +0 -22
  382. package/docs/archive/investigations/hlg-runs/runX-lw-cpm5.log +0 -22
  383. package/docs/archive/investigations/hlg-runs/runY-cliff-e4b.log +0 -26
  384. package/docs/archive/investigations/hlg-runs/runZ-cliff-12b.log +0 -26
  385. package/docs/archive/mlx-bun-lab-report.html +0 -275
  386. package/docs/archive/wwdc-mlx-bun.html +0 -848
  387. package/docs/design/adapters-end-to-end.md +0 -205
  388. package/docs/design/batching-perf-path.md +0 -255
  389. package/docs/design/batching-v2-plan.md +0 -529
  390. package/docs/design/bucketing-stage.md +0 -197
  391. package/docs/design/compat-cli-surface-design.md +0 -230
  392. package/docs/design/docs-reorg-plan.md +0 -165
  393. package/docs/design/dspark-serving-program.md +0 -371
  394. package/docs/design/dspark-speculative-decoding.md +0 -318
  395. package/docs/design/grammar-spec-batching-integration.md +0 -301
  396. package/docs/design/memory-inference-path.md +0 -422
  397. package/docs/design/memory-synthesis.md +0 -287
  398. package/docs/design/memory-system.md +0 -237
  399. package/docs/design/mlx-lm-serving-execution-seam.md +0 -81
  400. package/docs/design/mlx-lm-tool-parity-plan.md +0 -545
  401. package/docs/design/omlx-adoption-map.md +0 -98
  402. package/docs/design/orpo-dynamic-lambda.md +0 -220
  403. package/docs/design/orpo-future-enhancements.md +0 -340
  404. package/docs/design/paged-kv-cache.md +0 -214
  405. package/docs/design/parallel-slots.md +0 -567
  406. package/docs/design/parity-tier-dag.md +0 -161
  407. package/docs/design/repo-cleanup-plan.md +0 -231
  408. package/docs/design/runtime-isolation.md +0 -263
  409. package/docs/design/segmented-backward-training.md +0 -543
  410. package/docs/design/spec-decode-larger-targets.md +0 -229
  411. package/docs/design/ssd-kv-cold-tier.md +0 -415
  412. package/docs/design/structured-output.md +0 -484
  413. package/docs/design/tauri-desktop-app.md +0 -127
  414. package/docs/design/the-dreaming-master-plan.md +0 -445
  415. package/docs/design/turboquant-kv.md +0 -235
  416. package/docs/design/turboquant-weights.md +0 -467
  417. package/docs/design/w4a16-compute-precision-spike.md +0 -232
  418. package/docs/design/web-chat-beat-matrix.md +0 -315
  419. package/docs/design/write-pipeline-entity.md +0 -468
  420. package/docs/planning/IDEAS.md +0 -69
  421. package/docs/reference/embedding.md +0 -197
  422. package/docs/reference/features-matrix.md +0 -101
  423. package/docs/reference/orpo-quickstart.md +0 -135
  424. package/src/flags.ts +0 -11
  425. /package/docs/{design → archive/investigations}/colibri-glm52-port.md +0 -0
  426. /package/docs/{planning → archive/planning}/chunk-task-roadmap.md +0 -0
  427. /package/docs/{planning → archive/planning}/curve-sampler-research-plan.md +0 -0
  428. /package/docs/{planning → archive/planning}/memory-docs-and-dag-plan.md +0 -0
  429. /package/docs/{planning → archive/planning}/pi-integration-review.md +0 -0
  430. /package/docs/{planning → archive/planning}/release-notes-v0.2.0.md +0 -0
  431. /package/src/{memory-plan.ts → admission-plan.ts} +0 -0
  432. /package/{docs/archive/investigations → src/serve/assets}/curve-terrain.html +0 -0
  433. /package/{docs/dag → src/serve/assets}/training-inference-map.html +0 -0
package/docs/archive/mlx-bun-lab-report.html DELETED
@@ -1,275 +0,0 @@
1
- <!doctype html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="utf-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1">
6
- <title>mlx-bun Lab — build report</title>
7
- <style>
8
- :root{
9
- --bg:#000; --ink:#f5f5f7; --dim:#a1a1a6; --dimmer:#6e6e73;
10
- --hairline:rgba(255,255,255,.13); --card:rgba(255,255,255,.045);
11
- --card2:rgba(255,255,255,.07);
12
- --blue:#0a84ff; --cyan:#64d2ff; --indigo:#5e5ce6; --purple:#bf5af2;
13
- --pink:#ff375f; --orange:#ff9f0a; --yellow:#ffd60a; --green:#30d158; --red:#ff453a;
14
- --ease:cubic-bezier(.22,.61,.21,1);
15
- --mono:ui-monospace,"SF Mono",Menlo,monospace;
16
- }
17
- *{box-sizing:border-box;margin:0;padding:0}
18
- html{scroll-behavior:smooth}
19
- body{background:var(--bg);color:var(--ink);
20
- font:16px/1.65 -apple-system,"SF Pro Text",system-ui,sans-serif;
21
- -webkit-font-smoothing:antialiased;overflow-x:hidden}
22
- .bloom{position:fixed;border-radius:50%;filter:blur(120px);opacity:.5;z-index:-1;pointer-events:none}
23
- .b1{width:560px;height:560px;background:radial-gradient(circle,rgba(94,92,230,.5),transparent 70%);top:-160px;left:-120px}
24
- .b2{width:620px;height:620px;background:radial-gradient(circle,rgba(255,55,95,.32),transparent 70%);top:380px;right:-200px}
25
- .b3{width:680px;height:680px;background:radial-gradient(circle,rgba(48,209,88,.22),transparent 70%);top:1500px;left:-220px}
26
- .wrap{max-width:1000px;margin:0 auto;padding:0 24px}
27
- .grad{background-clip:text;-webkit-background-clip:text;color:transparent}
28
- .g-hero{background-image:linear-gradient(96deg,var(--orange),var(--pink) 34%,var(--purple) 64%,var(--blue))}
29
- .g-green{background-image:linear-gradient(96deg,var(--green),var(--cyan))}
30
- .g-pink{background-image:linear-gradient(96deg,var(--pink),var(--purple))}
31
- .g-blue{background-image:linear-gradient(96deg,var(--cyan),var(--blue))}
32
-
33
- header.hero{padding:120px 0 70px;text-align:center}
34
- .eyebrow{font:600 13px var(--mono);letter-spacing:.18em;text-transform:uppercase;color:var(--dim)}
35
- h1{font:800 clamp(40px,7vw,76px)/1.04 "SF Pro Display",-apple-system,sans-serif;letter-spacing:-.03em;margin:18px 0}
36
- .lede{font-size:clamp(17px,2.2vw,21px);color:var(--dim);max-width:720px;margin:0 auto;line-height:1.5}
37
- .meta{margin-top:26px;font:13px var(--mono);color:var(--dimmer)}
38
-
39
- section{padding:54px 0;border-top:1px solid var(--hairline)}
40
- h2{font:700 clamp(26px,3.6vw,38px)/1.1 "SF Pro Display",sans-serif;letter-spacing:-.02em;margin-bottom:8px}
41
- h2 + .sub{color:var(--dim);margin-bottom:30px;font-size:16px;max-width:760px}
42
- h3{font:650 19px "SF Pro Display",sans-serif;letter-spacing:-.01em;margin-bottom:6px}
43
-
44
- .stats{display:grid;grid-template-columns:repeat(4,1fr);gap:14px;margin-top:38px}
45
- .stat{background:var(--card);border:1px solid var(--hairline);border-radius:16px;padding:20px}
46
- .stat .n{font:800 30px "SF Pro Display",sans-serif;letter-spacing:-.02em}
47
- .stat .l{font-size:12.5px;color:var(--dim);margin-top:3px;line-height:1.35}
48
-
49
- .cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:16px}
50
- .card{background:var(--card);border:1px solid var(--hairline);border-radius:18px;padding:24px;transition:border-color .3s var(--ease),transform .3s var(--ease)}
51
- .card:hover{border-color:rgba(255,255,255,.28);transform:translateY(-2px)}
52
- .card .ic{font-size:22px;margin-bottom:12px}
53
- .card p{color:var(--dim);font-size:14.5px;margin-top:6px}
54
- .tag{display:inline-block;font:600 11px var(--mono);color:var(--green);background:rgba(48,209,88,.12);
55
- border:1px solid rgba(48,209,88,.3);border-radius:999px;padding:2px 9px;margin-top:12px}
56
- .tag.warn{color:var(--orange);background:rgba(255,159,10,.12);border-color:rgba(255,159,10,.3)}
57
-
58
- .flow{font:13px var(--mono);color:var(--dim);background:#0b0b0d;border:1px solid var(--hairline);
59
- border-radius:16px;padding:22px;white-space:pre;overflow-x:auto;line-height:1.6}
60
- .flow b{color:var(--ink)} .flow .k{color:var(--cyan)} .flow .g{color:var(--green)} .flow .p{color:var(--purple)}
61
-
62
- table{width:100%;border-collapse:collapse;font-size:14px;margin-top:6px}
63
- th,td{text-align:left;padding:11px 12px;border-bottom:1px solid var(--hairline);vertical-align:top}
64
- th{font:600 12px var(--mono);letter-spacing:.04em;text-transform:uppercase;color:var(--dim)}
65
- td code,.mono{font:12.5px var(--mono);color:var(--cyan)}
66
- td .ok{color:var(--green);font-weight:600}
67
- tr:last-child td{border-bottom:none}
68
-
69
- .showcase{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin-top:20px}
70
- .term{background:#0b0b0d;border:1px solid var(--hairline);border-radius:16px;overflow:hidden}
71
- .term .bar{display:flex;gap:7px;padding:12px 16px;border-bottom:1px solid var(--hairline);align-items:center}
72
- .term .bar i{width:11px;height:11px;border-radius:50%;display:inline-block}
73
- .term .bar .t{margin-left:8px;font:12px var(--mono);color:var(--dimmer)}
74
- .term .body{padding:18px;font:13.5px/1.6 var(--mono);color:var(--ink);white-space:pre-wrap;word-break:break-word;min-height:96px}
75
- .lbl{font:600 12px var(--mono);letter-spacing:.05em;text-transform:uppercase;margin-bottom:8px}
76
-
77
- .loss{background:var(--card);border:1px solid var(--hairline);border-radius:16px;padding:22px;margin-top:18px}
78
- ul.j{list-style:none;margin-top:8px}
79
- ul.j li{padding:14px 0;border-bottom:1px solid var(--hairline);display:flex;gap:14px}
80
- ul.j li:last-child{border-bottom:none}
81
- ul.j .b{flex:0 0 auto;width:30px;height:30px;border-radius:9px;display:grid;place-items:center;font-size:15px;
82
- background:var(--card2);border:1px solid var(--hairline)}
83
- ul.j .c h4{font:650 15.5px "SF Pro Display",sans-serif;margin-bottom:3px}
84
- ul.j .c p{color:var(--dim);font-size:14px}
85
- ul.j .c code{font:12px var(--mono);color:var(--cyan)}
86
- .note{color:var(--dimmer);font-size:13px;margin-top:18px;line-height:1.55}
87
- code.cmd{display:block;background:#0b0b0d;border:1px solid var(--hairline);border-radius:12px;
88
- padding:14px 16px;font:13px var(--mono);color:var(--green);margin-top:10px;overflow-x:auto;white-space:pre}
89
- footer{padding:60px 0 90px;text-align:center;color:var(--dimmer);font-size:13px;border-top:1px solid var(--hairline)}
90
- @media(max-width:760px){.stats{grid-template-columns:repeat(2,1fr)}.showcase{grid-template-columns:1fr}}
91
- </style>
92
- </head>
93
- <body>
94
- <div class="bloom b1"></div><div class="bloom b2"></div><div class="bloom b3"></div>
95
-
96
- <header class="hero"><div class="wrap">
97
- <div class="eyebrow">build report · branch web-ui-and-native-lab</div>
98
- <h1>mlx-bun <span class="grad g-hero">Lab</span></h1>
99
- <p class="lede">A complete, beautiful web workbench for local AI on Apple silicon —
100
- a full pi agent in the browser, plus <b>native</b> Quantize, Fine-tune, and
101
- Build-Dataset. No Python anywhere. Every engine is mlx-c through bun:ffi.</p>
102
- <p class="meta">M4 Pro · 24 GB · MiniCPM5-1B-OptiQ-4bit · 2026-06-14</p>
103
- <div class="stats">
104
- <div class="stat"><div class="n grad g-blue">5</div><div class="l">unified sections: Chat · Quantize · Fine-tune · Dataset · Status</div></div>
105
- <div class="stat"><div class="n grad g-green">0</div><div class="l">lines of Python — native quantize &amp; LoRA training via mlx-c</div></div>
106
- <div class="stat"><div class="n grad g-pink">150+</div><div class="l">new tests, all green (incl. real-model e2e)</div></div>
107
- <div class="stat"><div class="n grad g-hero">50+</div><div class="l">new source files across 11 subsystems</div></div>
108
- </div>
109
- </div></header>
110
-
111
- <section><div class="wrap">
112
- <h2>What shipped</h2>
113
- <p class="sub">One self-contained, keynote-styled SPA served from the same binary, backed by four new engines and a shared job system. The status page is kept and folded in.</p>
114
- <div class="cards">
115
- <div class="card"><div class="ic">💬</div><h3>Chat</h3><p>The full pi coding-agent embedded server-side, streamed to the browser over WebSocket: live tokens, tool calls (read/bash/edit/write/grep/find/ls), steering, and a real pre-execution approval gate for the dangerous tools.</p><span class="tag">pi SDK · verified streaming + tools</span></div>
116
- <div class="card"><div class="ic">🧮</div><h3>Quantize</h3><p>Reads a model, quantizes every eligible Linear + embedding via <span class="mono">mlx_quantize</span>, writes a real HF-layout 4/8-bit model dir with <span class="mono">mlx_save_safetensors</span> the existing loader serves unchanged.</p><span class="tag">native · 170 modules → 4.50 bpw</span></div>
117
- <div class="card"><div class="ic">🎛️</div><h3>Fine-tune</h3><p>Native LoRA + DPO. <span class="mono">mlx_value_and_grad</span> driven by a bun:ffi closure, hand-rolled AdamW, masked cross-entropy. Saves an adapter the server hot-mounts.</p><span class="tag">native · loss 4.48 → 0.68</span></div>
118
- <div class="card"><div class="ic">📦</div><h3>Build Dataset</h3><p>All 13 OptIQ-Lab templates ported to TypeScript — pure-data ones run locally, LLM-driven ones call the server's own loopback. Splits to train/valid JSONL.</p><span class="tag">13 templates · 90/10 split</span></div>
119
- <div class="card"><div class="ic">📊</div><h3>Status</h3><p>The existing keynote dashboard, kept and integrated: live memory meters, prompt-cache hit rate, KV-quant split, the fit solver + Apple-silicon SKU matrix, downloads.</p><span class="tag">kept &amp; unified</span></div>
120
- <div class="card"><div class="ic">⚙️</div><h3>Job system</h3><p>Shared SQLite-backed jobs with NDJSON-log SSE streaming. GPU jobs run as crash-isolated subprocesses (uncatchable Metal OOM can't take the server down); dataset jobs run in-process.</p><span class="tag">SSE · crash-isolated</span></div>
121
- </div>
122
- </div></section>
123
-
124
- <section><div class="wrap">
125
- <h2>Architecture</h2>
126
- <p class="sub">Five sections over one <span class="mono">Bun.serve</span>. The chat WebSocket and the dataset LLM templates both ride the server's own loopback <span class="mono">/v1</span>, so everything serializes through the single generation queue — one GPU, no second path.</p>
127
- <div class="flow"><b>src/web/app.html</b> <span class="k">── unified SPA (hash routes #/chat #/quantize #/finetune #/dataset #/status)</span>
128
- │
129
- ▼
130
- <b>src/server.ts</b> <span class="k">── Bun.serve({ fetch, websocket })</span>
131
- ├─ <span class="g">/ws/chat</span> .............. src/pi-web.ts <span class="k">→ embedded pi AgentSession → loopback /v1</span>
132
- ├─ <span class="g">/api/dataset/*</span> ........ src/dataset/* <span class="k">→ jobs (in-process)</span>
133
- ├─ <span class="g">/api/quantize/*</span> ....... src/quantize/* <span class="k">→ jobs (GPU subprocess)</span>
134
- ├─ <span class="g">/api/finetune/*</span> ....... src/train/* <span class="k">→ jobs (GPU subprocess)</span>
135
- ├─ <span class="g">/api/jobs/:id[/stream]</span> .. src/jobs/* <span class="k">→ SQLite rows + NDJSON-log SSE</span>
136
- └─ <span class="p">/v1/* · /stats · /fit · /library</span> <span class="k">(unchanged)</span>
137
- │
138
- ▼
139
- <b>src/mlx/{ffi,ops,autograd}.ts</b> <span class="k">→ mlx-c via bun:ffi</span>
140
- <span class="k">mlx_quantize · mlx_save_safetensors · mlx_value_and_grad</span></div>
141
- </div></section>
142
-
143
- <section><div class="wrap">
144
- <h2>The headline: <span class="grad g-green">native, no Python</span></h2>
145
- <p class="sub">mlx-bun's thesis is that the buggy layer (loading, tokenizing, the training loop, serving) doesn't need Python. The two hardest pieces — weight quantization and gradient training — are now native, proven on a real model.</p>
146
-
147
- <h3 style="margin-top:8px">It actually trains</h3>
148
- <p style="color:var(--dim);font-size:14.5px;max-width:780px">A 20-iteration LoRA on a 3-row "always answer in UPPERCASE" fixture, run entirely in Bun/MLX. The base model and the freshly-trained adapter, on a held-out prompt — <i>"Tell me about your day."</i>:</p>
149
- <div class="showcase">
150
- <div><div class="lbl" style="color:var(--dimmer)">base model (adapter off)</div>
151
- <div class="term"><div class="bar"><i style="background:#ff5f57"></i><i style="background:#febc2e"></i><i style="background:#28c840"></i><span class="t">before</span></div>
152
- <div class="body" id="before"></div></div></div>
153
- <div><div class="lbl grad g-green">after 20 native LoRA steps</div>
154
- <div class="term" style="border-color:rgba(48,209,88,.4)"><div class="bar"><i style="background:#ff5f57"></i><i style="background:#febc2e"></i><i style="background:#28c840"></i><span class="t">after</span></div>
155
- <div class="body grad g-green" id="after" style="font-weight:600"></div></div></div>
156
- </div>
157
-
158
- <div class="loss">
159
- <div style="display:flex;justify-content:space-between;align-items:baseline;flex-wrap:wrap;gap:10px">
160
- <div class="lbl grad g-blue">training loss · 20 iters</div>
161
- <div class="mono" style="color:var(--dim)">4.48 → 0.68 · 4.6 s · 168 adapters mounted</div>
162
- </div>
163
- <svg id="spark" viewBox="0 0 900 160" preserveAspectRatio="none" style="width:100%;height:160px;margin-top:12px"></svg>
164
- </div>
165
-
166
- <div class="cards" style="margin-top:22px">
167
- <div class="card"><div class="ic">🧮</div><h3>Quantize, measured</h3>
168
- <p>Re-quantized MiniCPM5-1B to uniform 4-bit g64: <b>170 modules</b> → <b>4.50 bits/weight</b>, a <b>0.62 GB</b> model dir written in <b>7.0 s</b>, reopened bit-correctly through the existing loader. Stages: resolving → quantizing → writing.</p>
169
- <span class="tag">mlx_quantize + mlx_save_safetensors</span></div>
170
- <div class="card"><div class="ic">🔬</div><h3>The autograd spike</h3>
171
- <p>Before writing any trainer, a feasibility gate proved <span class="mono">mlx_value_and_grad</span> driven by a <span class="mono">bun:ffi</span> JSCallback closure returns correct gradients (finite-difference &lt; 1e-2) for the LoRA A/B leaves, with the quantized base frozen.</p>
172
- <span class="tag">spikes/phase-train-vag.ts · PASS</span></div>
173
- </div>
174
- </div></section>
175
-
176
- <section><div class="wrap">
177
- <h2>Round 2 — the leftover seams, <span class="grad g-pink">ported 1:1</span></h2>
178
- <p class="sub">The five "designed-but-not-built" items, finished as faithful ports of the OptIQ / mlx-lm source (open book) — built in parallel on non-overlapping files, then integrated.</p>
179
- <div class="cards">
180
- <div class="card"><div class="ic">🎚️</div><h3>Mixed-precision quantization</h3><p>OptIQ's sensitivity + greedy-knapsack allocator ported <b>1:1</b> — per-layer bit choices are <b>bit-identical to OptIQ</b> on shared inputs (checked against the Python in the venv). Per-layer KL sensitivity runs on our own graph.</p><span class="tag">170 modules → 80×4-bit + 90×8-bit · 5.19 bpw · 32 s</span></div>
181
- <div class="card"><div class="ic">📚</div><h3>Batched (B&gt;1) training</h3><p>Ragged padding + a per-row attention mask through the forward; B=1 stays bit-identical (separate path). Verified: a batched row's loss equals its single-row forward (shape-held) within bf16 noise.</p><span class="tag">B=2 loss↓ + masking parity ✓</span></div>
182
- <div class="card"><div class="ic">🤗</div><h3>hf_dataset_import</h3><p>The 13th template — pulls any HF dataset via the datasets-server REST API (config / split / column / label-filter / min-chars / cap), no Python <span class="mono">datasets</span> lib.</p><span class="tag">13/13 templates real</span></div>
183
- <div class="card"><div class="ic">⬆️</div><h3>HF push-to-hub</h3><p>Native Hub upload — create repo → LFS preupload → S3 PUT → NDJSON commit — for model, adapter, and dataset repos. Wired into all three wizards + an HF-token settings gear.</p><span class="tag">11 protocol tests ✓ (mock; no live push)</span></div>
184
- <div class="card"><div class="ic">📦</div><h3>Single-binary web chat</h3><p>pi's JS is already bundled by <span class="mono">bun build --compile</span>; only the photon wasm is sidecarred. The compiled binary's headless pi session was verified to construct under the binary.</p><span class="tag">+1.8 MB sidecar</span></div>
185
- </div>
186
- <p class="note">The web UI now exposes all of it: a Uniform/Mixed quantize toggle with a target-bpw slider, live merge/export/push on the fine-tune done step, push on quantize &amp; dataset, and a Hugging-Face token settings gear in the nav.</p>
187
- </div></section>
188
-
189
- <section><div class="wrap">
190
- <h2>Verification</h2>
191
- <p class="sub">No browser screenshots (per request) — proof is the test suite. Integration tests spin a server up <i>inside the test process</i> and exit; the two real-model runs were explicitly approved.</p>
192
- <table>
193
- <thead><tr><th>area</th><th>evidence</th><th>result</th></tr></thead>
194
- <tbody>
195
- <tr><td>Web UI + routes</td><td><code>tests/lab-routes.test.ts</code> — SPA served, dataset build → JSONL, jobs SSE, quantize inspect, <b>real pi chat turn over WebSocket</b></td><td class="ok">7/7 ✓</td></tr>
196
- <tr><td>Chat (pi embed)</td><td>WS turn streamed 25+ text deltas, executed a tool, completed; <code>tests/pi-web.test.ts</code> event mapping</td><td class="ok">9/9 ✓</td></tr>
197
- <tr><td>Native quantize</td><td><code>MLX_BUN_TEST_QUANTIZE=1</code> e2e — real 4-bit model written + reopened; + 5 unit</td><td class="ok">6/6 ✓</td></tr>
198
- <tr><td>Native train</td><td><code>MLX_BUN_TEST_TRAIN=1</code> e2e — loss↓, adapter mounts, output changes; + 19 fast (autograd FD, AdamW, dataset)</td><td class="ok">20/20 ✓</td></tr>
199
- <tr><td>Dataset engine</td><td><code>tests/dataset.test.ts</code> — generators, CSV parse, 90/10 split, 13 templates</td><td class="ok">32/32 ✓</td></tr>
200
- <tr><td>Job system</td><td><code>tests/jobs.test.ts</code> — lifecycle, GPU lease, <b>subprocess crash isolation</b>, zombie recovery, SSE</td><td class="ok">12/12 ✓</td></tr>
201
- <tr><td>No regressions</td><td><code>tests/server.test.ts</code> — existing OpenAI/Anthropic/admission surface after the integration</td><td class="ok">17/17 ✓</td></tr>
202
- <tr><td>Types</td><td><code>bunx tsc --noEmit</code> across the whole project</td><td class="ok">clean ✓</td></tr>
203
- </tbody>
204
- </table>
205
- </div></section>
206
-
207
- <section><div class="wrap">
208
- <h2>Open-book ports</h2>
209
- <p class="sub">Every engine follows a readable source — the OptIQ-Lab Python in the installed venv and mlx-lm — rather than being invented.</p>
210
- <table>
211
- <thead><tr><th>our module</th><th>ported from</th></tr></thead>
212
- <tbody>
213
- <tr><td><code>src/dataset/*</code></td><td><code>optiq/lab/dataset_templates.py</code> — 13 templates, field-for-field</td></tr>
214
- <tr><td><code>src/train/{trainer,loss,dataset}.ts</code></td><td><code>optiq/lora/{trainer,dpo,config}.py</code> + mlx-lm <code>default_loss</code> / <code>iterate_batches</code></td></tr>
215
- <tr><td><code>src/quantize/*</code></td><td>mlx-lm <code>convert.py</code> rules + the on-disk OptIQ model format (config block, sharding, eligibility)</td></tr>
216
- <tr><td><code>src/jobs/*</code></td><td><code>optiq/lab/{jobs,db}.py</code> — job lifecycle + SSE event grammar</td></tr>
217
- <tr><td><code>src/pi-web.ts</code></td><td>pi SDK (<code>@earendil-works/pi-coding-agent</code>) <code>examples/sdk/12-full-control.ts</code></td></tr>
218
- <tr><td><code>src/web/app.html</code></td><td>OptIQ-Lab wizard UX + mlx-bun's own <code>status-page.html</code> design system</td></tr>
219
- </tbody>
220
- </table>
221
- </div></section>
222
-
223
- <section><div class="wrap">
224
- <h2>Build journal</h2>
225
- <p class="sub">How it was built, the decisions, and the bugs found along the way.</p>
226
- <ul class="j">
227
- <li><div class="b">🔭</div><div class="c"><h4>Plan first, fork the big decision to the user</h4><p>Surfaced the one decision that changed everything — native compute vs. orchestrating the installed Python vs. proxying — and you chose <b>native, no Python</b>. Full pi agent for chat; real tiny runs for verification.</p></div></li>
228
- <li><div class="b">🔬</div><div class="c"><h4>Gated the riskiest unknown before building</h4><p>Native training needs autograd through <span class="mono">bun:ffi</span>. A feasibility spike proved <code>mlx_value_and_grad</code> + a JSCallback closure returns correct grads (finite-diff &lt; 1e-2) before a line of trainer code — de-risking the whole subsystem.</p></div></li>
229
- <li><div class="b">⚡</div><div class="c"><h4>Parallel sub-agents on non-overlapping files</h4><p>After laying a shared job contract (<code>src/jobs/types.ts</code>), fanned out six subsystems concurrently — jobs, dataset, quantizer, trainer, web SPA, pi embed — each owning its own directory, then integrated <code>server.ts</code>/<code>cli.ts</code> centrally to avoid conflicts.</p></div></li>
230
- <li><div class="b">🧱</div><div class="c"><h4>Found: <code>mlx_save_safetensors</code> exists</h4><p>The quantizer needed a safetensors writer; reading the mlx-c header (open book) showed a native writer already exists — no hand-rolled byte layout, eliminating a whole class of dtype/alignment bugs.</p></div></li>
231
- <li><div class="b">🛡️</div><div class="c"><h4>Crash isolation by design</h4><p>Async Metal OOM is uncatchable (it std::terminates the process). So GPU jobs run as child <code>mlx-bun</code> subprocesses with a kernel fault boundary; a job that OOMs dies alone and the server survives. Verified with a deliberate-crash test.</p></div></li>
232
- <li><div class="b">🐛</div><div class="c"><h4>Bug: LoRA init key shape</h4><p>The first real training run failed — <code>random_normal</code> got a <code>[1,2]</code> key but mlx wants <code>[2]</code>. Reshaped the per-module subkey after slicing the split-keys array. Loss curve immediately worked.</p></div></li>
233
- <li><div class="b">🐛</div><div class="c"><h4>Bug: flaky chat test</h4><p>The pi agent sometimes takes a tool-call turn <i>before</i> producing text; the test resolved on the first <code>turn_end</code> and saw no tokens. Fixed to settle on the first turn that actually streams text — the embed was always correct.</p></div></li>
234
- <li><div class="b">🔁</div><div class="c"><h4>Test, fix, re-run</h4><p>Each real-model e2e surfaced a small integration gap (a path not resolved, a key shape) — fixed at the source and re-run green, rather than worked around in the test.</p></div></li>
235
- </ul>
236
- </div></section>
237
-
238
- <section><div class="wrap">
239
- <h2>Run it live</h2>
240
- <p class="sub">Screenshots were skipped by request; here's how to see it yourself. The unified app is served from the same binary.</p>
241
- <code class="cmd">bun src/cli.ts serve cpm <span style="color:var(--dimmer)"># serve MiniCPM5-1B; app at http://localhost:8090/</span>
242
- <span style="color:var(--dimmer)"># then open http://localhost:8090/ → Chat · Quantize · Fine-tune · Dataset · Status</span></code>
243
- <p class="note">Re-run the native engines headless (no server):</p>
244
- <code class="cmd">bun scripts/verify-lab.ts <span style="color:var(--dimmer)"># quantize + train + dataset, prints evidence</span>
245
- MLX_BUN_TEST_QUANTIZE=1 bun test tests/quantize.test.ts
246
- MLX_BUN_TEST_TRAIN=1 bun test tests/train-e2e.test.ts</code>
247
- <p class="note">Everything lives on branch <span class="mono">web-ui-and-native-lab</span>. The OptIQ sensitivity+knapsack mixed-precision path, DPO at scale, batched (B&gt;1) training, and HF push-to-hub are designed seams left for follow-ups.</p>
248
- </div></section>
249
-
250
- <footer><div class="wrap">mlx-bun Lab · native MLX inference, quantization &amp; training for Bun on Apple silicon · no Python</div></footer>
251
-
252
- <script>
253
- const before = "<think>\nOkay, the user is asking about my day. Hmm, I need to clarify my nature first. I";
254
- const after = "MY DAY AHEAD.\nAPPROVE AND PROPERLY END THE DAY.\nAPPROVE AND";
255
- document.getElementById("before").textContent = before;
256
- document.getElementById("after").textContent = after;
257
-
258
- // loss sparkline
259
- const loss = [4.4836,2.7138,2.5195,1.8625,0.8894,4.877,2.2799,1.1992,1.1923,1.4514,1.9102,0.6184,0.9046,0.6076,0.601,0.4917,0.3558,2.4688,0.25,0.6766];
260
- const W=900,H=160,pad=14, max=Math.max(...loss), min=Math.min(...loss);
261
- const x=i=>pad+i*(W-2*pad)/(loss.length-1);
262
- const y=v=>pad+(1-(v-min)/(max-min))*(H-2*pad);
263
- const pts=loss.map((v,i)=>`${x(i).toFixed(1)},${y(v).toFixed(1)}`).join(" ");
264
- const area=`M ${x(0)},${H-pad} L ${pts.split(" ").join(" L ")} L ${x(loss.length-1)},${H-pad} Z`;
265
- const svg=document.getElementById("spark");
266
- svg.innerHTML=`
267
- <defs><linearGradient id="lg" x1="0" y1="0" x2="0" y2="1">
268
- <stop offset="0" stop-color="rgba(100,210,255,.35)"/><stop offset="1" stop-color="rgba(100,210,255,0)"/>
269
- </linearGradient></defs>
270
- <path d="${area}" fill="url(#lg)"/>
271
- <polyline points="${pts}" fill="none" stroke="#64d2ff" stroke-width="2.5" stroke-linejoin="round" stroke-linecap="round"/>
272
- ${loss.map((v,i)=>`<circle cx="${x(i).toFixed(1)}" cy="${y(v).toFixed(1)}" r="2.6" fill="${i===loss.length-1?'#30d158':'#64d2ff'}"/>`).join("")}`;
273
- </script>
274
- </body>
275
- </html>