jev-web 0.2.0 → 0.3.0

package/README.md

@@ -91,6 +91,36 @@ take `input_ids, attention_mask, seg, pair_q, pair_opt`, and return per-pair
 `logits`. `typedMarkerIds()` fails loudly when a repo is missing them.
 
 
+## Multiple families (registry)
+
+`jev-web` is a multi-family runtime: `createDecisionRuntime({ family, fallback })`
+tries the requested family and then any fallbacks, returning the shared contract
+`{ info, decide(state, questions), dispose? }`:
+
+```js
+import { createDecisionRuntime, listDecisionFamilies } from "jev-web";
+
+listDecisionFamilies(); // ["open-jev", "laya"]
+const runtime = await createDecisionRuntime({
+  family: "laya",
+  fallback: ["open-jev"],
+  onFallback: ({ family, error }) => console.warn(family, error),
+});
+const { answers, truncated, length, prompts, timings } = await runtime.decide(state, questions);
+```
+
+Third-party families plug in without touching core:
+
+```js
+registerDecisionFamily("my-model", {
+  defaults: { model: "org/my-typed-decision-ONNX", revision: "main" },
+  create: async (opts) => ({ info, decide, dispose }),
+});
+```
+
+`decide()` returns `prompts` (decoded input sequence(s), for audit/debug) and
+`timings` (per-stage ms) alongside the answers.
+
 ## Laya family (ModernBERT encoder + typed head)
 
 `createLayaDecider(options)` runs the [Laya](https://huggingface.co/convaiinnovations/laya)

package/package.json

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

package/src/index.mjs

@@ -1,5 +1,9 @@
 // jev-web — public API (typed decisions in the browser).
 export { createDecider } from "./session.mjs";
+export {
+  registerDecisionFamily, createDecisionRuntime,
+  listDecisionFamilies, getDecisionFamily,
+} from "./registry.mjs";
 export { normalizeQuestions, QUESTION_TYPES, NOUL_OPTIONS } from "./questions.mjs";
 export { buildDecisionInput, typedMarkerIds, DecisionInputTooLongError } from "./encode.mjs";
 export { answersFromScores, softmaxWithTemperature } from "./answers.mjs";

package/src/laya.mjs

@@ -206,6 +206,69 @@ export function layaAnswersFromLogits({
   return answers;
 }
 
+/**
+ * Fetch a JSON file with optional byte progress (fetch/Response compatible).
+ * Falls back to `res.json()` when the body isn't streamable (Node fakes/tests).
+ */
+async function fetchJson(url, file, { fetchImpl, onProgress }) {
+  const res = await fetchImpl(url);
+  if (!res.ok) throw new Error(`tokenizer ${file}: HTTP ${res.status}`);
+  const total = Number(res.headers?.get?.("content-length")) || 0;
+  if (onProgress && res.body?.getReader) {
+    const reader = res.body.getReader();
+    const chunks = [];
+    let loaded = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      loaded += value.length;
+      onProgress({ phase: "tokenizer", file, loaded, total: total || null });
+    }
+    const buf = new Uint8Array(loaded);
+    let off = 0;
+    for (const c of chunks) { buf.set(c, off); off += c.length; }
+    return JSON.parse(new TextDecoder().decode(buf));
+  }
+  return res.json();
+}
+
+/**
+ * Load a Laya tokenizer directly from its files.
+ *
+ * transformers.js `AutoTokenizer.from_pretrained` ignores `subfolder`, and the
+ * Laya web export keeps its tokenizer under `v1/` (and its root has no
+ * `tokenizer_config.json`), so the library path throws
+ * "Cannot read properties of undefined (reading 'tokenizer_class')".
+ * Fetch the two JSON files ourselves and instantiate the class the config
+ * names (e.g. `PreTrainedTokenizerFast` -> `PreTrainedTokenizer`).
+ *
+ * @param {{urlBase:string, fetchImpl?:Function, transformers?:object,
+ *   onProgress?:Function}} spec `urlBase` must end with "/".
+ * @returns {Promise<object>} tokenizer instance
+ */
+export async function loadLayaTokenizer({
+  urlBase,
+  fetchImpl = fetch,
+  transformers = null,
+  onProgress = null,
+} = {}) {
+  if (!urlBase) throw new TypeError("loadLayaTokenizer: urlBase is required");
+  const base = urlBase.endsWith("/") ? urlBase : `${urlBase}/`;
+  const [tokenizerJSON, tokenizerConfig] = await Promise.all([
+    fetchJson(`${base}tokenizer.json`, "tokenizer.json", { fetchImpl, onProgress }),
+    fetchJson(`${base}tokenizer_config.json`, "tokenizer_config.json", { fetchImpl, onProgress }),
+  ]);
+  const tf = transformers ?? (await import("@huggingface/transformers"));
+  const className = String(tokenizerConfig?.tokenizer_class ?? "PreTrainedTokenizer")
+    .replace(/Fast$/, "");
+  const Cls = tf[className] ?? tf.PreTrainedTokenizer;
+  if (typeof Cls !== "function") {
+    throw new Error(`loadLayaTokenizer: no tokenizer class for "${className}"`);
+  }
+  return new Cls(tokenizerJSON, tokenizerConfig);
+}
+
 /** Wrap a transformers.js tokenizer into the tiny adapter laya needs. */
 export function layaTokenizerAdapter(tok) {
   const idOf = (prop, text) => {
@@ -216,6 +279,13 @@ export function layaTokenizerAdapter(tok) {
   };
   return {
     encode: (text) => Array.from(tok(text, { add_special_tokens: false }).input_ids.data, Number),
+    decode: (ids) => {
+      try {
+        return tok.decode(Array.from(ids), { skip_special_tokens: false });
+      } catch {
+        return Array.from(ids).join(" ");
+      }
+    },
     ids: {
       cls: idOf("cls_token_id", "[CLS]"),
       sep: idOf("sep_token_id", "[SEP]"),
@@ -225,6 +295,8 @@ export function layaTokenizerAdapter(tok) {
   };
 }
 
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+
 const hfUrl = (model, revision, file) =>
   `https://huggingface.co/${model}/resolve/${revision ? `${revision}/` : ""}${file}`;
 
@@ -249,6 +321,7 @@ export async function createLayaDecider({
   tokenizerSubfolder = null,
   ort = null,
   transformers = null,
+  fetchImpl = fetch,
   wasmPaths = null,
   device = "auto",
   // (url, sessionOptions) => Promise<InferenceSession>. Hosts that need custom
@@ -276,15 +349,28 @@ export async function createLayaDecider({
   const report = (phase) => (p) =>
     onProgress?.({ phase, file: p?.file ?? null, loaded: p?.loaded ?? null, total: p?.total ?? null });
 
-  const tokModel = tokenizerModel ?? model;
-  const tokSubfolder = tokenizerSubfolder === null
-    ? undefined
-    : (tokenizerSubfolder ?? subfolder);
-  const tok = await tf.AutoTokenizer.from_pretrained(tokModel, {
-    revision: tokenizerModel ? undefined : revision,
-    ...(tokSubfolder ? { subfolder: tokSubfolder } : {}),
-    progress_callback: report("tokenizer"),
-  });
+  let tok;
+  if (tokenizerModel) {
+    // Host-provided path/repo (local dir in Node, or a repo whose tokenizer
+    // lives at the root) — use the library loader.
+    const tokSubfolder = tokenizerSubfolder === null
+      ? undefined
+      : (tokenizerSubfolder ?? subfolder);
+    tok = await tf.AutoTokenizer.from_pretrained(tokenizerModel, {
+      revision: tokenizerSubfolder ? undefined : revision,
+      ...(tokSubfolder ? { subfolder: tokSubfolder } : {}),
+      progress_callback: report("tokenizer"),
+    });
+  } else {
+    // Default: the pinned web export keeps the tokenizer under `v1/`, which
+    // AutoTokenizer cannot address (no `subfolder` support) — load it directly.
+    tok = await loadLayaTokenizer({
+      urlBase: hfUrl(model, revision, `${subfolder}/`),
+      transformers: tf,
+      fetchImpl,
+      onProgress,
+    });
+  }
   const adapter = layaTokenizerAdapter(tok);
 
   const encUrl = encoderUrl ?? hfUrl(model, revision, `${subfolder}/encoder_q8.onnx`);
@@ -334,22 +420,27 @@ export async function createLayaDecider({
         Object.entries(temperatureByOptions).map(([k, v]) => [k, clampTemperature(v)])),
     },
     async decide(state, questions) {
+      const t0 = now();
       const normalized = normalizeQuestions(questions);
       const items = normalized.map((q) =>
         buildLayaSequence({ encode: adapter.encode, ids: adapter.ids, state, question: q, maxLen, headMaxLen, maxPrefixes }));
       const b = collateLayaItems(items, adapter.pad);
 
+      const tEncode = now();
       const encOut = await encoder.run({
         input_ids: int64(b.inputIds, [b.n, b.L]),
         attention_mask: int64(b.attention, [b.n, b.L]),
       });
+      const encoderMs = now() - tEncode;
       const hidden = encOut.hidden ?? encOut.last_hidden_state ?? encOut[Object.keys(encOut)[0]];
 
       // The q8 web head is exported batch-1 only (despite dynamic batch
       // axes), so run it once per question over the shared encoder output.
       // The encoder — the expensive half — still runs as one batched pass.
       const headLogits = [];
+      const headPerQuestionMs = [];
       const markerCounts = items.map((it) => it.markers.length);
+      const tHead = now();
       for (let i = 0; i < b.n; i++) {
         const k = markerCounts[i];
         const row = hidden.data.subarray(i * b.L * hidden.dims[2], (i + 1) * b.L * hidden.dims[2]);
@@ -357,6 +448,7 @@ export async function createLayaDecider({
         const rowMask = b.attention.subarray(i * b.L, (i + 1) * b.L);
         const rowPos = b.markerPos.subarray(i * b.M, i * b.M + k);
         const rowMarkerMask = b.markerMask.subarray(i * b.M, i * b.M + k);
+        const tHeadTotal = now();
         const headOut = await head.run({
           hidden: rowHidden,
           attention_mask: int64(rowMask, [1, b.L]),
@@ -366,6 +458,7 @@ export async function createLayaDecider({
         });
         const rowLogits = headOut.logits ?? headOut[Object.keys(headOut)[0]];
         headLogits.push(...Array.from(rowLogits.data, Number));
+        headPerQuestionMs.push(Math.round(now() - tHeadTotal));
       }
 
       const answers = layaAnswersFromLogits({
@@ -376,7 +469,22 @@ export async function createLayaDecider({
         temperatureByOptions,
       });
       const length = Number(b.attention.reduce((a, v) => a + v, 0n));
-      return { answers, truncated: items.some((it) => it.ids.length >= maxLen), length };
+      // Exact, human-readable view of what the encoder consumed: each
+      // question's token sequence decoded back to text (special tokens kept).
+      const prompts = items.map((it) => adapter.decode(it.ids));
+      const headMs = now() - tHead;
+      return {
+        answers,
+        truncated: items.some((it) => it.ids.length >= maxLen),
+        length,
+        prompts,
+        timings: {
+          totalMs: Math.round(now() - t0),
+          encoderMs: Math.round(encoderMs),
+          headMs: Math.round(headMs),
+          headPerQuestionMs,
+        },
+      };
     },
     async dispose() {
       try { await encoder.release?.(); } catch { /* optional */ }

package/src/registry.mjs

@@ -0,0 +1,102 @@
+/**
+ * registry.mjs — multi-family runtime for JEV-style typed-decision models.
+ *
+ * jev-web ships two families today (open-jev's fused DeBERTa graph and Laya's
+ * ModernBERT encoder + typed head) and any third party can add its own without
+ * touching core:
+ *
+ *   registerDecisionFamily("my-model", {
+ *     defaults: { model: "org/my-typed-decision-ONNX", revision: "main" },
+ *     create: async (opts) => ({ info, decide(state, questions), dispose? }),
+ *   });
+ *
+ *   const runtime = await createDecisionRuntime({ family: "my-model" });
+ *
+ * `createDecisionRuntime` tries the requested family, then any `fallback`
+ * families in order, reporting each failure through `onFallback`. The returned
+ * object always exposes the shared contract:
+ *   { info: { family, ... }, decide(state, questions) -> DecideResult, dispose? }
+ * where DecideResult is `{ answers, truncated, length, prompts?, timings? }`.
+ */
+
+import { createDecider } from "./session.mjs";
+import { DEFAULT_MODEL, DEFAULT_REVISION } from "./config.mjs";
+import {
+  createLayaDecider,
+  LAYA_DEFAULT_MODEL,
+  LAYA_DEFAULT_REVISION,
+  LAYA_DEFAULT_SUBFOLDER,
+} from "./laya.mjs";
+
+const families = new Map();
+
+/**
+ * Register (or replace) a decision family.
+ * @param {string} id short stable identifier, e.g. "open-jev"
+ * @param {{create:(opts:object)=>Promise<object>, defaults?:object}} descriptor
+ */
+export function registerDecisionFamily(id, descriptor) {
+  if (!id || typeof id !== "string") throw new TypeError("registerDecisionFamily: id is required");
+  if (!descriptor || typeof descriptor.create !== "function") {
+    throw new TypeError(`registerDecisionFamily(${id}): descriptor.create is required`);
+  }
+  families.set(id, { defaults: {}, ...descriptor });
+  return id;
+}
+
+/** @returns {string[]} registered family ids in registration order. */
+export function listDecisionFamilies() {
+  return [...families.keys()];
+}
+
+export function getDecisionFamily(id) {
+  return families.get(id) ?? null;
+}
+
+registerDecisionFamily("open-jev", {
+  defaults: { model: DEFAULT_MODEL, revision: DEFAULT_REVISION },
+  create: createDecider,
+});
+
+registerDecisionFamily("laya", {
+  defaults: {
+    model: LAYA_DEFAULT_MODEL,
+    revision: LAYA_DEFAULT_REVISION,
+    subfolder: LAYA_DEFAULT_SUBFOLDER,
+  },
+  create: createLayaDecider,
+});
+
+/**
+ * Create a decision runtime, preferring `family` and falling back in order.
+ * @param {{family?:string, fallback?:string[], onFallback?:Function}} [opts]
+ * @returns {Promise<{info:object, decide:Function, dispose?:Function}>}
+ */
+export async function createDecisionRuntime({
+  family = "laya",
+  fallback = [],
+  onFallback = null,
+  ...opts
+} = {}) {
+  const order = [family, ...(Array.isArray(fallback) ? fallback : [])].filter(Boolean);
+  let lastError = null;
+  for (const id of order) {
+    const descriptor = families.get(id);
+    if (!descriptor) {
+      lastError = new Error(`unknown decision family "${id}"`);
+      onFallback?.({ family: id, error: lastError });
+      continue;
+    }
+    try {
+      const runtime = await descriptor.create({ ...descriptor.defaults, ...opts });
+      return {
+        ...runtime,
+        info: { family: id, ...(runtime?.info ?? {}) },
+      };
+    } catch (error) {
+      lastError = error;
+      onFallback?.({ family: id, error });
+    }
+  }
+  throw lastError ?? new Error("createDecisionRuntime: no family could be created");
+}

package/src/session.mjs

@@ -5,6 +5,8 @@
 // builds). Everything heavy stays out of module scope.
 
 import { normalizeQuestions } from "./questions.mjs";
+
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
 import { buildDecisionInput, typedMarkerIds } from "./encode.mjs";
 import { answersFromScores } from "./answers.mjs";
 import {
@@ -77,6 +79,7 @@ export async function createDecider({
 
   return {
     info: {
+      family: "open-jev",
       model,
       revision,
       device: resolvedDevice,
@@ -88,6 +91,7 @@ export async function createDecider({
       configSource: remote.source,
     },
     async decide(state, questions) {
+      const t0 = now();
       const normalized = normalizeQuestions(questions);
       const tokenized = normalized.map((q) => ({
         type: q.type,
@@ -109,7 +113,9 @@ export async function createDecider({
         pair_q: i64(input.pairQ, [1, input.pairQ.length]),
         pair_opt: i64(input.pairOpt, [1, input.pairOpt.length]),
       };
+      const tInfer = now();
       const out = await net(feeds);
+      const inferMs = now() - tInfer;
       const logits = out?.logits;
       if (!logits) throw new Error("model output has no `logits` — not a typed-decision export?");
       const scores = Array.from(logits.to("float32").data, Number);
@@ -118,7 +124,20 @@ export async function createDecider({
         groups: input.groups,
         temperature: effective.temperature,
       });
-      return { answers, truncated: input.truncated, length: input.length };
+      // Exact view of the single fused sequence the graph consumed.
+      let prompt;
+      try {
+        prompt = tokenizer.decode(input.inputIds, { skip_special_tokens: false });
+      } catch {
+        prompt = input.inputIds.join(" ");
+      }
+      return {
+        answers,
+        truncated: input.truncated,
+        length: input.length,
+        prompts: [prompt],
+        timings: { totalMs: Math.round(now() - t0), inferMs: Math.round(inferMs) },
+      };
     },
     async decideMany(cases) {
       const out = [];