anyformer 0.0.1 → 0.3.1

package/src/describe.js

@@ -0,0 +1,47 @@
+// A model descriptor from a Hugging Face repo id: which weight formats the repo holds, their files and sizes, and the
+// architecture. Back ends decide from this alone; describe() never decides who runs a model.
+
+const HF = 'https://huggingface.co';
+
+// The last answer the Hub gave for each URL, kept in Cache Storage so a model already downloaded still loads offline.
+export const DESCRIBE_CACHE = 'anyformer-describe-v1';
+
+export async function describe(repo, { fetch = globalThis.fetch, revision = 'main', endpoint = HF, caches = globalThis.caches } = {}) {
+  const url = `${endpoint}/api/models/${repo}${revision === 'main' ? '' : `/revision/${revision}`}?blobs=true`;
+  const store = caches ? await caches.open(DESCRIBE_CACHE).catch(() => null) : null;
+  let res, failed;
+  try { res = await fetch(url); } catch (e) { failed = e; }
+  if (res?.ok) {
+    const info = await res.json();
+    await store?.put(url, new Response(JSON.stringify(info), { headers: { 'Content-Type': 'application/json' } })).catch(() => {});
+    return fromHubInfo(info, { endpoint });
+  }
+  // No network, or the Hub failed: the cached answer, when this browser has one.
+  const hit = await store?.match(url).catch(() => null);
+  if (hit) return fromHubInfo(await hit.json(), { endpoint });
+  throw failed ? new Error(`describe ${repo}: ${url} failed: ${failed.message}`, { cause: failed })
+    : new Error(`describe ${repo}: ${url} returned ${res.status}`);
+}
+
+// Pure: Hub API JSON → descriptor. Exported for tests and for callers that already hold the JSON.
+export function fromHubInfo(info, { endpoint = HF } = {}) {
+  const files = (info.siblings || []).map((s) => ({ name: s.rfilename, size: s.size ?? null }));
+  const gguf = files.filter((f) => f.name.endsWith('.gguf'));
+  const onnx = files.filter((f) => f.name.endsWith('.onnx'));
+  const safetensors = files.filter((f) => f.name.endsWith('.safetensors'));
+  const formats = [gguf.length && 'gguf', onnx.length && 'onnx', safetensors.length && 'safetensors'].filter(Boolean);
+  return {
+    repo: info.id,
+    revision: info.sha || null,
+    endpoint,
+    formats,
+    // GGUF repos report the architecture in the gguf block; transformers repos in config.model_type.
+    architecture: info.gguf?.architecture || info.config?.model_type || null,
+    task: info.pipeline_tag || null,
+    // Hub tags carry what format and architecture miss, e.g. 'text-diffusion' marks a kohra model.
+    tags: info.tags || [],
+    // all: every file, for the side files a format splits off (ONNX external data, tokenizers).
+    files: { gguf, onnx, safetensors, all: files },
+    ggufTotalBytes: info.gguf?.total ?? null,
+  };
+}

package/src/errors.js

