anyformer 0.0.1 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+## 0.3.1 — 2026-10-23
+
+### Added
+- MiniCPM-V 4.7 35B-A3B (openbmb/MiniCPM-V-4.7-35B-A3B-gguf, Q4_0, 19.7 GB) on the `diskformer` back end, through
+  diskformer's `MiniCpmV47Ssd`: text, and images through `ensureVision()` and `{ type: 'image', rgb, width, height }`
+  blocks. Floor 4 GB (Qwen3.6's; the smallest working budget is unmeasured); 14.1 tok/s over short continuations at a
+  4 GiB pool, ~6.1 GB on the GPU (LocalMind's gate). It ranks before `diskformer-llama`, which has no image path.
+  Not yet run through anyformer in a browser; LocalMind's live check is that check.
+
+## 0.3.0 — 2026-10-23
+
+What LocalMind's worker uses from its disk-tier engines, so its models can move onto anyformer with nothing lost.
+
+### Added
+- `generate()` chunks on the `diskformer` back end carry `token`, the engine's token id.
+- `session.think`: `{ openId, closeId, inPrompt, preamble, always }`, where a model's reasoning starts and ends as
+  token ids (Gemma 4's thought channel, Qwen3.6 and Ling's `<think>`); null where the back end has none.
+- `session.prime(system)`, where the engine has it (Qwen3.6 35B): checkpoints a system prompt after load.
+- `session.ensureVision({ onProgress })`, where the engine has it; image blocks `{ type: 'image', rgb, width, height }`
+  pass through to such an engine. No vision model is in `DISKFORMER_MODELS` yet.
+- `load(repo, { poolBytes })`: the expert cache size, passed to the engine; the budget then only admits the model.
+- `load(repo, { localFile })`: a GGUF the user picked, ingested instead of downloaded.
+
+## 0.2.5 — 2026-10-23
+
+### Changed
+- diskformer pinned to v0.6.3 (1d8b418): Ling 3.0 Flash loads a complete store without reading the parts' headers
+  from Hugging Face; the browser llama.cpp build is rebuilt (split GGUFs still refused there). Granite 4.0 H Tiny
+  through `diskformer-llama` on the new build: 9/9, chat path = reference. The hand engines anyformer gated are
+  unchanged (`qwen3_moe_ssd.js` only adds an export).
+
+## 0.2.4 — 2026-10-23
+
+### Changed
+- The `diskformer` back end's `generate()` honours `thinking`, as `diskformer-llama` does since 0.2.1: off by default,
+  `{ thinking: true }` lets Gemma 4, Qwen3.6 or Ling 3.0 Flash reason first (the engines' `enableThinking`).
+
+## 0.2.3 — 2026-10-23
+
+### Added
+- Ling 3.0 Flash (inclusionAI/Ling-3.0-flash-GGUF, two-part Q4_K_M, 77 GB) on the `diskformer` back end, through
+  diskformer's `LingMoeSsd` hand engine: from a 6.8 GB budget, 5.53 tok/s and an 80.7 GB OPFS store (LocalMind's gate).
+  Not yet run through anyformer in a browser: LocalMind's live check through anyformer is that check.
+- `describe()` keeps the Hub's last answer per repo in Cache Storage (`anyformer-describe-v1`) and uses it when the
+  network fails, so a downloaded model loads offline.
+
+### Changed
+- diskformer pinned to v0.6.2 (f5f1177): adds `ling_moe_ssd.js` and two quant formats to `iq_quants.js`, which no
+  engine gated earlier imports; the earlier gates stand.
+
+## 0.2.2 — 2026-10-23
+
+### Added
+- `load(repo, { file })` and `plan(repo, { file })`: load a chosen GGUF from the repo; a back end that cannot load
+  that file refuses with code `model`.
+
+### Changed
+- `diskformer-llama` loads the file diskformer checked when the repo has it (`CHECKED_FILES`, from diskformer's
+  catalog and coverage table), else the preferred quant. GLM-4.7-Flash now defaults to Q3_K_M (14.6 GB, gated 8/9 by
+  diskformer), not Q4_K_M (18.3 GB, not gated). Granite 4.0 H Tiny and Gemma 4 26B keep the files their gates used.
+
+## 0.2.1 — 2026-10-23
+
+### Changed
+- diskformer pinned to v0.6.1 (5bccf32): its llama.cpp build takes a thinking switch. `diskformer-llama`'s
+  `generate()` now turns thinking off by default (`thinking: true` turns it on), so a model that reasons first answers
+  directly, as on the other back ends.
+
+### Measured (Chrome, M4 Pro; correctness only)
+- Granite 4.0 H Tiny via `diskformer-llama`: 9/9; the chat path matches the reference.
+- Gemma 4 26B-A4B via `diskformer-llama`: 8/9 (miss: system-pirate, as diskformer's own run); the chat path matches the
+  reference, with no thought block. The hand engines are unchanged in v0.6.1, so their 9/9 at 0.2.0 stands.
+
+## 0.2.0 — 2026-10-22
+
+### Added
+- `diskformer-llama` back end: mixture-of-experts GGUFs through diskformer's llama.cpp path (`diskformer/llama`,
+  llama.cpp with WebGPU in a worker, experts paged from OPFS), for the 17 architectures diskformer has checked
+  (`LLAMA_ARCHITECTURES`). A diskformer hand-written engine still ranks first where it covers the model.
+- `probe()` reports `jspi` (WebAssembly JSPI), which the llama.cpp build needs.
+- `stored()` and `remove()` cover the llama.cpp path's GGUFs in OPFS (`gguf/`).
+
+### Changed
+- diskformer pinned to v0.6.0 (439ad4e) for both its hand engines and the llama.cpp path.
+
+### Measured (Chrome, M4 Pro)
+- Granite 4.0 H Tiny through `diskformer-llama`: 9/9 replies identical to diskformer's reference
+  (`npm run test:browser -- llama-gate`).
+- Gemma 4 26B-A4B through `diskformer-llama`: 8/9 identical to llama.cpp b9830, the same 8/9 (miss: system-pirate)
+  diskformer records for its own Chrome run. The resolver still sends this repo to the hand engine.
+- Gemma 4 26B-A4B on the hand engine at the new pin: 9/9 identical (`diskformer-chat`).
+
+### Known gaps
+- `diskformer-llama`'s chat path does not turn thinking off: a model that reasons first (Gemma 4, Qwen3.6, gpt-oss)
+  begins its reply with its thought block. Closed in 0.2.1.
+
+## 0.1.0 — 2026-10-14
+
+The first release with code. `anyformer@0.0.1` reserved the name and held none.
+
+### Added
+- `plan(repo)` and `load(repo)`: read the Hub repo, probe the browser, ask every back end, run the best yes. A refusal
+  carries a closed code (`format`, `model`, `task`, `webgpu`, `f16`, `opfs`, `budget`, `threw`) and one remedy in `REFUSALS`.
+- Five back ends:
+  - `transformers`: transformers.js 4.3.1. Text generation, image and audio chat (Gemma 4, Qwen3.5), embeddings,
+    speech to text, detection, classification, depth, segmentation.
+  - `kohra`: text diffusion (MDLM, BD3LM) over onnxruntime-web.
+  - `localmind`: LocalMind's hand-written WebGPU kernels (LFM2 / LFM2.5, Gemma 4 E2B / E4B, Ternary Bonsai 2).
+  - `wllama`: llama.cpp in WebAssembly for any other GGUF up to about 3.6 GB, on WebGPU or the CPU; files over 2 GB
+    split into OPFS shards once.
+  - `diskformer`: weights in OPFS, only what a step needs on the GPU (Gemma 4 26B-A4B from 2.5 GB, Qwen3.6 35B-A3B from 4 GB).
+- `MODELS`: models that pass a browser test, loadable by entry.
+- `pipeline(task, repo)`: transformers.js's call shape over any back end.
+- `stored()` and `remove(repo)`: what is downloaded in this browser, across every back end.
+- Coded errors: `AnyformerError` with a code from `ERROR_CODES`, checked with `isAnyformerError(e, code)`.
+- One `generate()` at a time per session, in call order.
+- Options: `load()` takes `task`, `maxCtx`, `dtype` and `signal`; `generate()` takes `maxNewTokens`, `repetitionPenalty`
+  and `signal`; each back end's `.source` (for example `kohraBackend.source`) overrides where its runtime loads from.
+- Pinned runtimes in `src/sources.js` (exact versions and commits); `npm run pin` moves them.
+- Agent face: 9 tools over one manifest, through WebMCP's `navigator.modelContext` or `window.anyformer.tools`.
+- The workbench (`examples/chat/`): pick a model, see the plan, then chat, compare embeddings or detect objects.
+
+### Measured (Chrome, M4 Pro, 24 GB)
+- 13 of 13 LocalMind Hub models plan at an 8 GB budget; 12 ran in a browser test.
+- 10 of 10 replies byte-identical with LocalMind direct on the same transformers.js pin.
+- Speed 0.99–1.02× LocalMind direct on the steady back ends.
+
+### Not tested yet
+Audio input blocks, abort mid-reply, speech / classification / depth / segmentation in a browser, any machine other
+than the M4 Pro, and Qwen3.6 35B-A3B (it needs more than this machine's 24 GB).

package/README.md

@@ -1,30 +1,120 @@
-# anyformer.js
+<h1 align="center">anyformer.js</h1>
 
-One call to run any model in a browser tab: it picks the back end that fits the model's format, architecture and your
-GPU budget.
+**One call to run a model in a browser tab: anyformer reads the repo, probes the browser, and picks the back end that
+fits the model's format, architecture and your GPU budget.**
+
+Plain ES modules, no build step, no dependencies to install. Chromium with WebGPU (GGUF models also run on the CPU). Weights stay in the user's own
+browser storage; no account, no server, no telemetry.
+
+[![license](https://img.shields.io/badge/license-MIT-555?style=flat-square)](LICENSE)
+[![dependencies](https://img.shields.io/badge/dependencies-none-555?style=flat-square)](package.json)
 
 ## Install
 
-Not usable yet. `anyformer@0.0.1` on npm is a name placeholder with no code.
+| How | Command |
+|---|---|
+| npm | `npm install anyformer` |
+| CDN | `import { load } from 'https://cdn.jsdelivr.net/npm/anyformer@0.1.0/+esm';` |
+| Copy | `index.js` and `src/`; nothing else is needed |
+
+```js
+import { load } from 'anyformer';
+
+const chat = await load('onnx-community/Qwen2.5-0.5B-Instruct', { budget: 2.5e9, onProgress: console.log });
+for await (const { text } of chat.generate([{ role: 'user', content: 'What does a CPU do?' }], { maxNewTokens: 64 }))
+  show(text);
+```
+
+Every session has `run(input)`: chat messages for text generation (content a string, or blocks such as
+`[{ type: 'image', image }, { type: 'text', text }]` for Gemma 4 and Qwen3.5), a string or strings for embeddings, ImageData for
+vision, 16 kHz samples for speech. `load(repo, { task })` picks a task when a repo has more than one. The first load
+downloads the weights into the browser; later loads read them from there. Each back end's runtime loads
+from jsDelivr only when that back end is chosen.
+
+## Try it
+
+Serve the repo and open the workbench: pick a model, see which back end anyformer chose and why every other one
+refused, then chat (with an image for the vision models), compare embeddings, or detect objects; remove downloads.
+
+```bash
+python3 -m http.server 8000      # then open http://localhost:8000/examples/chat/
+```
+
+## Why
+
+You have a model id and a browser tab. Whether it runs depends on its format (ONNX, GGUF), its architecture, whether it
+is autoregressive or diffusion, and how much GPU memory the tab can take. Each runtime covers part of that, and you
+find out which part by failing to load.
+
+anyformer asks every back end first. `plan(repo)` returns the model's description, the browser's capabilities and each
+back end's answer: yes with an estimate (GPU bytes, disk bytes, tok/s when measured), or no with a code and a reason.
+`load(repo)` runs the best yes.
+
+## Back ends
+
+| Back end | Runs | Models |
+|---|---|---|
+| `transformers` | transformers.js 4.3.1: text generation, image and audio chat (Gemma 4, Qwen3.5), embeddings, speech to text, detection, classification, depth, segmentation | ONNX repos in the onnx-community / Xenova layout |
+| `kohra` | kohra, text-diffusion over onnxruntime-web | MDLM and BD3LM repos tagged `text-diffusion` |
+| `localmind` | LocalMind's hand-written WebGPU kernels, the whole model on the GPU | any LFM2 / LFM2.5 GGUF; Gemma 4 E2B / E4B QAT-mobile; Ternary Bonsai 2 |
+| `wllama` | llama.cpp in WebAssembly: WebGPU when the budget holds the model, the CPU otherwise (no WebGPU needed) | any GGUF up to about 3.6 GB that no engine above covers; files over 2 GB are split into OPFS shards once |
+| `diskformer` | diskformer engines: weights in OPFS, only what a step needs on the GPU | Gemma 4 26B-A4B (from 2.5 GB), Qwen3.6 35B-A3B (from 4 GB), Ling 3.0 Flash 124B (from 6.8 GB), MiniCPM-V 4.7 with images (from 4 GB) |
+| `diskformer-llama` | diskformer's llama.cpp build with WebGPU, mixture-of-experts layers paged in from OPFS | GGUFs of the 17 MoE architectures diskformer has checked (Granite 4.0 H, gpt-oss, GLM-4.7-Flash, LFM2 MoE…); a hand engine above wins where it covers the model |
+
+Each runtime loads from an exact version or commit in [src/sources.js](src/sources.js); set a back end's `.source`
+(for example `kohraBackend.source`) to load another copy. `BACKENDS` lists the back ends `load()` asks by default: each joins after its browser test passes.
+
+## When no back end can run it
+
+`load()` throws an `AnyformerError` with code `NO_BACKEND` and the plan, naming each back end, its code and its
+reason. Codes are a closed set, each with one remedy in `REFUSALS`: `format`, `model`, `task`, `webgpu`, `f16`, `opfs`, `budget` (with `need`, the budget that would pass)
+and `threw`. Every other failure is an `AnyformerError` too, with a code from `ERROR_CODES` (`LOAD_FAILED`,
+`BUDGET_TOO_SMALL`, `ABORTED`, `EXECUTION_FAILED`, `INVALID_ARGUMENT`, `DISPOSED`); check it with
+`isAnyformerError(e, code)`. A session runs one `generate()` at a time, in call order.
 
-## What it is
+## Commands
 
-A superset runtime for in-browser inference. `load(modelId, { budget })` probes the browser (WebGPU features, GPU
-budget, OPFS quota, memory64), resolves the model to a back end, and exposes one generate / pipeline API:
+```js
+plan(repo, { budget, task })      // what would run it, and why the others would not; loads nothing
+load(repo, { budget, task, file, maxCtx, poolBytes, localFile, onProgress, signal })  // → { backend, task, plan, run(input), generate?, think?, prime?, dispose() }
+pipeline(task, repo, { budget })  // transformers.js's call shape: gen(messages) → [{ generated_text }]
+probe()                           // WebGPU, shader-f16, subgroups, limits, OPFS quota, memory64
+describe(repo)                    // Hub repo → formats, architecture, task, tags, files
+resolve(model, caps, backends, { budget })  // rank back ends for a described model
+stored() · remove(repo)           // what is downloaded in this browser; delete one
+MODELS.chat.DEFAULT               // models that pass a browser test; load(MODELS.chat.GEMMA4_26B_A4B) works too
+registerTools()                   // publish the agent face (below)
+```
 
-- **transformers.js** — ONNX, breadth across modalities.
-- **diskformer** — models larger than GPU memory: weights in OPFS, only what each step needs on the GPU.
-- **llama.cpp on WebGPU + diskformer** — GGUF across llama.cpp's architectures (after the diskformer spike).
-- **LocalMind's hand engines** — the fastest path on the few models they cover.
+Agents get the same calls as tools (`anyformer_models`, `_probe`, `_plan`, `_load`, `_generate`, `_sessions`, `_unload`,
+`_stored`, `_remove`) through
+WebMCP's `navigator.modelContext` where the browser has it and `window.anyformer.tools` otherwise; `anyformer_load`
+loads nothing until the caller accepts the plan's disk bytes, and `anyformer_remove` deletes nothing without
+`confirm: true`.
 
-One model store (diskformer's OPFS layer) serves every back end, so a model downloads once.
+## Verify it yourself
 
-## Context
+```bash
+npm test                                   # Node: probe, describe, resolver, back-end verdicts, agent face
+npm run test:browser -- probe              # headless Chrome: WebGPU, f16, OPFS
+npm run test:browser -- transformers       # Qwen2.5-0.5B answers on topic
+npm run test:browser -- kohra              # Qwen3-0.6B MDLM answers on topic
+npm run test:browser -- embed             # MiniLM embeddings rank a paraphrase above an unrelated sentence
+npm run test:browser -- detect            # DETR finds both cats in cats.jpg
+npm run test:browser -- examples/chat/index.html --query "auto=1"   # the workbench loads and answers
+npm run test:browser -- pipeline --port 8192 --profile ~/.cache/anyformer-chat-profile   # pipeline() on a GGUF
+npm run test:browser -- store             # list a download, remove it
+npm run test:browser -- chat --query "repo=LiquidAI/LFM2.5-1.2B-Instruct-GGUF"   # a LocalMind engine
+npm run test:browser -- vision --query "repo=onnx-community/Qwen3.5-4B-ONNX-OPT"   # names the two cats
+npm run test:browser -- diskformer-chat    # Gemma 4 26B-A4B at 2.5 GB: 9/9 replies identical to llama.cpp b9830
+npm run test:browser -- llama-gate --query "repo=ibm-granite/granite-4.0-h-tiny-GGUF&refs=diskformer-granite-refs"   # 9/9 via diskformer-llama
+```
 
-Scaffolded 2026-10-07 from the diskformer.js proposal
-(`diskformer.js/plan/coverage-and-superset-proposal-2026-10.md`, §4). It depends on diskformer; diskformer never depends
-on it. Tier: Product.
+The browser tests fail a reply that is off topic or repeats itself, and `diskformer-chat` fails any reply that differs
+from llama.cpp's by one character. Only Apple silicon (M4 Pro, Chrome) has run them. Not tested yet: audio input blocks, abort mid-reply, speech / classification / depth / segmentation in a browser, any
+machine other than the M4 Pro, and Qwen3.6 35B-A3B (it needs more than that machine's 24 GB).
 
 ## License
 
-MIT
+MIT. Spec and agent contract: [SPEC.md](SPEC.md) · depends on [diskformer.js](https://github.com/NakliTechie/diskformer.js)
+· [kohra](https://github.com/NakliTechie/kohra) · [LocalMind](https://github.com/NakliTechie/LocalMind)

package/SPEC.md

@@ -0,0 +1,68 @@
+# anyformer.js — spec
+
+Tier: Product (several back ends, a resolver, one store). anyformer depends on diskformer and kohra; neither depends on
+anyformer.
+
+## §0 Agent contract (DRIVER v0.1 pass, 2026-10-08)
+
+The driver: an agent in a browser tab (or a script) that must run a model it names by repo id, with no idea which
+runtime fits, how much GPU memory the tab may take, or whether a download is 0.5 GB or 36 GB. It is context-poor, may
+be killed mid-turn, and must not burn a user's disk or bandwidth by guessing.
+
+1. **One perception act: `anyformer_plan` (`plan()`).** One call returns the model's formats, architecture and task,
+   the browser's caps, the budget, the chosen back end, and every back end's verdict. The agent never probes or
+   fetches separately before deciding.
+2. **Closed vocabularies.** Errors from load() and a session are `AnyformerError` with `code` in `ERROR_CODES`
+   (NO_BACKEND · LOAD_FAILED · BUDGET_TOO_SMALL+need · ABORTED · EXECUTION_FAILED · INVALID_ARGUMENT · DISPOSED),
+   checked by name and code (`isAnyformerError`), so two copies of the library agree. A refusal is `{code, reason, need?}` with `code` in `REFUSALS`: format · model · task · webgpu ·
+   f16 · opfs · budget · threw. Each code has one remedy (`REFUSALS[code]`); `budget` carries `need`, the bytes that
+   would pass. Tool consequences are `read` · `stages` · `mutates`. Tool errors are `{error}` data, never throws.
+3. **One verdict per next action.** `chosen` set → load. `chosen` null → read the codes: format/model → another repo;
+   webgpu/f16/opfs → another browser or GPU (nothing in this tab fixes it); budget → re-plan with `need`; threw → a bug.
+4. **Bounded output.** `anyformer_plan` grows with the number of back ends, never with the repo's file count (the file
+   list stays out). The journal holds the last 50 calls. `generate` returns one reply.
+5. **Every failure names its remedy.** NO_BACKEND lists each back end with its code and reason; `REFUSALS[code]`
+   is the next move.
+6. **Crash-safe and idempotent.** A session runs one generate at a time; dispose() waits for it and is idempotent. `plan` and `probe` have no side effects. Weights land in OPFS through diskformer's
+   resumable ingest (an interrupted download resumes); transformers.js and kohra use the browser HTTP cache. Loading
+   twice loads twice; it never corrupts a store.
+7. **The tool holds the memory.** `anyformer_sessions` renders the open sessions and the last 50 tool calls with the
+   door each came through (`direct`, `window`, `modelContext`).
+8. **Accretion.** A back end joins `BACKENDS` only after its browser test passes (test/registry.test.js pins the list);
+   every escaped wrong answer becomes a browser-test check (the transformers.js q4f16 word salad became `onTopic`).
+9. **The tower.** One line per layer; each reads only the one below.
+   - `probe` (browser caps) · `describe` (Hub repo → descriptor)
+   - back ends: `canRun` (pure, descriptor + caps) · `load` → session
+   - `resolve` (rank the verdicts) → `plan` (probe + describe + resolve) → `load` (plan + back-end load)
+   - agent face: `TOOLS` manifest → `call` → WebMCP `registerTool` / `window.anyformer.tools`
+10. **The evaluator stays outside.** The browser tests (test/browser/) judge back ends against fixed references:
+    llama.cpp b9830 replies for diskformer, an on-topic check for transformers.js and kohra. A page that times out
+    exits 2 (indeterminate), never 0. Staging is enforced in the tool, not left to the agent: `anyformer_load` loads
+    nothing unless `acceptDiskBytes` covers the plan's disk bytes.
+
+Self-check: perception act ✓ · closed vocabularies ✓ · output bound ✓ · crash-safety ✓ · trajectory ✓ · accretion ✓ ·
+tower ✓ · evaluator boundary ✓.
+
+## What shipped (Batch A)
+
+- `load(repo, {budget, maxCtx, backends, onProgress, signal})` → `{backend, plan, generate(messages, {maxNewTokens, signal}),
+  dispose()}`; `generate` yields `{text, tokens}`, `text` cumulative.
+- Tasks: `plan/load(repo, { task })`, default the repo's pipeline tag; every session has `run(input)`, text generation
+  also `generate()`. Back ends list their `tasks`.
+- Back ends: transformers.js 4.3.1 (ONNX text-generation, q4 first), kohra @main (text-diffusion ONNX), diskformer
+  @main (pinned Gemma 4 26B-A4B and Qwen3.6 35B-A3B GGUFs). transformers.js also runs feature-extraction, speech recognition, object
+  detection, image classification, depth, segmentation, token and text classification on fp32 graphs. kohra and diskformer load from their main branches;
+  `<backend>.source` pins another copy.
+- transformers.js also runs Gemma 4 and Qwen3.5 ONNX as chat with image (and, for Gemma 4, audio) blocks, through
+  their conditional-generation classes at q4f16, as LocalMind does.
+- localmind @main: LocalMind's hand-written engines, matched by architecture and format (lfm2 GGUF, Gemma 4
+  QAT-mobile, qwen35 Prism ternary); resident on the GPU, so budget ≥ file size.
+- wllama 3.4.1 (LocalMind's pin): any GGUF ≤ ~3.6 GB no architecture engine covers (a repo's split set as is; a
+  single file over 2 GB split once into OPFS shards, src/gguf-split.js); WebGPU when the budget
+  holds it, CPU otherwise. Thinking off (chat_template_kwargs). Ranks last.
+- Pins: src/sources.js holds exact versions and commits; `npm run pin` moves the git pins to each repo's main.
+- Agent face: 9 tools (models, probe, plan, load, generate, sessions, unload, stored, remove). Person-only acts: none.
+- `MODELS`: tested entries by family; `load(entry)`. `stored()` / `remove(repo)` over the transformers.js cache and
+  diskformer's OPFS stores.
+- Gaps: no wasm fallback (every back end needs WebGPU); one store per back end, not the shared OPFS store yet (kohra's graph is in the HTTP cache, unlisted);
+  llama.cpp-webgpu not started; speed estimates exist for diskformer only.

package/index.js

@@ -0,0 +1,17 @@
+// anyformer — one call to run any model in a browser tab. Plain ESM, no build step.
+export { load, plan, BACKENDS, DEFAULT_BUDGET } from './src/load.js';
+export { AnyformerError, isAnyformerError, ERROR_CODES } from './src/errors.js';
+export { probe, memory64 } from './src/probe.js';
+export { describe, fromHubInfo } from './src/describe.js';
+export { resolve, REFUSALS } from './src/resolve.js';
+export { transformersBackend } from './src/backends/transformers.js';
+export { kohraBackend } from './src/backends/kohra.js';
+export { diskformerBackend, DISKFORMER_MODELS } from './src/backends/diskformer.js';
+export { diskformerLlamaBackend, LLAMA_ARCHITECTURES } from './src/backends/diskformer-llama.js';
+export { TOOLS, call, registerTools, journal, toolOptions } from './src/tools.js';
+export { MODELS } from './src/models.js';
+export { stored, remove } from './src/store.js';
+export { pipeline } from './src/pipeline.js';
+export { localmindBackend } from './src/backends/localmind.js';
+export { wllamaBackend } from './src/backends/wllama.js';
+export { PINS, SOURCES } from './src/sources.js';

package/package.json

@@ -1,13 +1,48 @@
 {
   "name": "anyformer",
-  "version": "0.0.1",
-  "description": "One call to run any model in a browser tab: picks the back end that fits the model's format, architecture and your GPU budget. Pre-release name placeholder; no code yet.",
+  "version": "0.3.1",
+  "description": "One call to run a model in a browser tab: anyformer reads the Hub repo, probes the browser, and picks the back end (transformers.js, LocalMind's WebGPU kernels, diskformer, kohra) that fits the model's format, architecture and your GPU budget.",
   "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SPEC.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test 'test/*.test.js'",
+    "test:browser": "node test/browser/run.mjs",
+    "pin": "node scripts/pin-sources.mjs"
+  },
+  "keywords": [
+    "agent",
+    "browser",
+    "diffusion",
+    "diskformer",
+    "gguf",
+    "inference",
+    "llm",
+    "localmind",
+    "onnx",
+    "transformers",
+    "webgpu",
+    "webmcp"
+  ],
   "license": "MIT",
   "author": "Chirag Patnaik",
   "homepage": "https://github.com/NakliTechie/anyformer.js#readme",
-  "repository": { "type": "git", "url": "git+https://github.com/NakliTechie/anyformer.js.git" },
-  "bugs": { "url": "https://github.com/NakliTechie/anyformer.js/issues" },
-  "keywords": ["webgpu", "llm", "inference", "browser", "transformers", "gguf", "onnx", "diskformer"],
-  "files": ["README.md", "LICENSE"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NakliTechie/anyformer.js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NakliTechie/anyformer.js/issues"
+  }
 }

package/src/backends/diskformer-llama.js

@@ -0,0 +1,161 @@
+// diskformer-llama: mixture-of-experts GGUFs through diskformer's llama.cpp path (diskformer/llama: llama.cpp with
+// WebGPU in a worker, the experts paged in from OPFS on demand). One engine for every architecture diskformer has
+// checked in Chrome, so a new MoE model of a covered architecture needs no anyformer code. Where diskformer also has a
+// hand-written engine for the model (the diskformer back end), that one carries a measured speed and ranks first.
+// llama.js loads from the CDN at load() time, at the commit src/sources.js pins; set diskformerLlamaBackend.source to
+// load another copy.
+
+import { AnyformerError } from '../errors.js';
+import { SOURCES } from '../sources.js';
+
+// Architectures that pass diskformer's two checks (docs/coverage.md at the pinned commit): paging is exact natively,
+// and the Chrome replies are compared with llama.cpp. Other models of the same architecture are expected to run.
+// Left out: hy_v3 and afmoe (run, below diskformer's bar), laguna (unknown tokens), dense architectures (no experts
+// to page), and Mixtral-style `llama` MoE (runs, too slow to use).
+export const LLAMA_ARCHITECTURES = [
+  'gemma4', 'qwen3moe', 'qwen3next', 'qwen35moe', 'qwen3vlmoe', 'deepseek2', 'nemotron_h_moe', 'ernie4_5-moe',
+  'gpt-oss', 'cohere2moe', 'lfm2moe', 'mellum', 'bailingmoe2', 'granitehybrid', 'bailingmoe3', 'flint', 'olmoe',
+];
+
+// Quant preference by the token in the file name; the first one the repo has wins. The files diskformer checked are
+// Q4_K_M, Q4_0, Q4_1, MXFP4 and Q3_K_M.
+const QUANTS = ['Q4_K_M', 'Q4_0', 'Q4_1', 'MXFP4', 'Q3_K_M', 'Q4_K_S', 'Q5_K_M', 'Q5_K_S', 'Q6_K', 'Q8_0'];
+
+// The exact files diskformer checked (ggml/chat.html CATALOG and docs/coverage.md at the pinned commit). When a repo
+// holds one, it is the default: the coverage numbers were measured on that file.
+export const CHECKED_FILES = [
+  'gemma-4-26B_q4_0-it.gguf', 'Qwen3-30B-A3B-Instruct-2507-Q3_K_M.gguf', 'Qwen3-Next-80B-A3B-Instruct-Q4_K_M.gguf',
+  'Qwen3.6-35B-A3B-UD-Q3_K_M.gguf', 'Qwen3-VL-30B-A3B-Instruct-Q3_K_M.gguf', 'GLM-4.7-Flash-Q3_K_M.gguf',
+  'NVIDIA-Nemotron-3-Nano-30B-A3B-Q4_K_M.gguf', 'ERNIE-4.5-21B-A3B-Thinking-Q4_K_M.gguf', 'gpt-oss-20b-MXFP4.gguf',
+  'North-Mini-Code-1.0-UD-Q3_K_M.gguf', 'LFM2.5-24B-A2B-QAD-Q4_0.gguf', 'LFM2-8B-A1B-Q4_K_M.gguf',
+  'Mellum2-12B-A2.5B-Instruct-Q4_K_M.gguf', 'Ling-mini-2.0-Q4_K_M.gguf', 'granite-4.0-h-tiny-Q4_K_M.gguf',
+  'Ling-3.0-tiny-Q4_K_M.gguf', 'flint-int4-q4_1.gguf', 'OLMoE-1B-7B-0125-Instruct-Q4_K_M.gguf',
+];
+
+// The GGUF to load: the language model (no mmproj vision tower), one file (no split sets). The caller's file when
+// given; else the file diskformer checked; else the preferred quant.
+export function pickGguf(model, file = null) {
+  const lms = model.files.gguf.filter((f) => !/mmproj/i.test(f.name) && !/-\d{5}-of-\d{5}\.gguf$/.test(f.name));
+  if (file) return lms.find((f) => f.name === file) || null;
+  const checked = lms.find((f) => CHECKED_FILES.includes(f.name.split('/').pop()));
+  if (checked) return checked;
+  for (const q of QUANTS) {
+    const f = lms.find((x) => new RegExp(`(^|[-_.])${q}([-_.]|$)`, 'i').test(x.name.replace(/\.gguf$/i, '')));
+    if (f) return f;
+  }
+  return null;
+}
+
+// OPFS keeps llama.cpp's GGUFs by file name (gguf/<name>), with no repo. anyformer records name → repo here, so
+// stored() can say which repo a file belongs to.
+export const LLAMA_INDEX = 'anyformer-llama.json';
+async function readIndex() {
+  try { return JSON.parse(await (await (await (await navigator.storage.getDirectory()).getFileHandle(LLAMA_INDEX)).getFile()).text()); } catch { return {}; }
+}
+async function writeIndex(index) {
+  const h = await (await navigator.storage.getDirectory()).getFileHandle(LLAMA_INDEX, { create: true });
+  const w = await h.createWritable();
+  await w.write(JSON.stringify(index));
+  await w.close();
+}
+export { readIndex as readLlamaIndex };
+
+// Chat content: a string, or text blocks joined. llama.cpp's chat here takes text only.
+function textOnly(messages) {
+  return messages.map((m) => {
+    if (typeof m.content === 'string') return m;
+    const other = m.content.find((b) => b.type !== 'text');
+    if (other) throw new AnyformerError('INVALID_ARGUMENT', `diskformer-llama runs text only; got a ${other.type} block`);
+    return { ...m, content: m.content.map((b) => b.text).join('\n') };
+  });
+}
+
+export const diskformerLlamaBackend = {
+  id: 'diskformer-llama',
+  tasks: ['text-generation', 'image-text-to-text'],
+  source: SOURCES.diskformerLlama,
+  // Where a GGUF downloads from; a test points it at a local server.
+  url: (model, file) => `${model.endpoint || 'https://huggingface.co'}/${model.repo}/resolve/${model.revision || 'main'}/${file.name.split('/').map(encodeURIComponent).join('/')}`,
+
+  canRun(model, caps, { budget, task, file = null }) {
+    if (!model.formats.includes('gguf')) return { ok: false, code: 'format', reason: 'no GGUF in the repo' };
+    if (task && !diskformerLlamaBackend.tasks.includes(task)) return { ok: false, code: 'task', reason: `task ${task}; diskformer's llama.cpp path runs text generation only` };
+    if (!LLAMA_ARCHITECTURES.includes(model.architecture)) return { ok: false, code: 'model', reason: `architecture ${model.architecture || 'unknown'} is not one diskformer's llama.cpp path has checked (${LLAMA_ARCHITECTURES.join(', ')})` };
+    const f = pickGguf(model, file);
+    if (!f) return { ok: false, code: 'model', reason: file ? `${file} is not a single-file language-model GGUF in the repo` : `no single-file GGUF at ${QUANTS.join(', ')} in the repo` };
+    if (!caps.webgpu) return { ok: false, code: 'webgpu', reason: 'no WebGPU adapter' };
+    if (!caps.memory64 || !caps.jspi) return { ok: false, code: 'webgpu', reason: 'the llama.cpp build needs wasm memory64 and JSPI (Chrome or Edge 137+)' };
+    if (!caps.opfs) return { ok: false, code: 'opfs', reason: 'no OPFS (navigator.storage.getDirectory)' };
+    // The budget is not checked here: llama.cpp plans its expert slots from it at load time, and refuses there.
+    return { ok: true, estimate: { gpuBytes: budget, diskBytes: f.size, tokPerSec: null } };
+  },
+
+  // maxCtx sizes the KV cache; 1024 is the context diskformer's gates run at.
+  async load(model, { budget, file = null, maxCtx = 1024, onProgress, signal }) {
+    const f = pickGguf(model, file);
+    const { Llama } = await import(diskformerLlamaBackend.source);
+    const llama = new Llama();
+    const say = (e) => onProgress?.({ backend: 'diskformer-llama', file: f.name, ...e });
+    const stop = () => llama.abort();
+    signal?.addEventListener('abort', stop, { once: true });
+    let info;
+    try {
+      const have = (await llama.list()).find((m) => m.name === f.name && !m.partial);
+      if (!have || have.size !== f.size) {
+        say({ status: 'download', loaded: 0, total: f.size });
+        await llama.download({ url: diskformerLlamaBackend.url(model, f), name: f.name, size: f.size },
+          (p) => say({ status: 'download', loaded: p.copied, total: p.total }));
+        signal?.throwIfAborted();
+      }
+      await writeIndex({ ...(await readIndex()), [f.name]: model.repo });
+      say({ status: 'load' });
+      info = await llama.load({ name: f.name, budget, ctx: maxCtx }, (p) => say({ status: 'plan', plan: p }));
+      signal?.throwIfAborted();
+    } catch (e) {
+      llama.terminate();
+      throw e;
+    } finally {
+      signal?.removeEventListener('abort', stop);
+    }
+    say({ status: 'ready', slots: info.slots });
+    return {
+      task: 'text-generation',
+      llama,
+      info,
+      // llama.cpp hands back text pieces, not token ids, so there are no think ids to report.
+      think: null,
+      // thinking: false (the default, as the other engines here) renders the template with thinking off, so a model that
+      // reasons first answers directly; true lets it think.
+      async *generate(messages, { maxNewTokens = 512, signal, thinking = false } = {}) {
+        const chunks = [];
+        let wake = null, finished = false, failed = null, result = null, text = '', tokens = 0;
+        const nudge = () => { wake?.(); wake = null; };
+        const abort = () => llama.abort();
+        signal?.addEventListener('abort', abort, { once: true });
+        const job = llama.chat(textOnly(messages), {
+          n: maxNewTokens, thinking,
+          onPiece: (s) => { text += s; tokens++; chunks.push({ text, tokens }); nudge(); },
+        }).then((r) => { result = r; }, (e) => { failed = e; }).finally(() => { finished = true; nudge(); });
+        try {
+          for (;;) {
+            while (chunks.length) yield chunks.shift();
+            if (finished) break;
+            await new Promise((r) => { wake = r; });
+          }
+          signal?.throwIfAborted();
+          if (failed) throw failed;
+          const s = result.stats || {};
+          const decode = s.decode_tokens && s.decode_ms ? s.decode_tokens / (s.decode_ms / 1000) : null;
+          yield { text: result.text, tokens: s.decode_tokens ?? tokens, ...(decode && { tokPerSec: decode }) };
+        } finally {
+          signal?.removeEventListener('abort', abort);
+          // The caller stopped reading early: stop the reply so the next call does not queue behind it.
+          if (!finished) { llama.abort(); await job; }
+        }
+      },
+      // A continuation of an already formatted prompt, greedy: what diskformer's gate replays.
+      complete: (prompt, { maxNewTokens = 64 } = {}) => llama.complete(prompt, { n: maxNewTokens }),
+      dispose: () => llama.terminate(),
+    };
+  },
+};