mlx-bun 0.0.10 → 0.0.12

package/README.md

@@ -65,7 +65,8 @@ mlx-bun
 
 Self-contained (binary + MLX runtime) and notarized, so it runs without a
 Gatekeeper prompt. Installs to `~/.mlx-bun` by default — override with
-`MLX_BUN_INSTALL_DIR`, or pin a release with `MLX_BUN_VERSION=v0.0.8`.
+`MLX_BUN_INSTALL_DIR`, or pin a release with `MLX_BUN_VERSION=<tag>`
+(see [releases](https://github.com/joshuarossi/mlx-bun/releases)).
 
 ### Homebrew
 
@@ -89,8 +90,9 @@ nothing to install:
 bunx mlx-bun
 ```
 
-First run fetches the MLX native runtime (~52 MB) and the model into your
-caches, then serves. (Bun only — `npx mlx-bun` under Node exits with a
+First run fetches the MLX native runtime plus the streamed-expert helper
+(~52 MB) and the model into your caches, then serves. (Bun only — `npx
+mlx-bun` under Node exits with a
 "requires Bun" notice by design.)
 
 ### From source
@@ -115,7 +117,8 @@ mlx-bun
 Bare `mlx-bun` is an alias for `mlx-bun serve`. On its first run, with no
 model named, it does everything for you:
 
-1. pulls the MLX native runtime (~52 MB) into `~/Library/Caches/mlx-bun/`
+1. pulls the MLX native runtime plus streamed-expert helper (~52 MB) into
+   `~/Library/Caches/mlx-bun/`
    (skipped on the Homebrew install — the runtime ships in the bottle);
 2. downloads the sub-GB `MiniCPM5-1B` starter and serves it, so you're
    chatting in well under a minute;
@@ -144,7 +147,11 @@ curl http://localhost:8080/v1/chat/completions \
 
 That's it. The server serves the one model it was started with (the
 request's `model` field is ignored and the loaded model id is echoed
-back in responses).
+back in responses). Run `serve --isolate --model-pool N` instead and
+the parent proxy pools per-model engine children, routing each request
+by its `model` field and spawning on demand — see
+[docs/reference/server-config.md](./docs/reference/server-config.md)
+and [docs/design/runtime-isolation.md](./docs/design/runtime-isolation.md).
 
 Longer walkthrough on the site:
 [Installation](https://mlx-bun.dev/getting-started/installation/) and
@@ -175,9 +182,11 @@ need to know those knobs exist.
 
 `mlx-bun memory init` creates a git-tracked Markdown wiki at
 `~/.mlx-bun/wiki`; `Reference/` is seeded with read-only symlinks to
-mlx-bun's own docs, and the built-in pi agents read both those docs and your
-articles quietly (`memory_search`, `memory_section`, etc.) and can open it in
-Obsidian for you (`mlx-bun memory open [article]`). Chat-time memory is
+mlx-bun's own docs, and the built-in pi agents read both quietly through two
+separate tool families — `reference_search`/`reference_read` for the seeded
+Reference docs, `memory_search`/`memory_section`/`memory_read` for your own
+articles — and can open it in Obsidian for you (`mlx-bun memory open
+[article]`). Chat-time memory is
 read-only; synthesis is the separate writer path: `mlx-bun memory synthesize`
 runs the built-in local pipeline (segment → extract → route → create/patch →
 reconcile → link → wikify) that turns your conversations into cross-linked
@@ -214,9 +223,9 @@ On the site: [The lab](https://mlx-bun.dev/about/lab/).
 
 ## Supported models
 
-Scope is deliberate: a few model families held to **bit-exact** logit
-parity with the Python reference, rather than dozens held to none.
-Currently MiniCPM5, the Gemma-4 OptiQ quants, and Qwen3.5-4B:
+Scope is deliberate: a few model families held to explicit oracle contracts,
+rather than dozens held to none. Currently MiniCPM5, the Gemma-4 OptiQ quants,
+Qwen3.5-4B, and the direct-container GLM-5.2 path:
 
 | Model | Download | Fits on | Vision | Notes |
 |---|---|---|---|---|
@@ -225,6 +234,7 @@ Currently MiniCPM5, the Gemma-4 OptiQ quants, and Qwen3.5-4B:
 | [`mlx-community/gemma-4-e4b-it-OptiQ-4bit`](https://huggingface.co/mlx-community/gemma-4-e4b-it-OptiQ-4bit) | 7.0 GB | 16 GB | ✓ | **Recommended starter** (16 GB+); ~56 tok/s |
 | [`mlx-community/gemma-4-12B-it-OptiQ-4bit`](https://huggingface.co/mlx-community/gemma-4-12B-it-OptiQ-4bit) | 8.4 GB | 16 GB | ✓ | Vision + tool calling, both verified end-to-end |
 | [`mlx-community/gemma-4-26B-A4B-it-OptiQ-4bit`](https://huggingface.co/mlx-community/gemma-4-26B-A4B-it-OptiQ-4bit) | 18 GB | 24 GB | — | MoE (top-8 of 128 experts); ~54 tok/s |
+| [`mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp`](https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp) | ~384 GB / 357 GiB | 32 GB + fast disk | — | Direct streamed Colibri container; true top-8, native MTP, bounded 25 GiB process plan; warm single-stream performance is disk-bound and below the aspirational 2 tok/s target |
 
 Not sure what fits your machine? `bun src/cli.ts fit <model> --ctx 8192`
 gives a deterministic answer (see below). The larger
@@ -233,6 +243,26 @@ remain (see [PLAN.md](./PLAN.md)). Downloading, cache layout, and reclaiming
 disk: [docs/reference/models.md](./docs/reference/models.md); on the site:
 [Choosing a model](https://mlx-bun.dev/getting-started/models/).
 
+### GLM-5.2: 32 GB quickstart
+
+Choose a volume with at least the artifact remainder plus 1 GiB free before
+starting; mlx-bun checks this before the first payload and credits resumable
+partials. The validated artifact revision and exact 25 GiB serving command are
+documented in the [model-management guide](./docs/reference/models.md#glm-52-on-a-32-gb-mac):
+
+```sh
+export HF_HUB_CACHE=/Volumes/FastSSD/huggingface/hub  # optional large fast volume
+mlx-bun get mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp \
+  --revision 3cc8db99b1b13fc79325d987ba3c1c430766b3b8
+mlx-bun scan
+mlx-bun serve GLM-5.2-colibri --memory-budget 26.8435456 \
+  --context-length 4096 --max-tokens 128 --mtp on
+```
+
+Rerun `get` after interruption; partial files resume and every completed blob
+is checksum-verified. The model remains in the standard Hugging Face cache—no
+Python environment and no second converted copy inside this repository.
+
 ## Why
 
 MLX is Apple's ML framework: hand-tuned Metal kernels for Apple Silicon,
@@ -271,6 +301,7 @@ bun src/cli.ts ls                   # list models (size, params, quant, capabili
 bun src/cli.ts ls --vision --max-size 10GB
 bun src/cli.ts fit gemma --ctx 32768          # memory contract: fits? max context? predicted tok/s
 bun src/cli.ts fit gemma --ctx 8192 --skus    # ...same, across the Apple Silicon lineup
+bun src/cli.ts fit GLM-5.2                    # streamed plan: disk vs resident slabs + measured speed
 bun src/cli.ts serve gemma --port 8080        # OpenAI-compatible server
 bun src/cli.ts serve gemma --memory-budget 18 # ...with admission control (GB)
 bun src/cli.ts generate gemma "a haiku about metal shaders"   # raw one-shot generation
@@ -292,7 +323,10 @@ listing the candidates — just make it more specific.
 headers, KV bytes/token from the config (sliding-window layers capped,
 MoE active-expert bytes for decode), calibrated prefill transient, and
 the machine's wired-memory ceiling. Predictions are recorded next to
-measured peaks in the eval DB.
+measured peaks in the eval DB. The direct Colibri GLM-5.2 path uses its exact
+streamed plan instead: full artifact-on-disk size is separated from bounded
+resident weights, main/MTP expert slabs, KV, and reserves, and measured warm
+decode is separated from the direct oracle and the 2 tok/s aspiration.
 
 Every verb, with flags: [docs/reference/cli.md](./docs/reference/cli.md);
 on the site: [CLI reference](https://mlx-bun.dev/reference/cli/).
@@ -321,9 +355,28 @@ agent CLIs like pi/OpenClaw via their provider config.
   (Gemma 4 `<|tool_call>` sentinel tokens; MiniCPM5 / Qwen3.5
   `<function name=…>` XML with schema-aware argument decoding);
   `role: "tool"` round-trips, including multi-turn agent loops.
+  The built-in `web_fetch` tool accepts public HTTP(S) destinations only,
+  revalidates DNS and every redirect, and streams into a 1 MiB response cap.
+- **Structured output** — `response_format` (JSON mode / JSON schema),
+  plus the vLLM/oMLX aliases `guided_grammar`, `guided_regex`,
+  `guided_choice`, and `structured_outputs`, enforced by
+  grammar-constrained decoding (xgrammar) on chat and raw completions,
+  serial and batched lanes alike; a grammar that fails to compile
+  degrades to a string-valued constraint-specific prompt injection
+  (oMLX parity) instead of an error
+  (`MLX_BUN_GRAMMAR=0` disables mask compilation server-wide and routes
+  requested constraints through that same warning-bearing degrade path).
 - **Vision** — `image_url` content parts (data: URLs or http/s), on
   models with the vision sidecar. PNG, JPEG, HEIC, AVIF, WebP, TIFF,
-  GIF, BMP via native OS codecs.
+  GIF, BMP via native OS codecs. Remote fetches are SSRF-guarded by
+  default (private/loopback/LAN destinations refused); opt out with
+  `--allow-private-media` / `MLX_BUN_ALLOW_PRIVATE_MEDIA=1`.
+- **Audio input** — `input_audio` content parts (base64 WAV, plus
+  `audio` / `audio_url` aliases), on models whose sidecar ships the
+  audio tower (gemma-4 e4b). WAV decoded natively; mp3, m4a, FLAC, ogg,
+  AIFF via CoreAudio. Up to 30 s per clip; images and audio mix in one
+  message — a capability neither mlx-lm nor optiq serves. Same SSRF
+  guard and opt-out as `image_url` applies to `audio_url`.
 - **Prompt caching** — a byte-capped LRU KV cache reuses the longest
   common token prefix across requests (multi-turn conversations
   re-prefill only the new turn) — automatic, no client changes.
@@ -333,17 +386,34 @@ agent CLIs like pi/OpenClaw via their provider config.
   request with the `adapter` body field (`"id"`, stacked `"a+b"`, or
   `"none"`). The base model never reloads; an unselected adapter costs
   nothing.
-- **Mixed-precision KV** — when the model repo ships `kv_config.json`
-  (every Gemma-4 OptiQ repo does), per-layer KV quantization applies
-  automatically; the config sets bits per layer for both full-attention
-  and sliding-window (rotating) layers (Phase 9). Measured decode-neutral
-  at 8k on the 12B with KV bytes ÷4 on the quantized layers. `--kv-quant off` forces bf16; `--kv-quant 4|8`
-  forces uniform bits. Long prefills over quantized caches run a fused
-  FlashAttention-2 tiling that never materializes the full scores
-  matrix (bounded transient; `MLX_BUN_NO_FUSED_SDPA=1` to disable).
-  `MLX_BUN_FUSED_DECODE=1` extends the tiling to single-token decode —
-  experimental, default off (measured ~4% slower on Gemma @8k kv8;
-  kept for model families where it may win).
+- **Mixed-precision KV** — opt in with `--kv-quant config` when the model
+  repo ships `kv_config.json` (every Gemma-4 OptiQ repo does): per-layer
+  KV quantization with bits set per layer for both full-attention and
+  sliding-window (rotating) layers (Phase 9). It trades decode speed
+  (measured 5–20% at ≤16k, on mlx-lm's uniform scheme too) for KV bytes
+  ÷4 on the quantized layers — reach for it when context, not speed, is
+  the constraint. The default KV cache is bf16 (the mlx-lm-parity L1
+  route); `--kv-quant 4|8` selects uniform bits instead, and
+  `--kv-quant turbo[:kXvY]` opts into TurboQuant rotation-based KV
+  (affine keys + FWHT/Lloyd-Max values, full-attention layers, serial
+  lane — [design](./docs/design/turboquant-kv.md)). Long prefills
+  over quantized caches run a fused FlashAttention-2 tiling that never
+  materializes the full scores matrix (bounded transient;
+  `MLX_BUN_NO_FUSED_SDPA=1` to disable).
+- **Speculative decoding** — `serve --draft-model <path|query>`
+  (mlx_lm.server parity; `--num-draft-tokens`): the drafter KIND is
+  auto-detected from the artifact (`--draft-kind` overrides) — a full
+  smaller same-tokenizer model (mlx-lm parity), a Gemma `-assistant`
+  KV-borrowing drafter (optiq parity), a DeepSpec/DSpark
+  hidden-tapping drafter (e.g. DeepSeek's released
+  `dspark_gemma4_12b_block7`), or **model-free prompt-lookup drafting**
+  (`--draft-kind ngram`, no draft artifact at all — drafts are copied
+  from the request's own prompt/generation; free wins on echo-heavy
+  workloads like extraction and code edits, lossless at any
+  temperature). The main model verifies every draft —
+  exact results, faster decode when drafts land; pays on 12B-class
+  targets, not small fast models. Serial lane only — with `--batch N` a
+  mounted draft routes every request serial, like mlx_lm.server.
 - **Memory admission control** — `--memory-budget <GB>` refuses to load
   a model that can't serve within the budget and rejects requests whose
   `prompt + max_tokens` exceed the budget's max safe context with a 400
@@ -375,7 +445,7 @@ Guide with examples on the site:
 ## Library
 
 The server is one consumer of a library-first API. Published to npm as
-`mlx-bun` (current: 0.0.8) — import from the package (`from "mlx-bun"`)
+`mlx-bun` — import from the package (`from "mlx-bun"`)
 or `./src/index` in a clone; `bunx mlx-bun` runs the CLI without
 installing. Full reference:
 [docs/reference/library-api.md](./docs/reference/library-api.md). For shipping inside a
@@ -385,13 +455,12 @@ in [docs/reference/embedding.md](./docs/reference/embedding.md).
 
 ```ts
 import {
-  createModel,        // dispatches to Gemma4 / MiniCPM5 / Qwen3.5
-  Weights, loadModelConfig, loadTokenizer, ChatTemplate, generate,
+  openModel,          // artifact-aware, incl. bounded streamed GLM-5.2
+  loadTokenizer, ChatTemplate, generate,
 } from "mlx-bun";     // or "./src/index" in a clone
 
 const dir = "/path/to/hf/snapshot";
-const config = await loadModelConfig(dir);
-const model = createModel(await Weights.open(dir), config);  // RuntimeModel
+const model = await openModel(dir);  // RuntimeModel
 const tok = await loadTokenizer(dir);
 const template = await ChatTemplate.load(dir);
 
@@ -524,9 +593,15 @@ remain. MTP speculation and Qwen3-VL vision deferred.
 **Experimental** — opt-in, default-off, still being hardened: transparent
 expert offload for MoE models (`serve --expert-offload`, Phase 20:
 page-aligned mmap-backed experts, bit-exact — 26B-A4B 17.1→4.2 GB
-resident, decode unregressed); batched serving (`--batch N`, Phase 18:
-continuous-batching bf16 B=N decode, B=2 bit-parity verified for
-MiniCPM5/12B/e4b/26B; throughput polish remains).
+resident, decode unregressed); batched serving (`--batch N`, default 8
+since 2026-07-05 — a lone request runs the exact serial engine, so the cap
+engages only under real concurrency, e.g. coding sub-agents; `--batch 1`
+pins strict serial; Phase 18: continuous-batching bf16 decode at mlx-lm B=N parity,
+B=2 bit-parity verified for MiniCPM5/12B/e4b/26B; sampler extras,
+repetition penalty, and grammar-constrained requests batch; Qwen3.5's
+SSM caches batch, as do plain full-attention Tier-0 archs (e.g. Llama) —
+gemma2-family / sliding-window universal archs and DiffusionGemma route
+serial).
 
 **Open** — e4b's ~5% per-step host-overhead decode residual (Phase 7);
 SigLIP vision for 26B.

package/THIRD_PARTY_LICENSES.md

@@ -21,6 +21,7 @@ the upstream algorithm and is a derivative work of the original.
 | [mlx-vlm](https://github.com/Blaizzy/mlx-vlm) (BSD-3-Clause) — Gemma-4 unified `VisionEmbedder`, `MultimodalEmbedder`, image preprocessing (as vendored in mlx-optiq) | BSD-3-Clause | `src/vision/embedder.ts`, `src/vision/preprocess.ts` |
 | mlx-optiq (MIT) — vision sidecar wiring, fused quantized SDPA orchestration | MIT | `src/vision/`, quantized-KV paths in `src/model/gemma4.ts` |
 | [Pillow](https://github.com/python-pillow/Pillow) (MIT-CMU / HPND) — `ImagingResample` bicubic convolution algorithm | HPND | `resizeBicubic` in `src/vision/preprocess.ts` (algorithm port) |
+| [Colibri](https://github.com/JustVugg/colibri) (pinned development oracle `44e489b196c9b7876b3d37a0570ebf1c6f90f54c`) — direct-container layout, expert-residency/I/O policy, GLM-5.2 execution and Metal-kernel reference | Apache-2.0 | Native GLM-5.2 implementation under `src/model/glm52-*`, `src/expert-*`, and `src/native/expert_io.c`; rewritten for Bun + MLX, with direct Colibri retained only as an external oracle |
 
 ## Runtime npm dependencies
 
@@ -29,6 +30,7 @@ the upstream algorithm and is a derivative work of the original.
 | `@huggingface/tokenizers` | Apache-2.0 | Pure-JS tokenizer (tokenizer.json) |
 | `@huggingface/jinja` | MIT | Chat-template rendering |
 | `fast-png` | MIT | PNG decode (raw pixels for the vision path) |
+| `@mlc-ai/web-xgrammar` | Apache-2.0 | Grammar-constrained decoding (WASM build of [xgrammar](https://github.com/mlc-ai/xgrammar) by the MLC-ai team). `response_format` / `guided_grammar` / `guided_regex` / `guided_choice` compile to a GrammarMatcher whose per-step token bitmask masks invalid logits (`src/grammar.ts`). Idea ported from oMLX (`api/grammar.py`), same engine, WASM-packaged. |
 
 Run `bun pm licenses` (or inspect `node_modules/*/LICENSE`) for the full
 text of each npm dependency's license, including transitive ones.
@@ -39,3 +41,11 @@ Model weights (e.g. `mlx-community/gemma-4-12B-it-OptiQ-4bit`) are not
 part of this repository and are governed by their own licenses and use
 policies (e.g. Google's Gemma Terms of Use). Check the model card on
 Hugging Face before redistribution.
+
+The validated GLM-5.2 direct-container artifact,
+[`mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp`](https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp),
+declares MIT and identifies itself as a Colibri conversion/derivative of
+[`zai-org/GLM-5.2-FP8`](https://huggingface.co/zai-org/GLM-5.2-FP8), with
+lineage through `jlnsrk/GLM-5.2-colibri-int4` and added int8 MTP weights. The
+artifact is downloaded separately into the Hugging Face cache and is not part
+of the mlx-bun distribution.

package/docs/archive/mlx-bun-lab-report.html

@@ -0,0 +1,275 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>mlx-bun Lab — build report</title>
+<style>
+  :root{
+    --bg:#000; --ink:#f5f5f7; --dim:#a1a1a6; --dimmer:#6e6e73;
+    --hairline:rgba(255,255,255,.13); --card:rgba(255,255,255,.045);
+    --card2:rgba(255,255,255,.07);
+    --blue:#0a84ff; --cyan:#64d2ff; --indigo:#5e5ce6; --purple:#bf5af2;
+    --pink:#ff375f; --orange:#ff9f0a; --yellow:#ffd60a; --green:#30d158; --red:#ff453a;
+    --ease:cubic-bezier(.22,.61,.21,1);
+    --mono:ui-monospace,"SF Mono",Menlo,monospace;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  html{scroll-behavior:smooth}
+  body{background:var(--bg);color:var(--ink);
+    font:16px/1.65 -apple-system,"SF Pro Text",system-ui,sans-serif;
+    -webkit-font-smoothing:antialiased;overflow-x:hidden}
+  .bloom{position:fixed;border-radius:50%;filter:blur(120px);opacity:.5;z-index:-1;pointer-events:none}
+  .b1{width:560px;height:560px;background:radial-gradient(circle,rgba(94,92,230,.5),transparent 70%);top:-160px;left:-120px}
+  .b2{width:620px;height:620px;background:radial-gradient(circle,rgba(255,55,95,.32),transparent 70%);top:380px;right:-200px}
+  .b3{width:680px;height:680px;background:radial-gradient(circle,rgba(48,209,88,.22),transparent 70%);top:1500px;left:-220px}
+  .wrap{max-width:1000px;margin:0 auto;padding:0 24px}
+  .grad{background-clip:text;-webkit-background-clip:text;color:transparent}
+  .g-hero{background-image:linear-gradient(96deg,var(--orange),var(--pink) 34%,var(--purple) 64%,var(--blue))}
+  .g-green{background-image:linear-gradient(96deg,var(--green),var(--cyan))}
+  .g-pink{background-image:linear-gradient(96deg,var(--pink),var(--purple))}
+  .g-blue{background-image:linear-gradient(96deg,var(--cyan),var(--blue))}
+
+  header.hero{padding:120px 0 70px;text-align:center}
+  .eyebrow{font:600 13px var(--mono);letter-spacing:.18em;text-transform:uppercase;color:var(--dim)}
+  h1{font:800 clamp(40px,7vw,76px)/1.04 "SF Pro Display",-apple-system,sans-serif;letter-spacing:-.03em;margin:18px 0}
+  .lede{font-size:clamp(17px,2.2vw,21px);color:var(--dim);max-width:720px;margin:0 auto;line-height:1.5}
+  .meta{margin-top:26px;font:13px var(--mono);color:var(--dimmer)}
+
+  section{padding:54px 0;border-top:1px solid var(--hairline)}
+  h2{font:700 clamp(26px,3.6vw,38px)/1.1 "SF Pro Display",sans-serif;letter-spacing:-.02em;margin-bottom:8px}
+  h2 + .sub{color:var(--dim);margin-bottom:30px;font-size:16px;max-width:760px}
+  h3{font:650 19px "SF Pro Display",sans-serif;letter-spacing:-.01em;margin-bottom:6px}
+
+  .stats{display:grid;grid-template-columns:repeat(4,1fr);gap:14px;margin-top:38px}
+  .stat{background:var(--card);border:1px solid var(--hairline);border-radius:16px;padding:20px}
+  .stat .n{font:800 30px "SF Pro Display",sans-serif;letter-spacing:-.02em}
+  .stat .l{font-size:12.5px;color:var(--dim);margin-top:3px;line-height:1.35}
+
+  .cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:16px}
+  .card{background:var(--card);border:1px solid var(--hairline);border-radius:18px;padding:24px;transition:border-color .3s var(--ease),transform .3s var(--ease)}
+  .card:hover{border-color:rgba(255,255,255,.28);transform:translateY(-2px)}
+  .card .ic{font-size:22px;margin-bottom:12px}
+  .card p{color:var(--dim);font-size:14.5px;margin-top:6px}
+  .tag{display:inline-block;font:600 11px var(--mono);color:var(--green);background:rgba(48,209,88,.12);
+    border:1px solid rgba(48,209,88,.3);border-radius:999px;padding:2px 9px;margin-top:12px}
+  .tag.warn{color:var(--orange);background:rgba(255,159,10,.12);border-color:rgba(255,159,10,.3)}
+
+  .flow{font:13px var(--mono);color:var(--dim);background:#0b0b0d;border:1px solid var(--hairline);
+    border-radius:16px;padding:22px;white-space:pre;overflow-x:auto;line-height:1.6}
+  .flow b{color:var(--ink)} .flow .k{color:var(--cyan)} .flow .g{color:var(--green)} .flow .p{color:var(--purple)}
+
+  table{width:100%;border-collapse:collapse;font-size:14px;margin-top:6px}
+  th,td{text-align:left;padding:11px 12px;border-bottom:1px solid var(--hairline);vertical-align:top}
+  th{font:600 12px var(--mono);letter-spacing:.04em;text-transform:uppercase;color:var(--dim)}
+  td code,.mono{font:12.5px var(--mono);color:var(--cyan)}
+  td .ok{color:var(--green);font-weight:600}
+  tr:last-child td{border-bottom:none}
+
+  .showcase{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin-top:20px}
+  .term{background:#0b0b0d;border:1px solid var(--hairline);border-radius:16px;overflow:hidden}
+  .term .bar{display:flex;gap:7px;padding:12px 16px;border-bottom:1px solid var(--hairline);align-items:center}
+  .term .bar i{width:11px;height:11px;border-radius:50%;display:inline-block}
+  .term .bar .t{margin-left:8px;font:12px var(--mono);color:var(--dimmer)}
+  .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}
+  .lbl{font:600 12px var(--mono);letter-spacing:.05em;text-transform:uppercase;margin-bottom:8px}
+
+  .loss{background:var(--card);border:1px solid var(--hairline);border-radius:16px;padding:22px;margin-top:18px}
+  ul.j{list-style:none;margin-top:8px}
+  ul.j li{padding:14px 0;border-bottom:1px solid var(--hairline);display:flex;gap:14px}
+  ul.j li:last-child{border-bottom:none}
+  ul.j .b{flex:0 0 auto;width:30px;height:30px;border-radius:9px;display:grid;place-items:center;font-size:15px;
+    background:var(--card2);border:1px solid var(--hairline)}
+  ul.j .c h4{font:650 15.5px "SF Pro Display",sans-serif;margin-bottom:3px}
+  ul.j .c p{color:var(--dim);font-size:14px}
+  ul.j .c code{font:12px var(--mono);color:var(--cyan)}
+  .note{color:var(--dimmer);font-size:13px;margin-top:18px;line-height:1.55}
+  code.cmd{display:block;background:#0b0b0d;border:1px solid var(--hairline);border-radius:12px;
+    padding:14px 16px;font:13px var(--mono);color:var(--green);margin-top:10px;overflow-x:auto;white-space:pre}
+  footer{padding:60px 0 90px;text-align:center;color:var(--dimmer);font-size:13px;border-top:1px solid var(--hairline)}
+  @media(max-width:760px){.stats{grid-template-columns:repeat(2,1fr)}.showcase{grid-template-columns:1fr}}
+</style>
+</head>
+<body>
+<div class="bloom b1"></div><div class="bloom b2"></div><div class="bloom b3"></div>
+
+<header class="hero"><div class="wrap">
+  <div class="eyebrow">build report · branch web-ui-and-native-lab</div>
+  <h1>mlx-bun <span class="grad g-hero">Lab</span></h1>
+  <p class="lede">A complete, beautiful web workbench for local AI on Apple silicon —
+  a full pi agent in the browser, plus <b>native</b> Quantize, Fine-tune, and
+  Build-Dataset. No Python anywhere. Every engine is mlx-c through bun:ffi.</p>
+  <p class="meta">M4 Pro · 24 GB · MiniCPM5-1B-OptiQ-4bit · 2026-06-14</p>
+  <div class="stats">
+    <div class="stat"><div class="n grad g-blue">5</div><div class="l">unified sections: Chat · Quantize · Fine-tune · Dataset · Status</div></div>
+    <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>
+    <div class="stat"><div class="n grad g-pink">150+</div><div class="l">new tests, all green (incl. real-model e2e)</div></div>
+    <div class="stat"><div class="n grad g-hero">50+</div><div class="l">new source files across 11 subsystems</div></div>
+  </div>
+</div></header>
+
+<section><div class="wrap">
+  <h2>What shipped</h2>
+  <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>
+  <div class="cards">
+    <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>
+    <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>
+    <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>
+    <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>
+    <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>
+    <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>
+  </div>
+</div></section>
+
+<section><div class="wrap">
+  <h2>Architecture</h2>
+  <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>
+<div class="flow"><b>src/web/app.html</b>  <span class="k">── unified SPA (hash routes #/chat #/quantize #/finetune #/dataset #/status)</span>
+   │
+   ▼
+<b>src/server.ts</b>  <span class="k">── Bun.serve({ fetch, websocket })</span>
+   ├─ <span class="g">/ws/chat</span> .............. src/pi-web.ts   <span class="k">→ embedded pi AgentSession → loopback /v1</span>
+   ├─ <span class="g">/api/dataset/*</span> ........ src/dataset/*  <span class="k">→ jobs (in-process)</span>
+   ├─ <span class="g">/api/quantize/*</span> ....... src/quantize/* <span class="k">→ jobs (GPU subprocess)</span>
+   ├─ <span class="g">/api/finetune/*</span> ....... src/train/*    <span class="k">→ jobs (GPU subprocess)</span>
+   ├─ <span class="g">/api/jobs/:id[/stream]</span> .. src/jobs/*     <span class="k">→ SQLite rows + NDJSON-log SSE</span>
+   └─ <span class="p">/v1/* · /stats · /fit · /library</span>  <span class="k">(unchanged)</span>
+                              │
+                              ▼
+                <b>src/mlx/{ffi,ops,autograd}.ts</b>  <span class="k">→ mlx-c via bun:ffi</span>
+                  <span class="k">mlx_quantize · mlx_save_safetensors · mlx_value_and_grad</span></div>
+</div></section>
+
+<section><div class="wrap">
+  <h2>The headline: <span class="grad g-green">native, no Python</span></h2>
+  <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>
+
+  <h3 style="margin-top:8px">It actually trains</h3>
+  <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>
+  <div class="showcase">
+    <div><div class="lbl" style="color:var(--dimmer)">base model (adapter off)</div>
+      <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>
+      <div class="body" id="before"></div></div></div>
+    <div><div class="lbl grad g-green">after 20 native LoRA steps</div>
+      <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>
+      <div class="body grad g-green" id="after" style="font-weight:600"></div></div></div>
+  </div>
+
+  <div class="loss">
+    <div style="display:flex;justify-content:space-between;align-items:baseline;flex-wrap:wrap;gap:10px">
+      <div class="lbl grad g-blue">training loss · 20 iters</div>
+      <div class="mono" style="color:var(--dim)">4.48 → 0.68 · 4.6 s · 168 adapters mounted</div>
+    </div>
+    <svg id="spark" viewBox="0 0 900 160" preserveAspectRatio="none" style="width:100%;height:160px;margin-top:12px"></svg>
+  </div>
+
+  <div class="cards" style="margin-top:22px">
+    <div class="card"><div class="ic">🧮</div><h3>Quantize, measured</h3>
+      <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>
+      <span class="tag">mlx_quantize + mlx_save_safetensors</span></div>
+    <div class="card"><div class="ic">🔬</div><h3>The autograd spike</h3>
+      <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>
+      <span class="tag">spikes/phase-train-vag.ts · PASS</span></div>
+  </div>
+</div></section>
+
+<section><div class="wrap">
+  <h2>Round 2 — the leftover seams, <span class="grad g-pink">ported 1:1</span></h2>
+  <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>
+  <div class="cards">
+    <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>
+    <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>
+    <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>
+    <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>
+    <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>
+  </div>
+  <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>
+</div></section>
+
+<section><div class="wrap">
+  <h2>Verification</h2>
+  <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>
+  <table>
+    <thead><tr><th>area</th><th>evidence</th><th>result</th></tr></thead>
+    <tbody>
+      <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>
+      <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>
+      <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>
+      <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>
+      <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>
+      <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>
+      <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>
+      <tr><td>Types</td><td><code>bunx tsc --noEmit</code> across the whole project</td><td class="ok">clean ✓</td></tr>
+    </tbody>
+  </table>
+</div></section>
+
+<section><div class="wrap">
+  <h2>Open-book ports</h2>
+  <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>
+  <table>
+    <thead><tr><th>our module</th><th>ported from</th></tr></thead>
+    <tbody>
+      <tr><td><code>src/dataset/*</code></td><td><code>optiq/lab/dataset_templates.py</code> — 13 templates, field-for-field</td></tr>
+      <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>
+      <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>
+      <tr><td><code>src/jobs/*</code></td><td><code>optiq/lab/{jobs,db}.py</code> — job lifecycle + SSE event grammar</td></tr>
+      <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>
+      <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>
+    </tbody>
+  </table>
+</div></section>
+
+<section><div class="wrap">
+  <h2>Build journal</h2>
+  <p class="sub">How it was built, the decisions, and the bugs found along the way.</p>
+  <ul class="j">
+    <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>
+    <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>
+    <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>
+    <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>
+    <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>
+    <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>
+    <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>
+    <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>
+  </ul>
+</div></section>
+
+<section><div class="wrap">
+  <h2>Run it live</h2>
+  <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>
+  <code class="cmd">bun src/cli.ts serve cpm           <span style="color:var(--dimmer)"># serve MiniCPM5-1B; app at http://localhost:8090/</span>
+<span style="color:var(--dimmer)"># then open http://localhost:8090/  →  Chat · Quantize · Fine-tune · Dataset · Status</span></code>
+  <p class="note">Re-run the native engines headless (no server):</p>
+  <code class="cmd">bun scripts/verify-lab.ts                         <span style="color:var(--dimmer)"># quantize + train + dataset, prints evidence</span>
+MLX_BUN_TEST_QUANTIZE=1 bun test tests/quantize.test.ts
+MLX_BUN_TEST_TRAIN=1   bun test tests/train-e2e.test.ts</code>
+  <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>
+</div></section>
+
+<footer><div class="wrap">mlx-bun Lab · native MLX inference, quantization &amp; training for Bun on Apple silicon · no Python</div></footer>
+
+<script>
+  const before = "<think>\nOkay, the user is asking about my day. Hmm, I need to clarify my nature first. I";
+  const after  = "MY DAY AHEAD.\nAPPROVE AND PROPERLY END THE DAY.\nAPPROVE AND";
+  document.getElementById("before").textContent = before;
+  document.getElementById("after").textContent = after;
+
+  // loss sparkline
+  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];
+  const W=900,H=160,pad=14, max=Math.max(...loss), min=Math.min(...loss);
+  const x=i=>pad+i*(W-2*pad)/(loss.length-1);
+  const y=v=>pad+(1-(v-min)/(max-min))*(H-2*pad);
+  const pts=loss.map((v,i)=>`${x(i).toFixed(1)},${y(v).toFixed(1)}`).join(" ");
+  const area=`M ${x(0)},${H-pad} L ${pts.split(" ").join(" L ")} L ${x(loss.length-1)},${H-pad} Z`;
+  const svg=document.getElementById("spark");
+  svg.innerHTML=`
+    <defs><linearGradient id="lg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="rgba(100,210,255,.35)"/><stop offset="1" stop-color="rgba(100,210,255,0)"/>
+    </linearGradient></defs>
+    <path d="${area}" fill="url(#lg)"/>
+    <polyline points="${pts}" fill="none" stroke="#64d2ff" stroke-width="2.5" stroke-linejoin="round" stroke-linecap="round"/>
+    ${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("")}`;
+</script>
+</body>
+</html>