jev-web 0.2.0

package/README.md

@@ -0,0 +1,171 @@
+# jev-web
+
+Run **open-jev-shaped typed-decision models** in the browser. One *state* text
+plus any number of typed *questions* (`choice` / `score` / `noul`) go in; a
+calibrated probability distribution per question comes back from a single
+forward pass. No server, no API keys — weights and inference stay on-device.
+
+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 you give it.
+
+## Install
+
+```bash
+npm i jev-web @huggingface/transformers
+```
+
+`@huggingface/transformers` is an optional peer dependency (it is imported
+lazily). Hosts that already ship their own copy can inject it via
+`createDecider({ transformers })`.
+
+## Use
+
+```js
+import { createDecider } from "jev-web";
+
+const decider = await createDecider({
+  // defaults to the reference open-jev DeBERTa-v3-large ONNX export,
+  // pinned by revision; any repo with the same typed-decision graph works
+  onProgress: (p) => console.log(p.phase, p.file, p.progress),
+});
+
+const { answers } = await decider.decide(
+  "I was charged twice for the same order and nobody answers my emails.",
+  [
+    {
+      type: "choice",
+      instructions: "Which product area is the message about?",
+      options: ["fees & charges", "refund & dispute", "card", "other"],
+    },
+    { type: "noul", instructions: "The customer is asking for a refund." },
+    {
+      type: "score",
+      instructions: "How negative is the message?",
+      options: ["very negative", "negative", "neutral", "positive", "very positive"],
+    },
+  ],
+);
+
+// [
+//   { type: "choice", choice: "refund & dispute", index: 1, probabilities: {...}, confidence: 0.61 },
+//   { type: "noul",  noul: 0.93, probabilities: { no: 0.07, yes: 0.93 }, confidence: 0.93 },
+//   { type: "score", score: 0.4,  level: 1, probabilities: {...}, confidence: 0.55 },
+// ]
+```
+
+## Question types
+
+| type | options | answer |
+|---|---|---|
+| `choice` | 2–255 labels | `choice` (argmax), `probabilities`, `confidence` |
+| `score` | 2–10 ordered levels | `score` (expected level index, may fall between levels) |
+| `noul` | exactly 2 (defaults `["no","yes"]`) | `noul` (p of the second option = p(yes)), `confidence` |
+
+Every answer carries the full distribution. `decide()` also returns
+`{ truncated, length }` — the state is capped (256 tokens by default) and the
+flag tells you when it was cut.
+
+## Backends and quantization
+
+`device` / `dtype` default to `auto`: WebGPU → `q4f16`, otherwise WASM → `q4`.
+Override explicitly (`fp16`, `fp32`, `q8`, …) when accuracy matters more than
+download size. First load downloads the weights once; transformers.js caches
+them (Cache API / IndexedDB) so later visits are offline-fast.
+
+`decider.info` reports the resolved `{ model, revision, device, dtype,
+temperature, maxStateTokens, maxLen, pool, configSource }`.
+
+## Model config
+
+Defaults come from the model repo's `open_jev_config.json` when present
+(temperature, marker tokens, state cap), else the published reference values.
+To use a different typed-decision export:
+
+```js
+createDecider({ model: "your-org/your-typed-decision-ONNX", revision: "main" });
+```
+
+The export must add the `[STATE]`, `[Q]`, `[OPT]` markers to its tokenizer,
+take `input_ids, attention_mask, seg, pair_q, pair_opt`, and return per-pair
+`logits`. `typedMarkerIds()` fails loudly when a repo is missing them.
+
+
+## Laya family (ModernBERT encoder + typed head)
+
+`createLayaDecider(options)` runs the [Laya](https://huggingface.co/convaiinnovations/laya)
+System-1 decision models, whose browser export is a **two-file q8 ONNX split**
+(encoder + head) rather than one fused graph:
+
+```js
+import { createLayaDecider } from "jev-web";
+
+const decider = await createLayaDecider({
+  // defaults to alfred361/laya-typed-decisions-web-q8 @ pinned revision
+  wasmPaths: "/assets/",            // self-hosted ORT wasm (optional)
+  onProgress: (p) => console.log(p.phase, p.loaded, p.total),
+});
+const { answers } = await decider.decide(stateText, questions);
+```
+
+Protocol implemented here (mirrors the reference `laya` Python runtime):
+
+- sequence `[CLS] <type> question: <instructions> [SEP] [MASK]opt0 … [SEP] <state> [SEP]`,
+  `marker_pos` at each option's `[MASK]`, `qtype` 0 choice / 1 score / 2 noul;
+- encoder `input_ids, attention_mask → hidden`; head
+  `hidden, attention_mask, marker_pos, marker_mask, qtype → logits`;
+- per-question calibration from `rl_agent_config.json`
+  (`temperature` + `temperature_by_options` buckets, clamped to [0.5, 5]).
+
+Notes:
+- the q8 web head is **batch-1 only**, so `decide()` batches the encoder and
+  runs the head once per question;
+- `choice` supports at most `max_prefixes` options (6 for the typed-decisions
+  export);
+- weights download once (~520 MB q8) and are browser-cached.
+
+Lower-level helpers are exported for custom runtimes:
+`buildLayaSequence`, `collateLayaItems`, `layaAnswersFromLogits`,
+`layaTokenizerAdapter`, `renderLayaOptions`, `layaTempBucket`, `clampTemperature`.
+
+## Worker / thread
+
+`jev-web` does not bundle a worker, so hosts can create one the way their
+bundler prefers:
+
+```js
+// host code
+const worker = new Worker(new URL("./my-worker.mjs", import.meta.url), { type: "module" });
+// my-worker.mjs
+import { createDecider } from "jev-web";
+```
+
+## API
+
+- `createDecider(options)` → open-jev family: `{ info, decide, decideMany, dispose }`
+- `createLayaDecider(options)` → Laya family: `{ info, decide, dispose }` (same `decide` contract)
+- `normalizeQuestions`, `buildDecisionInput`, `typedMarkerIds`, `answersFromScores`,
+  `softmaxWithTemperature`, `resolveDevice`, `resolveDtype`, `detectWebGPU`,
+  `loadModelConfig`, defaults (model/revision/temperature/caps).
+
+## Playground
+
+```bash
+npm run dev   # packages/jev-web → http://localhost:5188
+```
+
+Generic presets plus a paste-your-own state/questions box, download progress,
+latency, and a model-cache reset.
+
+## Limits
+
+- Typed-decision models answer **only** by picking among your options; they do
+  not explain or generate text.
+- Accuracy is domain-bound: questions and states unlike the model's training
+  domain are out of distribution. Measure before relying on any answer.
+- English, 512-token sequence (state capped), one state per forward pass.
+
+## License
+
+MIT (runtime code). Model weights keep their own license (the reference export
+is Apache-2.0).

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "jev-web",
+  "version": "0.2.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",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "open-jev",
+    "typed-decisions",
+    "onnx",
+    "transformers.js",
+    "webgpu",
+    "browser",
+    "classification"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build:dev": "vite build",
+    "test": "node --test test/*.test.mjs"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": ">=3.0.0",
+    "onnxruntime-web": ">=1.17.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    },
+    "onnxruntime-web": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@huggingface/transformers": "^4.3.0",
+    "vite": "^6.3.5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/answers.mjs

@@ -0,0 +1,36 @@
+// jev-web — score → answer decoding for typed-decision models.
+//
+// The graph returns one logit per (question, option) pair. Each question's
+// options form a softmax group; a post-hoc temperature (fitted by the model
+// authors) calibrates the distribution.
+
+export function softmaxWithTemperature(logits, temperature = 1) {
+  const t = Number.isFinite(temperature) && temperature > 0 ? temperature : 1;
+  if (!Array.isArray(logits) || logits.length === 0) throw new TypeError("logits must be a non-empty array");
+  const max = Math.max(...logits);
+  const exps = logits.map((x) => Math.exp((Number(x) - max) / t));
+  const sum = exps.reduce((a, b) => a + b, 0);
+  return exps.map((e) => e / sum);
+}
+
+export function answersFromScores(scores, { questions, groups, temperature = 1 }) {
+  if (!Array.isArray(scores)) throw new TypeError("scores must be an array");
+  return questions.map((q, i) => {
+    const pairIndices = groups[i];
+    const probs = softmaxWithTemperature(pairIndices.map((p) => scores[p]), temperature);
+    const probabilities = Object.fromEntries(q.options.map((option, j) => [option, probs[j]]));
+    const confidence = Math.max(...probs);
+    const best = probs.indexOf(confidence);
+
+    if (q.type === "choice") {
+      return { type: "choice", choice: q.options[best], index: best, probabilities, confidence };
+    }
+    if (q.type === "score") {
+      const expected = probs.reduce((acc, p, j) => acc + p * j, 0);
+      return { type: "score", score: expected, level: best, probabilities, confidence };
+    }
+    // noul: probabilities are { no, yes }; the answer is p(yes).
+    const yes = probabilities[q.options[1]];
+    return { type: "noul", noul: yes, probabilities, confidence: Math.max(yes, 1 - yes) };
+  });
+}

package/src/config.mjs

@@ -0,0 +1,65 @@
+// jev-web — model defaults, backend resolution, and model-side config.
+//
+// Defaults point at the reference ONNX export of com-kotobalabs/open-jev-
+// deberta-v3-large (Apache-2.0), pinned by revision for reproducibility. Any
+// repo with the same typed-decision graph layout works: pass `model` and
+// optionally `revision`.
+
+export const DEFAULT_MODEL = "onnx-community/open-jev-deberta-v3-large-ONNX";
+export const DEFAULT_REVISION = "7c79f25b5ac496089f448a969c801872ad59d31c";
+export const DEFAULT_TEMPERATURE = 1.05;
+export const DEFAULT_MARKERS = ["[STATE]", "[Q]", "[OPT]"];
+export const DEFAULT_MAX_STATE_TOKENS = 256;
+export const DEFAULT_MAX_LEN = 512;
+
+const HF_BASE = "https://huggingface.co";
+
+export function resolveDevice({ device = "auto", webgpu = false } = {}) {
+  if (device && device !== "auto") return device;
+  return webgpu ? "webgpu" : "wasm";
+}
+
+// Quantized WebGPU kernels are f16-friendly (q4f16); WASM wants the
+// non-f16 q4 build. fp32/fp16/q8 stay explicit opt-ins.
+export function resolveDtype(device, dtype = "auto") {
+  if (dtype && dtype !== "auto") return dtype;
+  return device === "webgpu" ? "q4f16" : "q4";
+}
+
+export async function detectWebGPU(scope = globalThis) {
+  try {
+    if (!scope?.navigator?.gpu?.requestAdapter) return false;
+    return !!(await scope.navigator.gpu.requestAdapter());
+  } catch {
+    return false;
+  }
+}
+
+// Read the model's own calibration/marker config when the repo ships one
+// (open_jev_config.json), else fall back to the published reference values.
+export async function loadModelConfig({ model = DEFAULT_MODEL, revision = DEFAULT_REVISION, fetchImpl = fetch } = {}) {
+  const fallback = {
+    temperature: DEFAULT_TEMPERATURE,
+    markers: [...DEFAULT_MARKERS],
+    maxStateTokens: DEFAULT_MAX_STATE_TOKENS,
+    maxLen: DEFAULT_MAX_LEN,
+    pool: "span",
+    source: "defaults",
+  };
+  const url = `${HF_BASE}/${model}/resolve/${revision ? `${revision}/` : ""}open_jev_config.json`;
+  try {
+    const res = await fetchImpl(url, { cache: "no-store" });
+    if (!res.ok) return fallback;
+    const cfg = await res.json();
+    return {
+      temperature: Number.isFinite(Number(cfg.temperature)) ? Number(cfg.temperature) : fallback.temperature,
+      markers: Array.isArray(cfg.markers) && cfg.markers.length === 3 ? cfg.markers.map(String) : fallback.markers,
+      maxStateTokens: Number.isFinite(Number(cfg.max_state_tokens)) ? Number(cfg.max_state_tokens) : fallback.maxStateTokens,
+      maxLen: Number.isFinite(Number(cfg.max_len)) ? Number(cfg.max_len) : fallback.maxLen,
+      pool: typeof cfg.pool === "string" ? cfg.pool : fallback.pool,
+      source: "model",
+    };
+  } catch {
+    return fallback;
+  }
+}

package/src/encode.mjs

@@ -0,0 +1,83 @@
+// jev-web — pure input builder for open-jev-shaped models.
+//
+// Layout produced (mirrors the reference export):
+//   [CLS] [STATE] state [Q] instructions [OPT] option … [SEP]
+//
+// `seg` carries a span slot per token: option tokens get their pair index,
+// question-instruction tokens get `totalPairs + question index`, everything
+// else -1. `pair_q` / `pair_opt` list the question slot and pair slot for
+// every (question, option) pair; `groups` groups pair indices per question.
+// The ONNX graph consumes these directly (see the model's export docs).
+
+export class DecisionInputTooLongError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DecisionInputTooLongError";
+  }
+}
+
+// Runtime-independent: take pre-tokenized ids and lay out the sequence.
+export function buildDecisionInput({
+  stateIds,
+  markers, // { cls, sep, state, question, option } single token ids
+  questions, // [{ type, instructionIds: number[], optionIds: number[][] }]
+  maxStateTokens = 256,
+  maxLen = 512,
+}) {
+  if (!Array.isArray(stateIds)) throw new TypeError("stateIds must be an array of token ids");
+  if (!Array.isArray(questions) || questions.length === 0) {
+    throw new TypeError("questions must be a non-empty array of tokenized questions");
+  }
+  for (const key of ["cls", "sep", "state", "question", "option"]) {
+    if (!Number.isInteger(markers?.[key])) throw new TypeError(`markers.${key} must be a token id`);
+  }
+
+  const truncated = stateIds.length > maxStateTokens;
+  const state = truncated ? stateIds.slice(0, maxStateTokens) : stateIds;
+
+  const inputIds = [markers.cls, markers.state, ...state];
+  const seg = inputIds.map(() => -1);
+  const pairQ = [];
+  const pairOpt = [];
+  const groups = [];
+  const totalPairs = questions.reduce((n, q) => n + q.optionIds.length, 0);
+
+  questions.forEach((q, qi) => {
+    inputIds.push(markers.question, ...q.instructionIds);
+    seg.push(-1, ...q.instructionIds.map(() => totalPairs + qi));
+    groups.push(
+      q.optionIds.map((ids) => {
+        inputIds.push(markers.option, ...ids);
+        seg.push(-1, ...ids.map(() => pairOpt.length));
+        pairQ.push(totalPairs + qi);
+        pairOpt.push(pairOpt.length);
+        return pairOpt.length - 1;
+      }),
+    );
+  });
+  inputIds.push(markers.sep);
+  seg.push(-1);
+
+  if (inputIds.length > maxLen) {
+    throw new DecisionInputTooLongError(
+      `decision input is ${inputIds.length} tokens, over the ${maxLen}-token limit ` +
+        `(state capped at ${maxStateTokens}) — shorten the questions or the state`,
+    );
+  }
+  return { inputIds, seg, pairQ, pairOpt, groups, truncated, length: inputIds.length, totalPairs };
+}
+
+// Shared marker lookup: every marker must encode to exactly one token id.
+// (Custom typed-decision exports add [STATE]/[Q]/[OPT] to the tokenizer; if
+// they are missing, the model is not a typed-decision export.)
+export function typedMarkerIds(encodeFn, { markers = ["[STATE]", "[Q]", "[OPT]"], cls = "[CLS]", sep = "[SEP]" } = {}) {
+  const one = (text) => {
+    const ids = encodeFn(text);
+    if (!Array.isArray(ids) || ids.length !== 1) {
+      throw new Error(`marker ${text} must encode to exactly one token (got ${ids?.length ?? 0})`);
+    }
+    return ids[0];
+  };
+  const [state, question, option] = markers.map(one);
+  return { cls: one(cls), sep: one(sep), state, question, option };
+}