@@ -0,0 +1,36 @@
+// Every error load() and a session throw is an AnyformerError with a code from ERROR_CODES. Callers branch on the
+// code; the message is for people and can change. (Back-end refusals before loading are REFUSALS in resolve.js.)
+
+export const ERROR_CODES = {
+  NO_BACKEND: 'no back end can run the model under this budget; err.plan.candidates holds each code and reason',
+  LOAD_FAILED: 'the repo lookup, a download or the back end failed while loading; err.cause holds the original error',
+  BUDGET_TOO_SMALL: 'the back end measured the model at load time and the budget does not cover it; retry with err.need',
+  ABORTED: 'the AbortSignal fired; err.cause holds its reason',
+  EXECUTION_FAILED: 'the back end failed while generating; err.cause holds the original error',
+  INVALID_ARGUMENT: 'a value passed by the caller is wrong',
+  DISPOSED: 'the session was disposed; load the model again',
+};
+
+export class AnyformerError extends Error {
+  constructor(code, message, { cause, ...extra } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+// On the prototype, so stack traces say AnyformerError.
+AnyformerError.prototype.name = 'AnyformerError';
+
+// By name and code, not instanceof: a page can hold two copies of anyformer (CDN imports), and the check still holds.
+export function isAnyformerError(e, code) {
+  return e instanceof Error && e.name === 'AnyformerError' && e.code in ERROR_CODES && (code === undefined || e.code === code);
+}
+
+// Any error into an AnyformerError. An aborted signal wins: fetch rejects with the abort reason, which is not always
+// an AbortError. An AnyformerError keeps its code; anything else gets `code` (the step that failed).
+export function wrap(e, code, signal, where = '') {
+  if (signal?.aborted) return isAnyformerError(e, 'ABORTED') ? e : new AnyformerError('ABORTED', `${where}aborted`, { cause: signal.reason });
+  if (isAnyformerError(e)) return e;
+  if (e?.name === 'AbortError') return new AnyformerError('ABORTED', `${where}aborted`, { cause: e });
+  return new AnyformerError(code, `${where}${e?.message ?? e}`, { cause: e });
+}

package/src/gguf-split.js

@@ -0,0 +1,160 @@
+// A GGUF too big for one ArrayBuffer (wllama reads files of at most 2 GB) becomes shards in llama.cpp's gguf-split
+// layout, the same files `llama-gguf-split --split-max-size` writes: shard 1 carries every metadata key, each shard
+// carries split.no / split.count / split.tensors.count and its own tensor table, and each shard's data section holds
+// its tensors with offsets relative to it. Tensor bytes are copied, never decoded, so any quant type works.
+
+const MAGIC = 0x46554747;                   // 'GGUF'
+const DEFAULT_ALIGNMENT = 32;
+// GGUF metadata value types → byte size (fixed-size types only; 8 = string, 9 = array).
+const SIZE = { 0: 1, 1: 1, 2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 10: 8, 11: 8, 12: 8 };
+
+class Short extends Error {}                // the header runs past the bytes read so far
+
+// Parse a GGUF header from its first bytes. Returns the raw metadata bytes (copied verbatim into shard 1), the tensor
+// table, the alignment and where the data section starts. Throws Short when `u8` stops inside the header.
+export function parseHeader(u8) {
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+  let p = 0;
+  const need = (n) => { if (p + n > u8.byteLength) throw new Short(); };
+  const u32 = () => { need(4); const v = dv.getUint32(p, true); p += 4; return v; };
+  const u64 = () => { need(8); const v = dv.getBigUint64(p, true); p += 8; return Number(v); };
+  const str = () => { const n = u64(); need(n); const s = new TextDecoder().decode(u8.subarray(p, p + n)); p += n; return s; };
+  const skip = (type) => {
+    if (type === 8) { const n = u64(); need(n); p += n; return; }
+    if (type === 9) { const t = u32(), n = u64(); if (t in SIZE) { need(n * SIZE[t]); p += n * SIZE[t]; } else for (let i = 0; i < n; i++) skip(t); return; }
+    need(SIZE[type]); p += SIZE[type];
+  };
+  if (u32() !== MAGIC) throw new Error('not a GGUF file');
+  const version = u32();
+  if (version < 2) throw new Error(`GGUF version ${version} is not supported`);
+  const tensorCount = u64(), kvCount = u64();
+  const kvStart = p;
+  let alignment = DEFAULT_ALIGNMENT;
+  for (let i = 0; i < kvCount; i++) {
+    const key = str(), type = u32();
+    if (key === 'general.alignment' && type === 4) { need(4); alignment = dv.getUint32(p, true); }
+    if (key.startsWith('split.')) throw new Error(`already a shard (${key})`);
+    skip(type);
+  }
+  const kvBytes = u8.slice(kvStart, p);
+  const tensors = [];
+  for (let i = 0; i < tensorCount; i++) {
+    const name = str(), nDims = u32(), dims = [];
+    for (let d = 0; d < nDims; d++) dims.push(u64());
+    tensors.push({ name, dims, type: u32(), offset: u64() });
+  }
+  const dataStart = Math.ceil(p / alignment) * alignment;
+  return { version, kvCount, kvBytes, tensors, alignment, dataStart };
+}
+
+// Read the header through `read(start, end)` (bytes [start, end)), widening the window until it parses.
+export async function readHeader(read, fileSize) {
+  for (let n = 8 << 20; ; n *= 2) {
+    try { return parseHeader(await read(0, Math.min(n, fileSize))); } catch (e) {
+      if (!(e instanceof Short) || n >= fileSize) throw e;
+    }
+  }
+}
+
+// Group tensors (in data order) into shards of at most maxBytes of data each. A tensor's bytes run to the next
+// tensor's offset, so the original alignment padding travels with it and every copied offset stays aligned.
+export function planShards(header, fileSize, maxBytes) {
+  const t = [...header.tensors].sort((a, b) => a.offset - b.offset);
+  const dataSize = fileSize - header.dataStart;
+  const sized = t.map((x, i) => ({ ...x, bytes: (i + 1 < t.length ? t[i + 1].offset : dataSize) - x.offset }));
+  const shards = [];
+  let cur = null;
+  for (const x of sized) {
+    if (!cur || (cur.bytes + x.bytes > maxBytes && cur.tensors.length)) shards.push(cur = { tensors: [], bytes: 0 });
+    cur.tensors.push({ ...x, newOffset: cur.bytes });
+    cur.bytes += x.bytes;
+  }
+  for (const s of shards) { s.start = header.dataStart + s.tensors[0].offset; s.end = s.start + s.bytes; }
+  return shards;
+}
+
+// The header bytes of shard i of n: magic, version, counts, metadata (all of it in shard 0, split keys only in the
+// rest), this shard's tensor table, padding to the alignment.
+export function shardHeader(header, shards, i) {
+  const out = [];
+  const enc = new TextEncoder();
+  const u32 = (v) => { const b = new Uint8Array(4); new DataView(b.buffer).setUint32(0, v, true); out.push(b); };
+  const u64 = (v) => { const b = new Uint8Array(8); new DataView(b.buffer).setBigUint64(0, BigInt(v), true); out.push(b); };
+  const u16 = (v) => { const b = new Uint8Array(2); new DataView(b.buffer).setUint16(0, v, true); out.push(b); };
+  const i32 = (v) => { const b = new Uint8Array(4); new DataView(b.buffer).setInt32(0, v, true); out.push(b); };
+  const str = (s) => { const b = enc.encode(s); u64(b.length); out.push(b); };
+  const shard = shards[i];
+  u32(MAGIC); u32(header.version);
+  u64(shard.tensors.length);
+  u64((i === 0 ? header.kvCount : 0) + 3);
+  if (i === 0) out.push(header.kvBytes);
+  str('split.no'); u32(2); u16(i);
+  str('split.count'); u32(2); u16(shards.length);
+  str('split.tensors.count'); u32(5); i32(header.tensors.length);
+  for (const t of shard.tensors) {
+    str(t.name); u32(t.dims.length);
+    for (const d of t.dims) u64(d);
+    u32(t.type); u64(t.newOffset);
+  }
+  // Shards after the first carry no general.alignment, so llama.cpp reads them at the default 32.
+  const align = i === 0 ? header.alignment : DEFAULT_ALIGNMENT;
+  const len = out.reduce((n, b) => n + b.length, 0);
+  out.push(new Uint8Array(Math.ceil(len / align) * align - len));
+  const all = new Uint8Array(out.reduce((n, b) => n + b.length, 0));
+  let p = 0;
+  for (const b of out) { all.set(b, p); p += b.length; }
+  return all;
+}
+
+export const shardName = (base, i, n) => `${base}-${String(i + 1).padStart(5, '0')}-of-${String(n).padStart(5, '0')}.gguf`;
+
+// Split the GGUF at `url` into shards of at most maxBytes in OPFS (anyformer-gguf/<key>/), reading it with HTTP range
+// requests, and return the shards as Files in order. Crash-safe and resumable: a shard of the expected size is kept,
+// anything else is rewritten, and done.json is written last; with done.json present nothing is fetched.
+export const SPLIT_ROOT = 'anyformer-gguf';
+export async function splitToOpfs({ url, size, key, repo, file, maxBytes = 512 << 20, onProgress, signal, fetch: f = globalThis.fetch }) {
+  const root = await (await navigator.storage.getDirectory()).getDirectoryHandle(SPLIT_ROOT, { create: true });
+  const dir = await root.getDirectoryHandle(key, { create: true });
+  const files = async (names) => Promise.all(names.map(async (n) => (await dir.getFileHandle(n)).getFile()));
+  // meta.json first, so an interrupted split still names its repo (src/store.js lists and removes it).
+  const meta = await (await dir.getFileHandle('meta.json', { create: true })).createWritable();
+  await meta.write(JSON.stringify({ repo, file, url, size }));
+  await meta.close();
+  try {
+    const done = JSON.parse(await (await (await dir.getFileHandle('done.json')).getFile()).text());
+    if (done.url === url && done.size === size) return files(done.shards);
+  } catch { /* not split yet, or interrupted */ }
+  const range = async (s, e) => {
+    const r = await f(url, { headers: { Range: `bytes=${s}-${e - 1}` }, signal });
+    if (r.status !== 206 && !(r.ok && s === 0 && e >= size)) throw new Error(`${url}: range request returned ${r.status}`);
+    return r;
+  };
+  const header = await readHeader(async (s, e) => new Uint8Array(await (await range(s, e)).arrayBuffer()), size);
+  const shards = planShards(header, size, maxBytes);
+  const base = file.replace(/\.gguf$/i, '');
+  const names = shards.map((_, i) => shardName(base, i, shards.length));
+  let copied = 0;
+  for (const [i, s] of shards.entries()) {
+    const head = shardHeader(header, shards, i);
+    const expect = head.length + s.bytes;
+    const h = await dir.getFileHandle(names[i], { create: true });
+    if ((await h.getFile()).size === expect) { copied += s.bytes; continue; }
+    const w = await h.createWritable();           // commits atomically on close(); an abort leaves the old file
+    try {
+      await w.write(head);
+      const body = (await range(s.start, s.end)).body.getReader();
+      for (;;) {
+        const { done, value } = await body.read();
+        if (done) break;
+        await w.write(value);
+        copied += value.length;
+        onProgress?.({ status: 'split', file: names[i], loaded: copied, total: size - header.dataStart });
+      }
+      await w.close();
+    } catch (e) { await w.abort().catch(() => {}); throw e; }
+  }
+  const marker = await (await dir.getFileHandle('done.json', { create: true })).createWritable();
+  await marker.write(JSON.stringify({ url, size, repo, file, shards: names }));
+  await marker.close();
+  return files(names);
+}

package/src/load.js

@@ -0,0 +1,127 @@
+import { probe } from './probe.js';
+import { describe } from './describe.js';
+import { resolve } from './resolve.js';
+import { transformersBackend } from './backends/transformers.js';
+import { kohraBackend } from './backends/kohra.js';
+import { diskformerBackend } from './backends/diskformer.js';
+import { diskformerLlamaBackend } from './backends/diskformer-llama.js';
+import { localmindBackend } from './backends/localmind.js';
+import { wllamaBackend } from './backends/wllama.js';
+import { AnyformerError, wrap } from './errors.js';
+
+// Back ends land here as each one passes its browser test (test/browser/). The list order breaks ties: a
+// diskformer hand engine carries a measured speed and outranks diskformer-llama for the same model; diskformer-llama
+// comes before wllama because it pages experts instead of holding the whole model on the GPU.
+export const BACKENDS = [transformersBackend, kohraBackend, diskformerBackend, localmindBackend, diskformerLlamaBackend, wllamaBackend];
+
+// 2.5 GB: the smallest budget diskformer's chat gate passes at. Browsers do not report GPU memory, so a caller that
+// knows more passes { budget }.
+export const DEFAULT_BUDGET = 2.5e9;
+
+function noBackend(plan) {
+  const lines = plan.candidates.map((c) => `  ${c.backend} [${c.code}]: ${c.reason}`);
+  return new AnyformerError('NO_BACKEND', `no back end can run ${plan.model.repo} at a ${(plan.budget / 1e9).toFixed(1)} GB budget` +
+    (lines.length ? `:\n${lines.join('\n')}` : ': no back ends registered'), { plan });
+}
+
+// What load() would do, without loading: the descriptor, the caps, and every back end's answer.
+// task: a Hugging Face pipeline task ('text-generation', 'feature-extraction', …); null runs the repo's own.
+// file: a weights file in the repo to load (a GGUF name); null lets each back end pick.
+// repo: a Hub id, or an entry from MODELS (its task and budget apply unless opts set them).
+const entry = (repo, opts) => (typeof repo === 'object' && repo?.repo
+  ? [repo.repo, { ...(repo.task && { task: repo.task }), ...(repo.budget && { budget: repo.budget }), ...opts }]
+  : [repo, opts]);
+
+export async function plan(repoOrEntry, opts = {}) {
+  let [repo, { budget = DEFAULT_BUDGET, task = null, file = null, backends = BACKENDS, caps, model, fetch }] = entry(repoOrEntry, opts);
+  caps ??= await probe();
+  model ??= await describe(repo, fetch ? { fetch } : {});
+  return { model, caps, budget, task, file, ...(await resolve(model, caps, backends, { budget, task, file })) };
+}
+
+export async function load(repoOrEntry, options = {}) {
+  const [repo, opts] = entry(repoOrEntry, options);
+  const { backends = BACKENDS, maxCtx, dtype, poolBytes, localFile, onProgress, signal } = opts;
+  let p;
+  try { p = await plan(repo, opts); } catch (e) { throw wrap(e, 'LOAD_FAILED', signal, `${repo}: `); }
+  if (!p.chosen) throw noBackend(p);
+  const backend = backends.find((b) => b.id === p.chosen);
+  let session;
+  try {
+    session = await backend.load(p.model, { budget: p.budget, task: p.task, file: p.file, caps: p.caps, maxCtx, dtype, poolBytes, localFile, onProgress, signal });
+  } catch (e) { throw wrap(e, 'LOAD_FAILED', signal, `${backend.id}: `); }
+  return { backend: backend.id, task: session.task || p.task || p.model.task || null, ...(session.device && { device: session.device }), plan: p, ...serialize(session) };
+}
+
+// content: a string, or an array of { type, … } blocks (text, image, audio) for multimodal models.
+const validContent = (c) => typeof c === 'string' || (Array.isArray(c) && c.every((b) => typeof b?.type === 'string'));
+const validMessages = (messages) => Array.isArray(messages) && messages.every((m) => typeof m?.role === 'string' && validContent(m?.content));
+
+// One call at a time per session: two overlapping generates would share one KV cache. A call waits for the previous
+// one to finish (or for its caller to stop iterating). dispose() waits for the running call, then frees the GPU;
+// calls after it throw DISPOSED.
+function serialize(session) {
+  let tail = Promise.resolve(), disposed = false;
+  const gone = () => new AnyformerError('DISPOSED', 'this session was disposed; load the model again');
+  const turn = async () => {
+    let release;
+    const mine = new Promise((r) => { release = r; });
+    const prev = tail;
+    tail = prev.then(() => mine);
+    await prev;
+    return release;
+  };
+  const generate = session.generate && async function* (messages, o = {}) {
+    if (disposed) throw gone();
+    if (!validMessages(messages)) throw new AnyformerError('INVALID_ARGUMENT', 'messages must be an array of { role, content }, content a string or an array of { type } blocks');
+    const release = await turn();
+    try {
+      if (disposed) throw gone();
+      for await (const chunk of session.generate(messages, o)) yield chunk;
+    } catch (e) {
+      throw wrap(e, 'EXECUTION_FAILED', o.signal);
+    } finally {
+      release();
+    }
+  };
+  // A call that waits its turn like generate(): prime and ensureVision share the engine with it.
+  const queued = (fn) => async (...args) => {
+    if (disposed) throw gone();
+    const release = await turn();
+    try {
+      if (disposed) throw gone();
+      return await fn(...args);
+    } catch (e) {
+      throw wrap(e, 'EXECUTION_FAILED');
+    } finally {
+      release();
+    }
+  };
+  return {
+    ...(generate && { generate }),
+    // Where reasoning starts and ends as token ids ({ openId, closeId, inPrompt, preamble, always }), or null.
+    ...('think' in session && { think: session.think }),
+    ...(session.prime && { prime: queued(session.prime) }),
+    ...(session.ensureVision && { ensureVision: queued(session.ensureVision) }),
+    // The one call every task has. For text generation it is the last chunk of generate().
+    async run(input, o = {}) {
+      if (generate) { let last; for await (const c of generate(input, o)) last = c; return last; }
+      if (disposed) throw gone();
+      const release = await turn();
+      try {
+        if (disposed) throw gone();
+        return await session.run(input, o);
+      } catch (e) {
+        throw wrap(e, 'EXECUTION_FAILED', o.signal);
+      } finally {
+        release();
+      }
+    },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      await tail;
+      await session.dispose?.();
+    },
+  };
+}

package/src/models.js

@@ -0,0 +1,50 @@
+// Models that pass a browser test through anyformer, grouped by what they do. Pass an entry to load() in place of a
+// repo id; it carries the task and, where the back end needs one, the budget. DEFAULT is the smallest download that
+// passed. `test` names the page under test/browser/ that proves the entry; test/models.test.js checks it exists.
+
+const M = (repo, backend, task, test, extra = {}) => ({ repo, backend, task, test, ...extra });
+
+const QWEN2_5_0_5B = M('onnx-community/Qwen2.5-0.5B-Instruct', 'transformers', 'text-generation', 'transformers', { downloadBytes: 786e6 });
+const TERNARY_BONSAI_4B = M('onnx-community/Ternary-Bonsai-4B-ONNX', 'transformers', 'text-generation', 'transformers', { downloadBytes: 1.16e9 });
+const LFM2_5_230M = M('LiquidAI/LFM2.5-230M-GGUF', 'localmind', 'text-generation', 'chat', { downloadBytes: 149e6 });
+const LFM2_5_1_2B = M('LiquidAI/LFM2.5-1.2B-Instruct-GGUF', 'localmind', 'text-generation', 'chat', { downloadBytes: 696e6 });
+const GEMMA4_E2B = M('google/gemma-4-E2B-it-qat-mobile-transformers', 'localmind', 'text-generation', 'chat', { downloadBytes: 2.46e9 });
+const GEMMA4_E4B = M('google/gemma-4-E4B-it-qat-mobile-transformers', 'localmind', 'text-generation', 'chat', { budget: 4e9, downloadBytes: 3.53e9 });
+const TERNARY_BONSAI_2_27B = M('prism-ml/Ternary-Bonsai-2-27B-gguf', 'localmind', 'text-generation', 'chat', { budget: 7e9, downloadBytes: 5.94e9 });
+const QWEN3_5_4B = M('onnx-community/Qwen3.5-4B-ONNX-OPT', 'transformers', 'text-generation', 'vision', { budget: 3.1e9, downloadBytes: 3.0e9 });
+const GEMMA4_E2B_ONNX = M('onnx-community/gemma-4-E2B-it-ONNX', 'transformers', 'text-generation', 'vision', { budget: 3.5e9, downloadBytes: 3.38e9 });
+const GEMMA4_E4B_ONNX = M('onnx-community/gemma-4-E4B-it-ONNX', 'transformers', 'text-generation', 'transformers', { budget: 5.3e9, downloadBytes: 5.18e9 });
+const MINICPM5_2B = M('openbmb/MiniCPM5-2B-GGUF', 'wllama', 'text-generation', 'chat', { downloadBytes: 1.56e9 });
+const QWEN3_0_6B_MDLM = M('naklitechie/Qwen3-0.6B-diffusion-mdlm-ONNX', 'kohra', 'text-generation', 'kohra', { downloadBytes: 1.54e9 });
+const GEMMA4_26B_A4B = M('google/gemma-4-26B-A4B-it-qat-q4_0-gguf', 'diskformer', 'text-generation', 'diskformer-chat', { budget: 2.5e9, downloadBytes: 14.44e9 });
+const MINILM_L6 = M('Xenova/all-MiniLM-L6-v2', 'transformers', 'feature-extraction', 'embed', { downloadBytes: 90e6 });
+const DETR_RESNET_50 = M('Xenova/detr-resnet-50', 'transformers', 'object-detection', 'detect', { downloadBytes: 167e6 });
+
+export const MODELS = {
+  chat: {
+    DEFAULT: QWEN2_5_0_5B,
+    QWEN2_5_0_5B,
+    /** Ternary weights (q2 graph), 4B parameters in 1.16 GB. */
+    TERNARY_BONSAI_4B,
+    /** LocalMind's hand-written LFM2 kernels: 149 MB, the fastest chat here. */
+    LFM2_5_230M,
+    /** The same LFM2 engine on the 1.2B GGUF. */
+    LFM2_5_1_2B,
+    /** Gemma 4 E2B, Google's QAT-mobile export, on LocalMind's Gemma kernels. */
+    GEMMA4_E2B,
+    /** Gemma 4 E4B on the same kernels; the whole 3.5 GB stays on the GPU. */
+    GEMMA4_E4B,
+    /** 27B parameters at 1.6 bits (Prism ternary), 5.9 GB on the GPU. */
+    TERNARY_BONSAI_2_27B,
+    /** llama.cpp in WebAssembly (wllama): WebGPU when the budget holds it, the CPU otherwise. */
+    MINICPM5_2B,
+    /** Text diffusion: the whole reply denoises at once (kohra). */
+    QWEN3_0_6B_MDLM,
+    /** 26B parameters in 2.5 GB of GPU memory; 14.4 GB on disk (diskformer). */
+    GEMMA4_26B_A4B,
+  },
+  /** Chat with images in the messages: content [{ type: 'image', image }, { type: 'text', text }]. Gemma 4 takes audio too. */
+  vision: { DEFAULT: QWEN3_5_4B, QWEN3_5_4B, GEMMA4_E2B_ONNX, GEMMA4_E4B_ONNX },
+  embedding: { DEFAULT: MINILM_L6, MINILM_L6 },
+  objectDetection: { DEFAULT: DETR_RESNET_50, DETR_RESNET_50 },
+};

package/src/pipeline.js

@@ -0,0 +1,27 @@
+// transformers.js's pipeline() call shape over anyformer's resolver, so `import { pipeline } from 'anyformer'` replaces
+// `from '@huggingface/transformers'` for the calls below. Any repo anyformer can plan works: GGUF on diskformer,
+// text diffusion on kohra, ONNX on transformers.js.
+//
+//   const gen = await pipeline('text-generation', 'google/gemma-4-26B-A4B-it-qat-q4_0-gguf', { budget: 2.5e9 });
+//   const [{ generated_text }] = await gen(messages, { max_new_tokens: 128 });   // messages in → messages + reply out
+//   const [{ generated_text: text }] = await gen('Once upon a time');            // a string in → the reply string out
+//
+// Other tasks return what the session's run() returns (feature-extraction: plain arrays, not a Tensor).
+// Options: budget, maxCtx, backends, progress_callback (transformers.js's name) or onProgress, signal.
+
+import { load } from './load.js';
+import { AnyformerError } from './errors.js';
+
+export async function pipeline(task, repo, options = {}) {
+  if (!repo) throw new AnyformerError('INVALID_ARGUMENT', 'pipeline(task, repo): anyformer needs a repo id or a MODELS entry');
+  const { progress_callback, ...opts } = options;
+  const session = await load(repo, { ...opts, task, onProgress: opts.onProgress || progress_callback });
+  const call = task === 'text-generation'
+    ? async (input, o = {}) => {
+      const messages = typeof input === 'string' ? [{ role: 'user', content: input }] : input;
+      const reply = await session.run(messages, { maxNewTokens: o.max_new_tokens ?? o.maxNewTokens ?? 256, signal: o.signal });
+      return [{ generated_text: typeof input === 'string' ? reply.text : [...messages, { role: 'assistant', content: reply.text }] }];
+    }
+    : (input, o) => session.run(input, o);
+  return Object.assign(call, { task, backend: session.backend, plan: session.plan, session, dispose: () => session.dispose() });
+}

package/src/probe.js

@@ -0,0 +1,37 @@
+// What this browser can do, read once per page. Every field has a safe value when an API is missing (Node, Firefox,
+// a page without WebGPU), so a back end's canRun() reads caps without guarding.
+
+// A wasm module with one memory whose flags byte is 0x04 (memory64). It validates only where memory64 is supported.
+const MEMORY64_PROBE = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 5, 3, 1, 4, 0]);
+
+export function memory64() {
+  try { return WebAssembly.validate(MEMORY64_PROBE); } catch { return false; }
+}
+
+export async function probe({ gpu = globalThis.navigator?.gpu, storage = globalThis.navigator?.storage } = {}) {
+  const caps = {
+    webgpu: false, f16: false, subgroups: false,
+    maxBufferSize: 0, maxStorageBufferBindingSize: 0, adapter: null,
+    opfs: false, quotaBytes: 0, usageBytes: 0,
+    memory64: memory64(),
+    // JSPI: wasm that suspends on a promise (diskformer's llama.cpp build reads experts from OPFS this way).
+    jspi: typeof globalThis.WebAssembly?.Suspending === 'function',
+  };
+  const adapter = gpu ? await gpu.requestAdapter({ powerPreference: 'high-performance' }).catch(() => null) : null;
+  if (adapter) {
+    caps.webgpu = true;
+    caps.f16 = adapter.features.has('shader-f16');
+    caps.subgroups = adapter.features.has('subgroups');
+    caps.maxBufferSize = adapter.limits.maxBufferSize;
+    caps.maxStorageBufferBindingSize = adapter.limits.maxStorageBufferBindingSize;
+    const info = adapter.info || {};
+    caps.adapter = { vendor: info.vendor || '', architecture: info.architecture || '', description: info.description || '' };
+  }
+  if (storage?.getDirectory) {
+    caps.opfs = true;
+    const est = storage.estimate ? await storage.estimate().catch(() => null) : null;
+    caps.quotaBytes = est?.quota || 0;
+    caps.usageBytes = est?.usage || 0;
+  }
+  return caps;
+}

