jev-web 0.3.3 → 0.4.0

package/src/questions.mjs

@@ -1,39 +1,39 @@
-// jev-web — question normalization for typed-decision models.
-//
-// The model answers three question kinds:
-//   choice — pick one of 2..255 options
-//   score  — ordered levels (2..10); the answer is the expected level index
-//   noul   — yes/no; the answer is p(yes)
-
-export const QUESTION_TYPES = new Set(["choice", "score", "noul"]);
-export const NOUL_OPTIONS = ["no", "yes"];
-
-export function normalizeQuestions(questions) {
-  if (!Array.isArray(questions) || questions.length === 0) {
-    throw new TypeError("questions must be a non-empty array");
-  }
-  return questions.map((q, i) => {
-    const type = q?.type;
-    if (!QUESTION_TYPES.has(type)) {
-      throw new TypeError(`questions[${i}].type must be one of ${[...QUESTION_TYPES].join("|")}`);
-    }
-    const instructions = String(q?.instructions ?? "").trim();
-    if (!instructions) throw new TypeError(`questions[${i}].instructions is required`);
-
-    let options;
-    if (type === "noul") {
-      options = Array.isArray(q.options) && q.options.length ? q.options.map(String) : [...NOUL_OPTIONS];
-      if (options.length !== 2) throw new TypeError(`questions[${i}]: noul takes exactly 2 options`);
-    } else if (type === "choice") {
-      options = (q.options ?? []).map(String);
-      if (options.length < 2) throw new TypeError(`questions[${i}]: choice needs at least 2 options`);
-      if (options.length > 255) throw new TypeError(`questions[${i}]: choice supports at most 255 options`);
-    } else {
-      options = (q.options ?? []).map(String);
-      if (options.length < 2 || options.length > 10) {
-        throw new TypeError(`questions[${i}]: score needs 2-10 ordered levels`);
-      }
-    }
-    return { type, instructions, options };
-  });
-}
+// jev-web — question normalization for typed-decision models.
+//
+// The model answers three question kinds:
+//   choice — pick one of 2..255 options
+//   score  — ordered levels (2..10); the answer is the expected level index
+//   noul   — yes/no; the answer is p(yes)
+
+export const QUESTION_TYPES = new Set(["choice", "score", "noul"]);
+export const NOUL_OPTIONS = ["no", "yes"];
+
+export function normalizeQuestions(questions) {
+  if (!Array.isArray(questions) || questions.length === 0) {
+    throw new TypeError("questions must be a non-empty array");
+  }
+  return questions.map((q, i) => {
+    const type = q?.type;
+    if (!QUESTION_TYPES.has(type)) {
+      throw new TypeError(`questions[${i}].type must be one of ${[...QUESTION_TYPES].join("|")}`);
+    }
+    const instructions = String(q?.instructions ?? "").trim();
+    if (!instructions) throw new TypeError(`questions[${i}].instructions is required`);
+
+    let options;
+    if (type === "noul") {
+      options = Array.isArray(q.options) && q.options.length ? q.options.map(String) : [...NOUL_OPTIONS];
+      if (options.length !== 2) throw new TypeError(`questions[${i}]: noul takes exactly 2 options`);
+    } else if (type === "choice") {
+      options = (q.options ?? []).map(String);
+      if (options.length < 2) throw new TypeError(`questions[${i}]: choice needs at least 2 options`);
+      if (options.length > 255) throw new TypeError(`questions[${i}]: choice supports at most 255 options`);
+    } else {
+      options = (q.options ?? []).map(String);
+      if (options.length < 2 || options.length > 10) {
+        throw new TypeError(`questions[${i}]: score needs 2-10 ordered levels`);
+      }
+    }
+    return { type, instructions, options, ...(q?.criteria !== undefined ? { criteria: q.criteria } : {}) };
+  });
+}

package/src/registry.mjs