package/src/index.mjs

@@ -0,0 +1,38 @@
+// jev-web — public API (typed decisions in the browser).
+export { createDecider } from "./session.mjs";
+export { normalizeQuestions, QUESTION_TYPES, NOUL_OPTIONS } from "./questions.mjs";
+export { buildDecisionInput, typedMarkerIds, DecisionInputTooLongError } from "./encode.mjs";
+export { answersFromScores, softmaxWithTemperature } from "./answers.mjs";
+export {
+  createLayaDecider,
+  buildLayaSequence,
+  collateLayaItems,
+  layaAnswersFromLogits,
+  layaTokenizerAdapter,
+  renderLayaOptions,
+  layaTempBucket,
+  clampTemperature,
+  LAYA_DEFAULT_MODEL,
+  LAYA_DEFAULT_REVISION,
+  LAYA_DEFAULT_SUBFOLDER,
+  LAYA_DEFAULT_TEMPERATURES,
+  LAYA_DEFAULT_TEMPERATURES_BY_OPTIONS,
+  LAYA_DEFAULT_MAX_LEN,
+  LAYA_DEFAULT_HEAD_MAX_LEN,
+  LAYA_DEFAULT_MAX_PREFIXES,
+  LAYA_QTYPE,
+  LAYA_TEMP_MIN,
+  LAYA_TEMP_MAX,
+} from "./laya.mjs";
+export {
+  DEFAULT_MODEL,
+  DEFAULT_REVISION,
+  DEFAULT_TEMPERATURE,
+  DEFAULT_MARKERS,
+  DEFAULT_MAX_STATE_TOKENS,
+  DEFAULT_MAX_LEN,
+  resolveDevice,
+  resolveDtype,
+  detectWebGPU,
+  loadModelConfig,
+} from "./config.mjs";