package/src/resolve.js

@@ -0,0 +1,49 @@
+// Ask every back end whether it can run the model under the budget, then rank the ones that can.
+//
+// Back-end contract (each back end is a plain object):
+//   id        string, stable, e.g. 'diskformer'
+//   tasks     the Hugging Face pipeline tasks it runs, e.g. ['text-generation']
+//   canRun(model, caps, { budget, task, file }) → { ok: true, estimate } | { ok: false, code, reason, need? }
+//             file: a weights file the caller chose (a GGUF name); a back end that cannot load that file refuses.
+//             estimate = { gpuBytes, diskBytes, tokPerSec | null }. No network, no GPU allocation: it reads the
+//             descriptor and caps only. code is one of REFUSALS below; need is the budget that would pass, with
+//             code 'budget'. A throw counts as code 'threw' with the message as the reason.
+//   load(model, { budget, caps, maxCtx, dtype, onProgress, signal }) → session   (maxCtx: tokens; dtype: a precision
+//             the back end offers, e.g. 'q4f16' for transformers.js; undefined = the back end's default)
+//             session = { run(input, opts) → result, dispose() }; a text-generation session also has
+//             generate(messages, opts) → async iterable of { text, tokens }, and run(messages) is its last chunk.
+//   task is the requested pipeline task, or null for the repo's own (model.task).
+//             The back end applies the model's own chat template.
+
+// Why a back end said no: a closed set, each with the move that changes the answer.
+export const REFUSALS = {
+  format: 'the repo has no weights in a format this back end reads; pick a repo in another format',
+  model: 'this back end reads the format but not this model (architecture or file); pick another model',
+  task: 'this back end does not run the requested task; another back end or another repo does',
+  webgpu: 'no WebGPU adapter; use Chrome or Edge 121+ on a GPU with WebGPU',
+  f16: 'the GPU lacks shader-f16; use a GPU that has it',
+  opfs: 'no OPFS; use a browser with navigator.storage.getDirectory, outside private mode',
+  budget: 'the GPU budget is too small; pass { budget } at least `need` bytes',
+  threw: 'the back end crashed deciding; a bug in that back end, report it with the reason',
+};
+
+export async function resolve(model, caps, backends, { budget, task = null, file = null } = {}) {
+  const candidates = [];
+  for (const [order, b] of backends.entries()) {
+    let r;
+    try { r = await b.canRun(model, caps, { budget, task, file }); } catch (e) { r = { ok: false, code: 'threw', reason: `canRun threw: ${e.message}` }; }
+    candidates.push(r.ok ? { backend: b.id, order, ok: true, estimate: r.estimate } : { backend: b.id, order, ok: false, code: r.code || 'model', reason: r.reason, ...(r.need && { need: r.need }) });
+  }
+  const ranked = candidates.filter((c) => c.ok).sort(rank);
+  return { chosen: ranked[0]?.backend ?? null, ranked: ranked.map((c) => c.backend), candidates };
+}
+
+// A back end with a speed estimate ranks above one without; two estimates rank by tok/s; otherwise the order the
+// caller listed them in, which is the default preference.
+function rank(a, b) {
+  const ta = a.estimate?.tokPerSec ?? null;
+  const tb = b.estimate?.tokPerSec ?? null;
+  if (ta !== null && tb !== null && ta !== tb) return tb - ta;
+  if ((ta === null) !== (tb === null)) return ta === null ? 1 : -1;
+  return a.order - b.order;
+}

