jev-web 0.6.0 → 0.7.0

package/README.md

@@ -12,8 +12,9 @@ cached.
 
 Three model families ship today — open-jev (fused DeBERTa graph), Laya
 (ModernBERT encoder + typed head), Strands Decider 2B (Qwen torso + pointer
-head), Bekko System One v0 (Ettin cross-encoder), and Decision 2.0 (Qwen3 +
-candidate head) — behind one registry: `createDecisionRuntime({ family, fallback })`.
+head), Bekko System One v0 (Ettin cross-encoder), Decision 2.0 (Qwen3 +
+candidate head), and Kev (Qwen3 + pointer head) — behind one registry:
+`createDecisionRuntime({ family, fallback })`.
 
 This is a generic runtime, not a classifier for any particular domain. You bring
 the state text and the questions; the model answers by choosing among the options
@@ -225,7 +226,7 @@ tries the requested family and then any fallbacks, returning the shared contract
 ```js
 import { createDecisionRuntime, listDecisionFamilies } from "jev-web";
 
-listDecisionFamilies(); // ["open-jev", "laya", "strands-decider", "bekko", "decision2"]
+listDecisionFamilies(); // ["open-jev", "laya", "strands-decider", "bekko", "decision2", "kev"]
 const runtime = await createDecisionRuntime({
   family: "strands-decider",
   fallback: ["laya", "open-jev"],
@@ -345,6 +346,9 @@ const decider = await createBekkoDecider({
   // onnx_browser/ (29 MB)
   onProgress: (p) => console.log(p.phase, p.loaded, p.total),
 });
+// or pick a larger sibling:
+// await createBekkoDecider({ variant: "68m" });  // 196 MB
+// await createBekkoDecider({ variant: "400m" }); // 1.43 GB, #2 on the S1MB leaderboard
 const { answers } = await decider.decide(stateText, questions);
 ```
 