package/src/laya.mjs

@@ -0,0 +1,386 @@
+/**
+ * laya.mjs — Laya System-1 decision models (ModernBERT encoder + typed head).
+ *
+ * The Laya family is a *different graph* from open-jev:
+ *   encoder: input_ids, attention_mask -> hidden  (last_hidden_state)
+ *   head:    hidden, marker_pos, marker_mask, qtype -> logits, act_logits
+ *
+ * Sequence layout (mirrors the reference `laya` Python runtime,
+ * `laya/common.py build_sequence`):
+ *   [CLS] <type> question: <instructions> [SEP] [MASK]opt0 [MASK]opt1 … [SEP] <state> [SEP]
+ * `marker_pos` points at each option's [MASK]; `qtype` is 0 choice / 1 score /
+ * 2 noul. Logits are calibrated per question type *and* option-count bucket
+ * (rl_agent_config.json `temperature` / `temperature_by_options`), clamped to
+ * [0.5, 5] like the Python runtime.
+ *
+ * The browser export used here is a two-file q8 ONNX split
+ * (alfred361/laya-typed-decisions-web-q8, pinned by revision).
+ */
+
+import { normalizeQuestions } from "./questions.mjs";
+import { softmaxWithTemperature } from "./answers.mjs";
+
+export const LAYA_DEFAULT_MODEL = "alfred361/laya-typed-decisions-web-q8";
+export const LAYA_DEFAULT_REVISION = "96f637c0bee046dce5c61a3174de9f7cdcf09ace";
+export const LAYA_DEFAULT_SUBFOLDER = "v1";
+
+/** Reference calibration from the typed-decisions rl_agent_config.json. */
+export const LAYA_DEFAULT_TEMPERATURES = [1.0148024559020996, 1.0374259948730469, 1.0575125217437744];
+export const LAYA_DEFAULT_TEMPERATURES_BY_OPTIONS = {
+  "choice:3-5": 1.7601518630981445,
+  "choice:6-10": 1.0000158548355103,
+  "score:3-5": 1.2514300346374512,
+  "noul:2": 1.983399510383606,
+  "choice:11+": 0.10058280825614929,
+  "choice:2": 1.9063563346862793,
+};
+export const LAYA_DEFAULT_MAX_LEN = 1024;
+export const LAYA_DEFAULT_HEAD_MAX_LEN = 256;
+export const LAYA_DEFAULT_MAX_PREFIXES = 6;
+
+export const LAYA_QTYPE = { choice: 0, score: 1, noul: 2 };
+const QTYPE_NAMES = { 0: "choice", 1: "score", 2: "noul" };
+
+// The Python runtime refuses temperatures outside [0.5, 5]: the shipped
+// `choice:11+` bucket (0.1006) would sharpen logits ~10x and publish a coin
+// flip as near-certainty.
+export const LAYA_TEMP_MIN = 0.5;
+export const LAYA_TEMP_MAX = 5;
+
+export function clampTemperature(t, lo = LAYA_TEMP_MIN, hi = LAYA_TEMP_MAX) {
+  const n = Number(t);
+  if (!Number.isFinite(n)) return 1;
+  return Math.min(hi, Math.max(lo, n));
+}
+
+export function layaTempBucket(qtype, k) {
+  const size = k <= 2 ? "2" : k <= 5 ? "3-5" : k <= 10 ? "6-10" : "11+";
+  return `${QTYPE_NAMES[qtype]}:${size}`;
+}
+
+/**
+ * Option texts exactly as the reference runtime renders them.
+ * Our normalized questions carry no per-option criteria, so choice options
+ * render as their labels and noul falls back to the reference wording.
+ */
+export function renderLayaOptions(question) {
+  if (question.type === "choice") return question.options.map(String);
+  if (question.type === "score") return question.options.map((c, i) => `level ${i}: ${c}`);
+  // noul
+  const [no, yes] = question.options;
+  if (no === "no" && yes === "yes") {
+    return ["false: no, the statement does not hold", "true: yes, the statement holds"];
+  }
+  return [`false: ${no}`, `true: ${yes}`];
+}
+
+/**
+ * Build one Laya sequence + marker positions.
+ * @param {{encode:(text:string)=>number[], ids:{cls:number,sep:number,mask:number},
+ *   state:string, question:object, maxLen?:number, headMaxLen?:number,
+ *   maxPrefixes?:number}} spec
+ * @returns {{ids:number[], markers:number[], qtype:number}}
+ */
+export function buildLayaSequence({
+  encode,
+  ids,
+  state,
+  question,
+  maxLen = LAYA_DEFAULT_MAX_LEN,
+  headMaxLen = LAYA_DEFAULT_HEAD_MAX_LEN,
+  maxPrefixes = LAYA_DEFAULT_MAX_PREFIXES,
+}) {
+  const options = renderLayaOptions(question);
+  if (options.length > maxPrefixes) {
+    throw new RangeError(
+      `laya: ${question.type} with ${options.length} options exceeds max_prefixes=${maxPrefixes}`);
+  }
+  const qtype = LAYA_QTYPE[question.type];
+  if (qtype === undefined) throw new TypeError(`laya: unsupported question type ${question.type}`);
+
+  const strip = (s) => String(s).replace(/\[MASK\]/g, " ");
+  let headIds = encode(`${question.type} question: ${strip(question.instructions)}`);
+  let optIds = options.map((o) => [ids.mask, ...encode(` ${strip(o)}`).slice(0, 48)]);
+
+  let optBudget = headMaxLen - optIds.reduce((n, o) => n + o.length, 0);
+  if (optBudget < 16) {
+    const per = Math.max(4, Math.floor((headMaxLen - 16) / Math.max(1, optIds.length)));
+    optIds = optIds.map((o) => o.slice(0, per));
+    optBudget = headMaxLen - optIds.reduce((n, o) => n + o.length, 0);
+  }
+  headIds = headIds.slice(0, Math.max(8, optBudget));
+
+  let seq = [ids.cls, ...headIds, ids.sep];
+  const markers = [];
+  for (const o of optIds) {
+    markers.push(seq.length);
+    seq.push(...o);
+  }
+  seq.push(ids.sep);
+  const room = Math.max(0, maxLen - seq.length - 1);
+  const stateIds = encode(String(state ?? "")).slice(0, room);
+  seq = [...seq, ...stateIds, ids.sep];
+
+  const clipped = seq.slice(0, maxLen);
+  return {
+    ids: clipped,
+    markers: markers.filter((m) => m < maxLen),
+    qtype,
+  };
+}
+
+/** Pad a batch of Laya items into int64/bool tensors. */
+export function collateLayaItems(items, padId = 0) {
+  const n = items.length;
+  const L = Math.max(...items.map((it) => it.ids.length));
+  const M = Math.max(...items.map((it) => it.markers.length));
+  const inputIds = new BigInt64Array(n * L).fill(BigInt(padId));
+  const attention = new BigInt64Array(n * L);
+  const markerPos = new BigInt64Array(n * M);
+  const markerMask = new Uint8Array(n * M);
+  const qtype = new BigInt64Array(n);
+  items.forEach((it, i) => {
+    it.ids.forEach((v, j) => { inputIds[i * L + j] = BigInt(v); attention[i * L + j] = 1n; });
+    it.markers.forEach((m, j) => { markerPos[i * M + j] = BigInt(m); markerMask[i * M + j] = 1; });
+    qtype[i] = BigInt(it.qtype);
+  });
+  return { n, L, M, inputIds, attention, markerPos, markerMask, qtype };
+}
+
+/**
+ * Decode head logits (row-major [question][marker]) into jev-web answers.
+ * @param {{logits:number[]|Float32Array, questions:object[], markerCounts:number[],
+ *   temperatures?:number[], temperatureByOptions?:object}} spec
+ */
+export function layaAnswersFromLogits({
+  logits,
+  questions,
+  markerCounts,
+  temperatures = LAYA_DEFAULT_TEMPERATURES,
+  temperatureByOptions = LAYA_DEFAULT_TEMPERATURES_BY_OPTIONS,
+}) {
+  const answers = [];
+  let offset = 0;
+  questions.forEach((q, i) => {
+    const k = markerCounts[i];
+    const qtype = LAYA_QTYPE[q.type];
+    const t = clampTemperature(
+      temperatureByOptions[layaTempBucket(qtype, k)] ?? temperatures[qtype] ?? 1,
+    );
+    const probs = softmaxWithTemperature(Array.from(logits.slice(offset, offset + k), Number), t);
+    offset += k;
+
+    const entropy = k > 1
+      ? -probs.reduce((acc, p) => acc + p * Math.log(Math.max(p, 1e-12)), 0) / Math.log(k)
+      : 0;
+    const confidence = Math.min(1, Math.max(0, 1 - entropy));
+    const best = probs.indexOf(Math.max(...probs));
+
+    if (q.type === "choice") {
+      answers.push({
+        type: "choice",
+        choice: q.options[best],
+        index: best,
+        probabilities: Object.fromEntries(q.options.map((o, j) => [o, probs[j]])),
+        confidence,
+      });
+    } else if (q.type === "score") {
+      const expected = probs.reduce((acc, p, j) => acc + p * j, 0);
+      answers.push({
+        type: "score",
+        score: expected,
+        level: best,
+        probabilities: Object.fromEntries(q.options.map((o, j) => [o, probs[j]])),
+        confidence,
+      });
+    } else {
+      const yes = probs[1];
+      answers.push({
+        type: "noul",
+        noul: yes,
+        probabilities: { [q.options[0]]: probs[0], [q.options[1]]: probs[1] },
+        confidence: Math.max(yes, 1 - yes),
+      });
+    }
+  });
+  return answers;
+}
+
+/** Wrap a transformers.js tokenizer into the tiny adapter laya needs. */
+export function layaTokenizerAdapter(tok) {
+  const idOf = (prop, text) => {
+    const direct = tok?.[prop];
+    if (Number.isFinite(direct)) return Number(direct);
+    const ids = tok.encode?.(text) ?? tok(text, { add_special_tokens: true }).input_ids?.data;
+    return Number(Array.from(ids ?? [])[0] ?? 0);
+  };
+  return {
+    encode: (text) => Array.from(tok(text, { add_special_tokens: false }).input_ids.data, Number),
+    ids: {
+      cls: idOf("cls_token_id", "[CLS]"),
+      sep: idOf("sep_token_id", "[SEP]"),
+      mask: idOf("mask_token_id", "[MASK]"),
+    },
+    pad: idOf("pad_token_id", "[PAD]"),
+  };
+}
+
+const hfUrl = (model, revision, file) =>
+  `https://huggingface.co/${model}/resolve/${revision ? `${revision}/` : ""}${file}`;
+
+/**
+ * Create a Laya decider.
+ *
+ * @param {object} [opts]
+ *  model/revision/subfolder — pinned web-q8 ONNX export (or your own mirror)
+ *  encoderUrl/headUrl       — override the resolved ONNX URLs
+ *  ort                      — injected onnxruntime-web (lazy import otherwise)
+ *  transformers             — injected @huggingface/transformers (tokenizer only)
+ *  wasmPaths                — ORT wasm/loader directory (self-hosted builds)
+ *  device                   — "auto" | "wasm" | "webgpu"
+ */
+export async function createLayaDecider({
+  model = LAYA_DEFAULT_MODEL,
+  revision = LAYA_DEFAULT_REVISION,
+  subfolder = LAYA_DEFAULT_SUBFOLDER,
+  encoderUrl = null,
+  headUrl = null,
+  tokenizerModel = null,
+  tokenizerSubfolder = null,
+  ort = null,
+  transformers = null,
+  wasmPaths = null,
+  device = "auto",
+  // (url, sessionOptions) => Promise<InferenceSession>. Hosts that need custom
+  // loading (local files, bundled weights, offline mirrors) override this.
+  sessionFactory = null,
+  onProgress = null,
+  maxLen = LAYA_DEFAULT_MAX_LEN,
+  headMaxLen = LAYA_DEFAULT_HEAD_MAX_LEN,
+  maxPrefixes = LAYA_DEFAULT_MAX_PREFIXES,
+  temperatures = LAYA_DEFAULT_TEMPERATURES,
+  temperatureByOptions = LAYA_DEFAULT_TEMPERATURES_BY_OPTIONS,
+  scope = globalThis,
+} = {}) {
+  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 executionProviders = resolvedDevice === "webgpu" ? ["webgpu", "wasm"] : ["wasm"];
+
+  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"),
+  });
+  const adapter = layaTokenizerAdapter(tok);
+
+  const encUrl = encoderUrl ?? hfUrl(model, revision, `${subfolder}/encoder_q8.onnx`);
+  const headUrlResolved = headUrl ?? hfUrl(model, revision, `${subfolder}/head_q8.onnx`);
+  const createSession = sessionFactory
+    ?? ((url, opts) => ortMod.InferenceSession.create(url, opts));
+  const loadPair = async (providers) => {
+    const opts = { executionProviders: providers, graphOptimizationLevel: "all" };
+    const enc = await createSession(encUrl, { ...opts, progress_callback: report("encoder") });
+    const hd = await createSession(headUrlResolved, { ...opts, progress_callback: report("head") });
+    return { enc, hd };
+  };
+  let encoder, head, activeDevice = resolvedDevice;
+  try {
+    ({ enc: encoder, hd: head } = await loadPair(executionProviders));
+  } catch (e) {
+    // A quantized graph can be rejected by the WebGPU EP at session creation;
+    // retry wasm-only before giving up (the caller may still fall back).
+    if (resolvedDevice === "webgpu") {
+      onProgress?.({ phase: `webgpu unavailable (${e?.message ?? e}) — retrying on wasm` });
+      ({ enc: encoder, hd: head } = await loadPair(["wasm"]));
+      activeDevice = "wasm";
+    } else {
+      throw e;
+    }
+  }
+
+  const int64 = (arr, dims) => new ortMod.Tensor("int64", arr, dims);
+  const bool = (arr, dims) => new ortMod.Tensor("bool", arr, dims);
+
+  return {
+    info: {
+      family: "laya",
+      model,
+      revision,
+      device: activeDevice,
+      dtype: "q8",
+      maxLen,
+      headMaxLen,
+      maxPrefixes,
+      // Single representative temperature for UIs that show one value
+      // (noul:2 bucket, else the noul type temperature); per-bucket values
+      // below are what the decoder actually applies.
+      temperature: clampTemperature(temperatureByOptions["noul:2"] ?? temperatures[2] ?? 1),
+      temperatures: temperatures.map(clampTemperature),
+      temperatureByOptions: Object.fromEntries(
+        Object.entries(temperatureByOptions).map(([k, v]) => [k, clampTemperature(v)])),
+    },
+    async decide(state, questions) {
+      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 encOut = await encoder.run({
+        input_ids: int64(b.inputIds, [b.n, b.L]),
+        attention_mask: int64(b.attention, [b.n, b.L]),
+      });
+      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 markerCounts = items.map((it) => it.markers.length);
+      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]);
+        const rowHidden = new ortMod.Tensor(hidden.type, row, [1, b.L, hidden.dims[2]]);
+        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 headOut = await head.run({
+          hidden: rowHidden,
+          attention_mask: int64(rowMask, [1, b.L]),
+          marker_pos: int64(rowPos, [1, k]),
+          marker_mask: bool(rowMarkerMask, [1, k]),
+          qtype: int64(b.qtype.subarray(i, i + 1), [1]),
+        });
+        const rowLogits = headOut.logits ?? headOut[Object.keys(headOut)[0]];
+        headLogits.push(...Array.from(rowLogits.data, Number));
+      }
+
+      const answers = layaAnswersFromLogits({
+        logits: headLogits,
+        questions: normalized,
+        markerCounts,
+        temperatures,
+        temperatureByOptions,
+      });
+      const length = Number(b.attention.reduce((a, v) => a + v, 0n));
+      return { answers, truncated: items.some((it) => it.ids.length >= maxLen), length };
+    },
+    async dispose() {
+      try { await encoder.release?.(); } catch { /* optional */ }
+      try { await head.release?.(); } catch { /* optional */ }
+    },
+  };
+}

package/src/questions.mjs

@@ -0,0 +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 };
+  });
+}

package/src/session.mjs

@@ -0,0 +1,132 @@
+// 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";
+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: {
+      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 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 out = await net(feeds);
+      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,
+      });
+      return { answers, truncated: input.truncated, length: input.length };
+    },
+    async decideMany(cases) {
+      const out = [];
+      for (const c of cases ?? []) out.push(await this.decide(c.state, c.questions));
+      return out;
+    },
+    dispose() {
+      net?.dispose?.();
+    },
+  };
+}