package/src/sources.js

@@ -0,0 +1,23 @@
+// Where each back end's runtime loads from: exact versions and commits, so a given anyformer behaves the same tomorrow.
+// kohra and diskformer move fast on their main branches; `node scripts/pin-sources.mjs` moves these pins
+// to each repo's current main, and the browser tests then prove the new pins (test/browser/README.md).
+// transformers.js and wllama move only by hand, in step with LocalMind's pins (plan/history.md, 2026-10-08).
+
+export const PINS = {
+  transformers: '4.3.1',
+  wllama: '3.4.1',      // LocalMind's pin; its stream-drain workaround (src/backends/wllama.js) is for this version
+  kohra: 'f678fac7342c79b58b640540b8b3a7d078b7ab1a',
+  // v0.6.4: every engine (the disk-tier MoE engines, Ling 3.0 Flash, and LocalMind's whole-model engines LFM2.5,
+  // Gemma 4 E2B/E4B and Ternary Bonsai 2) under engines/, and the llama.cpp path under ggml/.
+  diskformer: '095ab2058be9de56841c51b9369ba556d625392b',
+};
+
+const gh = (repo, sha, path) => `https://cdn.jsdelivr.net/gh/NakliTechie/${repo}@${sha}/${path}`;
+
+export const SOURCES = {
+  transformers: `https://cdn.jsdelivr.net/npm/@huggingface/transformers@${PINS.transformers}/+esm`,
+  wllama: `https://cdn.jsdelivr.net/npm/@wllama/wllama@${PINS.wllama}/esm`,
+  kohra: gh('kohra', PINS.kohra, 'kohra.js'),
+  diskformer: gh('diskformer.js', PINS.diskformer, 'engines'),
+  diskformerLlama: gh('diskformer.js', PINS.diskformer, 'ggml/llama.js'),
+};