@@ -358,9 +362,11 @@ Protocol implemented here (mirrors the reference browser runtime,
 - score levels map to numeric candidate values `0..n-1`; the answer is the
   expected value plus the argmax level and a normalised score.
 
-Larger siblings are available via the exported model/revision constants:
-`BEKKO_68M_MODEL` / `BEKKO_68M_REVISION` and `BEKKO_400M_MODEL` /
-`BEKKO_400M_REVISION` (68M and 400M, same `onnx_browser/` layout).
+Larger siblings are available via the `variant` option (`"17m"`, `"68m"`,
+`"400m"`) or the exported model/revision constants: `BEKKO_68M_MODEL` /
+`BEKKO_68M_REVISION` and `BEKKO_400M_MODEL` / `BEKKO_400M_REVISION` (same
+`onnx_browser/` layout). The `BEKKO_VARIANTS` map carries each size's pinned
+revision and download size.
 
 Lower-level helpers are exported for custom runtimes:
 `renderBekkoContent`, `renderBekkoRequest`, `tokenizeBekkoRequest`,
@@ -410,6 +416,46 @@ Lower-level helpers are exported for custom runtimes:
 `renderDecision2Content`, `renderDecision2Options`, `buildDecision2Segments`,
 `tokenizeDecision2Segments`, `decision2Softmax`, `decision2AnswerFromLogits`.
 
+## Kev family (Qwen3 + pointer head)
+
+`createKevDecider(options)` runs
+[Kev](https://huggingface.co/jaredpalmer/kev-0.6b) (Apache-2.0), a typed
+decision model: one state and any number of typed questions are packed into a
+single sequence with five delimiter tokens; a block-causal mask derived
+in-graph lets every question see the state and itself only, and a pointer head
+scores each option's `</opt>` token against its question's `<decide>` token.
+One ONNX graph (`input_ids, attention_mask → logits [B, seq]`), one forward
+pass for the whole batch — read the logit at each option's `</opt>` position
+and softmax within the question:
+
+```js
+import { createKevDecider } from "jev-web";
+
+const decider = await createKevDecider({
+  // defaults to onnx-community/kev-0.6b-ONNX @ pinned revision,
+  // onnx/model_q4f16.onnx (335 MB)
+  onProgress: (p) => console.log(p.phase, p.loaded, p.total),
+});
+// or pick the larger sibling:
+// await createKevDecider({ variant: "4b" }); // 1.07 GB, #29 on the Decision Index
+const { answers } = await decider.decide(stateText, questions);
+```
+
+Protocol implemented here (mirrors the reference JS in the model README):
+
+- delimiters `<|fim_prefix|>` (state), `<|fim_middle|>` (question),
+  `<|box_start|>` / `<|box_end|>` (option), `<|fim_suffix|>` (decide); ids
+  derived through the tokenizer, limits from `config.json`'s `kev` block
+  (8192 state / 8192 branch tokens, 255 options);
+- caller text is escaped (`<|name|>` → `<¦name¦>`) so it can never forge a
+  delimiter;
+- choice questions accept `criteria` as `{label: description}`, rendered as
+  `label: description`; noul defaults to `no` / `yes`.
+
+The `KEV_VARIANTS` map (`"0.6b"`, `"4b"`) carries each size's pinned revision
+and download size. Lower-level helpers are exported for custom runtimes:
+`escapeKevText`, `packKevSequence`.
+
 ## Worker / thread
 
 `jev-web` does not bundle a worker, so hosts can create one the way their
@@ -454,4 +500,4 @@ import { createDecider } from "jev-web";
 ## License
 
 MIT (runtime code). Model weights keep their own license (the reference export
-is Apache-2.0).
+is Apache-2.0).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-web",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Run open-jev-, Laya- and Strands-Decider-shaped typed-decision models in the browser: one state plus typed questions in, calibrated probabilities out.",
   "type": "module",
   "license": "MIT",

package/src/bekko.mjs

@@ -28,6 +28,28 @@ export const BEKKO_68M_REVISION = "ab7685f23e5edbc1acb12ced4f2c4e12591efa69";
 export const BEKKO_400M_MODEL = "hotchpotch/bekko-system-one-v0-400m";
 export const BEKKO_400M_REVISION = "1960df5602bd93cc8d336fdebd9fb68a30926e13";
 
+/** Named size variants with their pinned revisions and download sizes. */
+export const BEKKO_VARIANTS = {
+  "17m": {
+    model: BEKKO_DEFAULT_MODEL,
+    revision: BEKKO_DEFAULT_REVISION,
+    bytes: 29_000_000,
+    description: "17m, 29 MB browser ONNX",
+  },
+  "68m": {
+    model: BEKKO_68M_MODEL,
+    revision: BEKKO_68M_REVISION,
+    bytes: 196_342_909,
+    description: "68m, 196 MB browser ONNX",
+  },
+  "400m": {
+    model: BEKKO_400M_MODEL,
+    revision: BEKKO_400M_REVISION,
+    bytes: 1_426_199_724,
+    description: "400m, 1.43 GB browser ONNX",
+  },
+};
+
 // Candidate batching heuristic from the reference runtime: bound the
 // candidate-attention growth per forward; not a total RAM limit.
 export const BEKKO_ATTENTION_BUDGET = 1_048_576;
@@ -252,6 +274,7 @@ const hfUrl = (model, revision, ...parts) =>
 export async function createBekkoDecider({
   model = BEKKO_DEFAULT_MODEL,
   revision = BEKKO_DEFAULT_REVISION,
+  variant = null,
   subdir = BEKKO_DEFAULT_SUBDIR,
   manifestUrl = null,
   modelUrl = null,
@@ -268,6 +291,13 @@ export async function createBekkoDecider({
   attentionBudget = BEKKO_ATTENTION_BUDGET,
   scope = globalThis,
 } = {}) {
+  // Named size shortcut: {variant: "400m"} sets model/revision.
+  if (variant) {
+    const v = BEKKO_VARIANTS[variant];
+    if (!v) throw new TypeError(`bekko: unknown variant "${variant}" (17m, 68m, 400m)`);
+    model = v.model;
+    revision = v.revision;
+  }
   const ortMod = ort ?? (await import("onnxruntime-web"));
   const tf = transformers ?? (await import("@huggingface/transformers"));
   if (wasmPaths) {
@@ -289,10 +319,29 @@ export async function createBekkoDecider({
   const manifest = await manifestRes.json();
   const taskColumns = manifest.tasks;
 
-  const tok = await tf.AutoTokenizer.from_pretrained(tokenizerModel ?? model, {
-    revision: tokenizerRevision ?? (tokenizerModel ? undefined : revision),
-    progress_callback: report("tokenizer"),
-  });
+  /**
+   * Load the tokenizer. The bekko repos keep tokenizer.json under
+   * onnx_browser/, not the repo root, so AutoTokenizer.from_pretrained(repo)
+   * finds nothing there. Load the subdir's tokenizer.json directly and
+   * construct the base tokenizer (special tokens come from the manifest).
+   * An explicit tokenizerModel still goes through from_pretrained.
+   */
+  async function loadBekkoTokenizer() {
+    if (tokenizerModel) {
+      return tf.AutoTokenizer.from_pretrained(tokenizerModel, {
+        revision: tokenizerRevision,
+        progress_callback: report("tokenizer"),
+      });
+    }
+    const tokRes = await fetchImpl(hfUrl(model, revision, subdir, "tokenizer.json"));
+    if (!tokRes.ok) {
+      throw new Error(`bekko: tokenizer fetch failed (${tokRes.status})`);
+    }
+    report("tokenizer")({ file: "tokenizer.json" });
+    return new tf.PreTrainedTokenizer(await tokRes.json(), {});
+  }
+
+  const tok = await loadBekkoTokenizer();
   const encode = (text) =>
     Array.from(tok(text, { add_special_tokens: false }).input_ids.data, Number);
 
@@ -388,4 +437,4 @@ export async function createBekkoDecider({
       try { await session.release?.(); } catch { /* optional */ }
     },
   };
-}
+}

package/src/index.mjs

@@ -64,6 +64,7 @@ export {
   BEKKO_68M_REVISION,
   BEKKO_400M_MODEL,
   BEKKO_400M_REVISION,
+  BEKKO_VARIANTS,
   BEKKO_ATTENTION_BUDGET,
   BEKKO_DEFAULT_YES,
   BEKKO_DEFAULT_NO,
@@ -88,6 +89,16 @@ export {
   DECISION2_MAX_INPUT_TOKENS,
   DECISION2_NOUL_DESCRIPTIONS,
 } from "./decision2.mjs";
+export {
+  createKevDecider,
+  escapeKevText,
+  packKevSequence,
+  KEV_DEFAULT_MODEL,
+  KEV_DEFAULT_REVISION,
+  KEV_4B_MODEL,
+  KEV_4B_REVISION,
+  KEV_VARIANTS,
+} from "./kev.mjs";
 export {
   DEFAULT_MODEL,
   DEFAULT_REVISION,
@@ -99,4 +110,4 @@ export {
   resolveDtype,
   detectWebGPU,
   loadModelConfig,
-} from "./config.mjs";
+} from "./config.mjs";

package/src/kev.mjs

@@ -0,0 +1,297 @@
+/**
+ * kev.mjs — Kev decision-model family (jaredpalmer/kev, Apache-2.0).
+ *
+ * Kev is a typed decision model: one document (the *state*) and any number of
+ * typed questions are packed into a single sequence with five delimiter
+ * tokens. A block-causal mask (derived in-graph from the delimiter ids) lets
+ * every question see the state and itself only; a pointer head scores each
+ * option's `</opt>` token against its question's `<decide>` token.
+ *
+ *   graph:  input_ids, attention_mask (right padded) -> logits [B, seq]
+ *   decode: read the logit at every option's `</opt>` position,
+ *           softmax within each question.
+ *
+ * Reference: onnx-community/kev-0.6b-ONNX README (ships a JS implementation
+ * this mirrors) and config.json `kev` block (delimiters, ids, limits).
+ */
+
+import { normalizeQuestions } from "./questions.mjs";
+import { answersFromScores } from "./answers.mjs";
+import { fetchCachedBytes, fetchOnnxExternalData } from "./laya.mjs";
+import { resolveDtype } from "./config.mjs";
+
+const HF_BASE = "https://huggingface.co";
+const hfUrl = (model, revision, ...parts) =>
+  [HF_BASE, model, "resolve", revision, ...parts.filter(Boolean)].join("/");
+
+export const KEV_DEFAULT_MODEL = "onnx-community/kev-0.6b-ONNX";
+export const KEV_DEFAULT_REVISION = "5a827091b3d58fe4fdfc02a5a5b2ce364047d678";
+export const KEV_4B_MODEL = "onnx-community/kev-4b-ONNX";
+export const KEV_4B_REVISION = "195bdf73096df2bca7150223c9279af7893163c";
+
+/** Named size variants with their pinned revisions and download sizes. */
+export const KEV_VARIANTS = {
+  "0.6b": {
+    model: KEV_DEFAULT_MODEL,
+    revision: KEV_DEFAULT_REVISION,
+    bytes: 335_000_000,
+    description: "kev-0.6b, 335 MB q4f16 browser ONNX",
+  },
+  "4b": {
+    model: KEV_4B_MODEL,
+    revision: KEV_4B_REVISION,
+    bytes: 1_070_000_000,
+    description: "kev-4b, 1.07 GB q4 browser ONNX",
+  },
+};
+
+// Fallback when config.json has no `kev` block (both shipped repos have one).
+const KEV_FALLBACK = {
+  delimiters: {
+    state: "<|fim_prefix|>",
+    question: "<|fim_middle|>",
+    option_start: "<|box_start|>",
+    option_end: "<|box_end|>",
+    decide: "<|fim_suffix|>",
+  },
+  max_state_tokens: 8192,
+  max_branch_tokens: 8192,
+  max_options: 255,
+};
+
+/** Caller text can never produce a delimiter: <|name|> -> <¦name¦>. */
+export function escapeKevText(text) {
+  return String(text).replace(/<\|([A-Za-z0-9_]+)\|>/g, "<¦$1¦>");
+}
+
+function renderKevContent(content) {
+  if (typeof content === "string") return content.trim();
+  return JSON.stringify(content);
+}
+
+/** Render one option; choice options pick up `criteria` descriptions. */
+function renderKevOption(question, label) {
+  if (question.type === "choice") {
+    const desc = question.criteria?.[label];
+    if (desc != null && String(desc).trim() && String(desc).trim() !== label) {
+      return `${label}: ${String(desc).trim()}`;
+    }
+  }
+  return label;
+}
+
+/**
+ * Pack the state and normalized questions into one kev token sequence.
+ * Returns { tokens, groups } where groups[i] holds the sequence indices of
+ * question i's option `</opt>` tokens.
+ */
+export function packKevSequence({ stateText, questions, encode, delims, limits }) {
+  const { state: STATE, question: Q, option_start: OPT, option_end: END, decide: DECIDE } = delims;
+  const stateIds = encode(stateText).slice(0, limits.max_state_tokens);
+  const tokens = [STATE, ...stateIds];
+  const groups = [];
+  let truncated = false;
+
+  for (const q of questions) {
+    const instrIds = encode(q.instructions);
+    const spans = q.options.map((label) => [OPT, ...encode(renderKevOption(q, label)), END]);
+    const branch = [Q, ...instrIds, ...spans.flat(), DECIDE];
+    if (branch.length > limits.max_branch_tokens) {
+      throw new Error(
+        `kev: question branch too long (${branch.length} > ${limits.max_branch_tokens} tokens)`,
+      );
+    }
+    if (tokens.length + branch.length > limits.max_state_tokens) {
+      truncated = true;
+      break;
+    }
+    const base = tokens.length;
+    let cursor = 1 + instrIds.length;
+    const ends = spans.map((s) => {
+      cursor += s.length;
+      return base + cursor - 1; // index of this option's </opt>
+    });
+    tokens.push(...branch);
+    groups.push(ends);
+  }
+  return { tokens, groups, truncated };
+}
+
+/**
+ * Create a Kev decider.
+ *
+ * @param {object} [opts]
+ *  model/revision — pinned ONNX export (or your own mirror)
+ *  variant        — "0.6b" | "4b" shortcut for model/revision
+ *  modelFile      — override the resolved onnx file (default picks q4f16/q4 by device)
+ *  configUrl/modelUrl — override the resolved file URLs
+ *  ort            — injected onnxruntime-web (lazy import otherwise)
+ *  transformers   — injected @huggingface/transformers (tokenizer only)
+ *  fetchImpl      — fetch implementation
+ *  wasmPaths      — ORT wasm/loader directory (self-hosted builds)
+ *  device         — "auto" | "wasm" | "webgpu"
+ *  dtype          — "auto" | "q4" | "q4f16"
+ *  sessionFactory — (url, sessionOptions) => Promise<InferenceSession>
+ *  onProgress     — progress callback
+ */
+export async function createKevDecider({
+  model = KEV_DEFAULT_MODEL,
+  revision = KEV_DEFAULT_REVISION,
+  variant = null,
+  modelFile = null,
+  configUrl = null,
+  modelUrl = null,
+  ort = null,
+  transformers = null,
+  fetchImpl = fetch,
+  wasmPaths = null,
+  device = "auto",
+  dtype = "auto",
+  sessionFactory = null,
+  onProgress = null,
+  scope = globalThis,
+} = {}) {
+  if (variant) {
+    const v = KEV_VARIANTS[variant];
+    if (!v) throw new TypeError(`kev: unknown variant "${variant}" (0.6b, 4b)`);
+    model = v.model;
+    revision = v.revision;
+  }
+  const ortMod = ort ?? (await import("onnxruntime-web"));
+  const tf = transformers ?? (await import("@huggingface/transformers"));
+  if (wasmPaths) {
+    try { ortMod.env.wasm.wasmPaths = wasmPaths; } catch { /* older runtime */ }
+  }
+
+  const resolvedDevice = device !== "auto"
+    ? device
+    : (scope?.navigator?.gpu ? "webgpu" : "wasm");
+  const resolvedDtype = resolveDtype(resolvedDevice, dtype);
+  const executionProviders = resolvedDevice === "webgpu" ? ["webgpu", "wasm"] : ["wasm"];
+
+  const report = (phase) => (p) =>
+    onProgress?.({ phase, file: p?.file ?? null, loaded: p?.loaded ?? null, total: p?.total ?? null });
+
+  // Model config carries the kev protocol block (delimiters, ids, limits).
+  const cfgRes = await fetchImpl(configUrl ?? hfUrl(model, revision, "", "config.json"));
+  if (!cfgRes.ok) throw new Error(`kev: config fetch failed (${cfgRes.status})`);
+  const kevCfg = (await cfgRes.json()).kev ?? {};
+  const delimiters = { ...KEV_FALLBACK.delimiters, ...(kevCfg.delimiters ?? {}) };
+  const limits = {
+    max_state_tokens: kevCfg.max_state_tokens ?? KEV_FALLBACK.max_state_tokens,
+    max_branch_tokens: kevCfg.max_branch_tokens ?? KEV_FALLBACK.max_branch_tokens,
+    max_options: kevCfg.max_options ?? KEV_FALLBACK.max_options,
+  };
+
+  const tok = await tf.AutoTokenizer.from_pretrained(model, {
+    revision,
+    progress_callback: report("tokenizer"),
+  });
+  const rawEncode = (text) =>
+    Array.from(tok(text, { add_special_tokens: false }).input_ids.data, Number);
+  // Delimiter ids are derived from the raw strings; caller text is escaped so
+  // it can never produce a delimiter.
+  const encode = (text) => rawEncode(escapeKevText(text));
+  // Derive delimiter ids through the tokenizer (robust to id changes).
+  const delims = Object.fromEntries(
+    Object.entries(delimiters).map(([k, t]) => {
+      const ids = rawEncode(t);
+      if (ids.length !== 1) throw new Error(`kev: delimiter ${t} is not a single token`);
+      return [k, ids[0]];
+    }),
+  );
+
+  const qfile = modelFile ?? (resolvedDtype === "q4f16" ? "model_q4f16.onnx" : "model_q4.onnx");
+  const url = modelUrl ?? hfUrl(model, revision, "onnx", qfile);
+  const createSession = sessionFactory
+    ?? (async (u, opts) => {
+      const modelBytes = await fetchCachedBytes(u, {
+        fetchImpl, onProgress: (p) => onProgress?.(p), persist: true,
+      });
+      const external = await fetchOnnxExternalData(u, {
+        fetchImpl, onProgress: (p) => onProgress?.(p),
+      });
+      const sessionOpts = external ? { ...opts, externalData: [external] } : opts;
+      return ortMod.InferenceSession.create(modelBytes, sessionOpts);
+    });
+  let session;
+  let activeDevice = resolvedDevice;
+  try {
+    session = await createSession(url, {
+      executionProviders,
+      graphOptimizationLevel: "all",
+    });
+  } catch (e) {
+    if (resolvedDevice === "webgpu") {
+      onProgress?.({ phase: `webgpu unavailable (${e?.message ?? e}) — retrying on wasm` });
+      session = await createSession(url, { executionProviders: ["wasm"], graphOptimizationLevel: "all" });
+      activeDevice = "wasm";
+    } else {
+      throw e;
+    }
+  }
+
+  return {
+    info: {
+      family: "kev",
+      model,
+      revision,
+      device: activeDevice,
+      dtype: resolvedDtype,
+      tasks: ["choice", "noul", "score"],
+      limits,
+    },
+    async decide(state, questions) {
+      const t0 = Date.now();
+      const normalized = normalizeQuestions(questions);
+      for (const [i, q] of normalized.entries()) {
+        if (q.options.length > limits.max_options) {
+          throw new TypeError(`questions[${i}]: kev supports at most ${limits.max_options} options`);
+        }
+      }
+      const stateText = renderKevContent(state);
+      const { tokens, groups, truncated } = packKevSequence({
+        stateText, questions: normalized, encode, delims, limits,
+      });
+      if (groups.length !== normalized.length) {
+        throw new Error("kev: packed fewer questions than requested");
+      }
+
+      const n = tokens.length;
+      const inputIds = new ortMod.Tensor("int64", BigInt64Array.from(tokens, BigInt), [1, n]);
+      const attentionMask = new ortMod.Tensor("int64", new BigInt64Array(n).fill(1n), [1, n]);
+      const tRun = Date.now();
+      const out = await session.run({ input_ids: inputIds, attention_mask: attentionMask });
+      const runMs = Date.now() - tRun;
+      const outLogits = out.logits ?? out[Object.keys(out)[0]];
+      if (outLogits.dims.length !== 2 || outLogits.dims[0] !== 1 || outLogits.dims[1] !== n) {
+        throw new Error("kev: invalid model logits shape");
+      }
+      const scores = Array.from(outLogits.data, Number);
+      // One flat score list; groups map each question to its option positions.
+      const flat = [];
+      const flatGroups = groups.map((ends) => ends.map((pos) => {
+        flat.push(scores[pos]);
+        return flat.length - 1;
+      }));
+      const answers = answersFromScores(flat, {
+        questions: normalized,
+        groups: flatGroups,
+      });
+
+      return {
+        answers,
+        truncated,
+        length: n,
+        prompts: normalized.map((q) => ({
+          instructions: q.instructions,
+          options: q.options,
+        })),
+        timings: { totalMs: Date.now() - t0, runMs },
+      };
+    },
+    async dispose() {
+      try { await session.release?.(); } catch { /* optional */ }
+    },
+  };
+}

package/src/registry.mjs

@@ -44,6 +44,11 @@ import {
   DECISION2_DEFAULT_MODEL,
   DECISION2_DEFAULT_REVISION,
 } from "./decision2.mjs";
+import {
+  createKevDecider,
+  KEV_DEFAULT_MODEL,
+  KEV_DEFAULT_REVISION,
+} from "./kev.mjs";
 
 const families = new Map();
 
@@ -108,6 +113,14 @@ registerDecisionFamily("decision2", {
   create: createDecision2Decider,
 });
 
+registerDecisionFamily("kev", {
+  defaults: {
+    model: KEV_DEFAULT_MODEL,
+    revision: KEV_DEFAULT_REVISION,
+  },
+  create: createKevDecider,
+});
+
 /**
  * Create a decision runtime, preferring `family` and falling back in order.
  * @param {{family?:string, fallback?:string[], onFallback?:Function}} [opts]
@@ -140,4 +153,4 @@ export async function createDecisionRuntime({
     }
   }
   throw lastError ?? new Error("createDecisionRuntime: no family could be created");
-}
+}