@@ -1,102 +1,129 @@
-/**
- * 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");
-}
+/**
+ * registry.mjs — multi-family runtime for JEV-style typed-decision models.
+ *
+ * jev-web ships three families today (open-jev's fused DeBERTa graph, Laya's
+ * ModernBERT encoder + typed head, Strands Decider 2B's Qwen torso + pointer
+ * head, and Bekko System One v0's cross-encoder) 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";
+import {
+  createStrandsDecider,
+  STRANDS_DEFAULT_MODEL,
+  STRANDS_DEFAULT_REVISION,
+} from "./strands.mjs";
+import {
+  createBekkoDecider,
+  BEKKO_DEFAULT_MODEL,
+  BEKKO_DEFAULT_REVISION,
+} from "./bekko.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,
+});
+
+registerDecisionFamily("strands-decider", {
+  defaults: {
+    model: STRANDS_DEFAULT_MODEL,
+    revision: STRANDS_DEFAULT_REVISION,
+  },
+  create: createStrandsDecider,
+});
+
+registerDecisionFamily("bekko", {
+  defaults: {
+    model: BEKKO_DEFAULT_MODEL,
+    revision: BEKKO_DEFAULT_REVISION,
+  },
+  create: createBekkoDecider,
+});
+
+/**
+ * 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

@@ -1,151 +1,151 @@
-// jev-web — decider session: tokenizer + model + decide().
-//
-// transformers.js is an optional peer dependency, imported lazily so the
-// package works anywhere and hosts can inject their own copy (tests, custom
-// 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 {
-  DEFAULT_MODEL,
-  DEFAULT_REVISION,
-  loadModelConfig,
-  resolveDevice,
-  resolveDtype,
-  detectWebGPU,
-} from "./config.mjs";
-
-export async function createDecider({
-  model = DEFAULT_MODEL,
-  revision = DEFAULT_REVISION,
-  dtype = "auto",
-  device = "auto",
-  temperature = null,
-  maxStateTokens = null,
-  onProgress = null,
-  transformers = null,
-  fetchImpl = fetch,
-  scope = globalThis,
-  // Directory (or CDN base) holding the onnxruntime-web wasm/loader files.
-  // Bundlers usually cannot ship the 26 MB asyncify wasm under static-host
-  // file-size limits; hosts that self-host a compressed copy set this to
-  // e.g. "/assets/". Defaults to the runtime's own resolution.
-  wasmPaths = null,
-} = {}) {
-  const tf = transformers ?? (await import("@huggingface/transformers"));
-  if (wasmPaths) {
-    try {
-      tf.env.backends.onnx.wasm.wasmPaths = wasmPaths;
-    } catch { /* older runtime: ignore */ }
-  }
-  const remote = await loadModelConfig({ model, revision, fetchImpl });
-  const resolvedDevice = resolveDevice({ device, webgpu: await detectWebGPU(scope) });
-  const resolvedDtype = resolveDtype(resolvedDevice, dtype);
-
-  const report = (phase) => (p) =>
-    onProgress?.({
-      phase,
-      status: p?.status ?? null,
-      file: p?.file ?? null,
-      loaded: p?.loaded ?? null,
-      total: p?.total ?? null,
-      progress: p?.progress ?? null,
-    });
-
-  const tokenizer = await tf.AutoTokenizer.from_pretrained(model, {
-    revision,
-    progress_callback: report("tokenizer"),
-  });
-  const net = await tf.AutoModel.from_pretrained(model, {
-    revision,
-    dtype: resolvedDtype,
-    device: resolvedDevice,
-    progress_callback: report("model"),
-  });
-
-  const encode = (text) => Array.from(tokenizer(text, { add_special_tokens: false }).input_ids.data, Number);
-  const markers = typedMarkerIds(encode, { markers: remote.markers });
-
-  const effective = {
-    temperature: Number.isFinite(temperature) ? temperature : remote.temperature,
-    maxStateTokens: Number.isFinite(maxStateTokens) ? maxStateTokens : remote.maxStateTokens,
-    maxLen: remote.maxLen,
-  };
-
-  const i64 = (values, dims) => new tf.Tensor("int64", BigInt64Array.from(values, BigInt), dims);
-
-  return {
-    info: {
-      family: "open-jev",
-      model,
-      revision,
-      device: resolvedDevice,
-      dtype: resolvedDtype,
-      temperature: effective.temperature,
-      maxStateTokens: effective.maxStateTokens,
-      maxLen: effective.maxLen,
-      pool: remote.pool,
-      configSource: remote.source,
-    },
-    async decide(state, questions) {
-      const t0 = now();
-      const normalized = normalizeQuestions(questions);
-      const tokenized = normalized.map((q) => ({
-        type: q.type,
-        instructionIds: encode(q.instructions),
-        optionIds: q.options.map((option) => encode(option)),
-      }));
-      const stateIds = encode(String(state ?? ""));
-      const input = buildDecisionInput({
-        stateIds,
-        markers,
-        questions: tokenized,
-        maxStateTokens: effective.maxStateTokens,
-        maxLen: effective.maxLen,
-      });
-      const feeds = {
-        input_ids: i64(input.inputIds, [1, input.length]),
-        attention_mask: i64(input.inputIds.map(() => 1), [1, input.length]),
-        seg: i64(input.seg, [1, input.length]),
-        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);
-      const answers = answersFromScores(scores, {
-        questions: normalized,
-        groups: input.groups,
-        temperature: effective.temperature,
-      });
-      // 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 = [];
-      for (const c of cases ?? []) out.push(await this.decide(c.state, c.questions));
-      return out;
-    },
-    dispose() {
-      net?.dispose?.();
-    },
-  };
-}
+// jev-web — decider session: tokenizer + model + decide().
+//
+// transformers.js is an optional peer dependency, imported lazily so the
+// package works anywhere and hosts can inject their own copy (tests, custom
+// 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 {
+  DEFAULT_MODEL,
+  DEFAULT_REVISION,
+  loadModelConfig,
+  resolveDevice,
+  resolveDtype,
+  detectWebGPU,
+} from "./config.mjs";
+
+export async function createDecider({
+  model = DEFAULT_MODEL,
+  revision = DEFAULT_REVISION,
+  dtype = "auto",
+  device = "auto",
+  temperature = null,
+  maxStateTokens = null,
+  onProgress = null,
+  transformers = null,
+  fetchImpl = fetch,
+  scope = globalThis,
+  // Directory (or CDN base) holding the onnxruntime-web wasm/loader files.
+  // Bundlers usually cannot ship the 26 MB asyncify wasm under static-host
+  // file-size limits; hosts that self-host a compressed copy set this to
+  // e.g. "/assets/". Defaults to the runtime's own resolution.
+  wasmPaths = null,
+} = {}) {
+  const tf = transformers ?? (await import("@huggingface/transformers"));
+  if (wasmPaths) {
+    try {
+      tf.env.backends.onnx.wasm.wasmPaths = wasmPaths;
+    } catch { /* older runtime: ignore */ }
+  }
+  const remote = await loadModelConfig({ model, revision, fetchImpl });
+  const resolvedDevice = resolveDevice({ device, webgpu: await detectWebGPU(scope) });
+  const resolvedDtype = resolveDtype(resolvedDevice, dtype);
+
+  const report = (phase) => (p) =>
+    onProgress?.({
+      phase,
+      status: p?.status ?? null,
+      file: p?.file ?? null,
+      loaded: p?.loaded ?? null,
+      total: p?.total ?? null,
+      progress: p?.progress ?? null,
+    });
+
+  const tokenizer = await tf.AutoTokenizer.from_pretrained(model, {
+    revision,
+    progress_callback: report("tokenizer"),
+  });
+  const net = await tf.AutoModel.from_pretrained(model, {
+    revision,
+    dtype: resolvedDtype,
+    device: resolvedDevice,
+    progress_callback: report("model"),
+  });
+
+  const encode = (text) => Array.from(tokenizer(text, { add_special_tokens: false }).input_ids.data, Number);
+  const markers = typedMarkerIds(encode, { markers: remote.markers });
+
+  const effective = {
+    temperature: Number.isFinite(temperature) ? temperature : remote.temperature,
+    maxStateTokens: Number.isFinite(maxStateTokens) ? maxStateTokens : remote.maxStateTokens,
+    maxLen: remote.maxLen,
+  };
+
+  const i64 = (values, dims) => new tf.Tensor("int64", BigInt64Array.from(values, BigInt), dims);
+
+  return {
+    info: {
+      family: "open-jev",
+      model,
+      revision,
+      device: resolvedDevice,
+      dtype: resolvedDtype,
+      temperature: effective.temperature,
+      maxStateTokens: effective.maxStateTokens,
+      maxLen: effective.maxLen,
+      pool: remote.pool,
+      configSource: remote.source,
+    },
+    async decide(state, questions) {
+      const t0 = now();
+      const normalized = normalizeQuestions(questions);
+      const tokenized = normalized.map((q) => ({
+        type: q.type,
+        instructionIds: encode(q.instructions),
+        optionIds: q.options.map((option) => encode(option)),
+      }));
+      const stateIds = encode(String(state ?? ""));
+      const input = buildDecisionInput({
+        stateIds,
+        markers,
+        questions: tokenized,
+        maxStateTokens: effective.maxStateTokens,
+        maxLen: effective.maxLen,
+      });
+      const feeds = {
+        input_ids: i64(input.inputIds, [1, input.length]),
+        attention_mask: i64(input.inputIds.map(() => 1), [1, input.length]),
+        seg: i64(input.seg, [1, input.length]),
+        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);
+      const answers = answersFromScores(scores, {
+        questions: normalized,
+        groups: input.groups,
+        temperature: effective.temperature,
+      });
+      // 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 = [];
+      for (const c of cases ?? []) out.push(await this.decide(c.state, c.questions));
+      return out;
+    },
+    dispose() {
+      net?.dispose?.();
+    },
+  };
+}