jev-web 0.3.2 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 warsang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,145 @@
 # jev-web
 
-Run **open-jev-shaped typed-decision models** in the browser. One *state* text
+[![npm](https://img.shields.io/npm/v/jev-web.svg)](https://www.npmjs.com/package/jev-web)
+[![license](https://img.shields.io/npm/l/jev-web.svg)](./LICENSE)
+[![CI](https://github.com/warsang/jev-web/actions/workflows/test.yml/badge.svg)](https://github.com/warsang/jev-web/actions/workflows/test.yml)
+
+Run **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.
+calibrated probability distribution per question comes back from a **single
+forward pass**. No server, no API keys, no network calls after the weights are
+cached.
+
+Three model families ship today — open-jev (fused DeBERTa graph), Laya
+(ModernBERT encoder + typed head), Strands Decider 2B (Qwen torso + pointer
+head), and Bekko System One v0 (Ettin cross-encoder) — 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
+you give it.
+
+## ▶ Live demo
+
+**https://warsang.github.io/jev-web/**
+
+An interactive playground that runs this exact package: type a state, add typed
+questions, and watch the model and a hand-written keyword baseline answer
+side by side. It also counts your actual outbound requests, so the
+"offline / private / no server" claim is checkable rather than asserted.
+
+![jev-web demo: typed decisions vs raw text parsing](docs/demo.gif)
+
+<sub>The frames are captured from the live demo at
+[warsang.github.io/jev-web](https://warsang.github.io/jev-web/) — site → typed
+decisions with latency → the negation case where the rules and the model
+disagree → the comparison matrix.</sub>
+
+Three questions, one forward pass, and a hard label from the rule parser that
+could not answer the third question at all:
 
-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.
+![three typed decisions with full distributions and a measured latency, beside a keyword baseline that returns hard labels and no answer](docs/demo-typed.png)
+
+## Quickstart
+
+```js
+import { createDecider } from "jev-web";
+
+const decider = await createDecider();          // ~340 MB of weights, once
+const { answers } = await decider.decide(
+  "I was charged twice for the same order.",
+  [{ type: "noul", instructions: "The customer is asking for a refund." }],
+);
+
+answers[0].noul;                    // 0.92   — p(yes)
+answers[0].probabilities;           // { no: 0.08, yes: 0.92 }
+answers[0].confidence;               // 0.92
+```
+
+That is the whole integration. The first call downloads the weights and the
+browser caches them; every later call — and every later visit, including
+offline — is local. **Zero dependencies**: `@huggingface/transformers` is an
+optional peer, imported lazily.
+
+## What comes back
+
+```js
+const { answers } = await decider.decide(
+  "I was charged twice for the same order and nobody answers my emails. I want my money back now.",
+  [
+    { 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: "fees & charges", index: 0,
+//     probabilities: { "fees & charges": 0.796, "refund & dispute": 0.169,
+//                      card: 0.019, other: 0.016 }, confidence: 0.796 },
+//   { type: "noul", noul: 0.927,
+//     probabilities: { no: 0.073, yes: 0.927 }, confidence: 0.927 },
+//   { type: "score", score: 0.866, level: 1,
+//     probabilities: { "very negative": 0.336, negative: 0.478, neutral: 0.175,
+//                      positive: 0.008, "very positive": 0.003 }, confidence: 0.478 },
+// ]
+// timings: { totalMs, inferMs }   ·  length, truncated, prompts
+```
+
+Three questions, **one** forward pass, and every question carries the full
+distribution — not just a label. That last part is the point: a hard label
+cannot be thresholded, routed by confidence, or second-guessed, and the
+`choice` answer above is a genuine 79.6 / 16.9 split rather than a coin flip you
+find out about later.
+
+## jev-web vs. calling a hosted LLM API with `fetch()`
+
+| | jev-web | Hosted LLM API via `fetch()` |
+|---|---|---|
+| **Cost per decision** | **$0.00** — the weights are static files | per-token, forever; a busy form multiplies it by every visitor |
+| **Latency** | one local forward pass, measured live on the demo page | typically 0.4–3 s, plus a network round trip |
+| **Network at answer time** | **0 requests** — works in airplane mode | one round trip per call, minimum |
+| **Output shape** | **calibrated distribution per question, every question in one pass** | prose you then have to regex back into a distribution |
+| **Determinism** | same input → same probabilities, always | temperature 0 + structured outputs helps; still not guaranteed |
+| **Privacy** | your text never leaves the device | your users' text is sent to a third party on every call |
+| **Ops burden** | static files on a CDN, no key, no rate limit | key management, quotas, rate limits, uptime, spend alerts |
+| **Ceiling** | only *picks among options you supply* — never writes, never explains | general purpose; will happily invent an option you never offered |
+
+**The honest trade.** jev-web is a classifier, not a chatbot. If you need
+free-form answers you need a generator. If you need a routing decision, a score,
+or a yes/no with a confidence you can threshold on, this is the cheaper, faster
+and private one — and it is also *smaller*: a 0.5 B model plus your options
+beats a frontier model plus a parsing layer, on every axis except generality.
+
+## Try it before you install it
+
+The live demo covers the interesting cases, and the presets are chosen to break
+keyword parsing rather than to flatter the model:
+
+| preset | what it shows |
+|---|---|
+| **Banking triage** | easy text — a fair rule can match, the model adds a confidence |
+| **Negation trap** | *"This is not about a refund. My card was stolen…"* — the keyword rule routes to `refund & dispute`; the model routes to `card` (53.3%) and answers the refund question **no** (0.101) |
+| **Contradictory review** | praise and complaint in one sentence; keyword polarity reads the praise |
+| **Mixed intent** | two intents in one state — a hard label must pick one, a distribution does not have to |
+| **Out of domain** | no in-domain signal at all; the rule parser has nothing to say |
+
+The negation case is the one worth looking at. The state is *"This is not about
+a refund. My card was stolen in Madrid and the bank refuses to help. I never
+received the money back I asked about."*
+
+![negation: the keyword baseline routes to refund and dispute, the model routes to card](docs/demo-negation.png)
+
+The rule parser finds the word `refund` and routes to **refund & dispute** — the
+exact opposite of what the customer meant. The model routes to **card** (53.3%)
+and answers *"the customer is asking for a refund"* with **no** (0.101). Both
+the bad routing and the inversion come from the same clause, and neither is
+visible in a hard label.
+
+The demo also tracks outbound requests through the Performance API: you will see
+~14 requests while the weights load, then **0** for every decision after that.
 
 ## Install
 
@@ -22,7 +154,7 @@ lazily). Hosts that already ship their own copy can inject it via
 ## Use
 
 ```js
-import { createDecider } from "jev-web";
+import { createDecider, DEFAULT_MODEL, DEFAULT_REVISION } from "jev-web";
 
 const decider = await createDecider({
   // defaults to the reference open-jev DeBERTa-v3-large ONNX export,
@@ -46,12 +178,6 @@ const { answers } = await decider.decide(
     },
   ],
 );
-
-// [
-//   { 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
@@ -90,7 +216,6 @@ 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.
 
-
 ## Multiple families (registry)
 
 `jev-web` is a multi-family runtime: `createDecisionRuntime({ family, fallback })`
@@ -100,10 +225,10 @@ tries the requested family and then any fallbacks, returning the shared contract
 ```js
 import { createDecisionRuntime, listDecisionFamilies } from "jev-web";
 
-listDecisionFamilies(); // ["open-jev", "laya"]
+listDecisionFamilies(); // ["open-jev", "laya", "strands-decider", "bekko"]
 const runtime = await createDecisionRuntime({
-  family: "laya",
-  fallback: ["open-jev"],
+  family: "strands-decider",
+  fallback: ["laya", "open-jev"],
   onFallback: ({ family, error }) => console.warn(family, error),
 });
 const { answers, truncated, length, prompts, timings } = await runtime.decide(state, questions);
@@ -158,6 +283,89 @@ Lower-level helpers are exported for custom runtimes:
 `buildLayaSequence`, `collateLayaItems`, `layaAnswersFromLogits`,
 `layaTokenizerAdapter`, `renderLayaOptions`, `layaTempBucket`, `clampTemperature`.
 
+## Strands Decider family (Qwen torso + pointer head)
+
+`createStrandsDecider(options)` runs
+[Strands Decider 2B](https://strandsagents.com/blog/introducing-strands-decider/),
+a 2B-parameter decision model: a Qwen3.5-2B torso (LoRA merged) with its LM head
+replaced by a pointer head that scores each option from its own hidden state
+against the `<answer>` position. One fused ONNX graph, one forward pass for the
+whole batch:
+
+```js
+import { createStrandsDecider } from "jev-web";
+
+const decider = await createStrandsDecider({
+  // defaults to onnx-community/strands-decider-2B-hobson-v19-ONNX @ pinned
+  // revision, q8 (onnx/model_quantized.onnx)
+  onProgress: (p) => console.log(p.phase, p.loaded, p.total),
+});
+const { answers } = await decider.decide(stateText, questions);
+```
+
+Protocol implemented here (mirrors the reference Python runtime):
+
+- prompt `<state>…</state><question type="{noul|choice|score}">…<options>\n1. …\n</options></question><answer>`;
+- graph `input_ids, attention_mask, answer_pos, option_pos → logits`, where
+  `answer_pos` is each row's last real token (the `<answer>` pooling position)
+  and `option_pos` carries each option line's last-token position (padded with
+  0); the prompt is tokenised in chunks at pre-tokeniser piece boundaries so
+  those positions are exact with no offset mapping;
+- choice questions accept `criteria` as `{label: description}` (mirroring the
+  reference schema); noul slots are fixed `false`/`true` with overridable
+  rubric descriptions;
+- the question gets first claim on the 4096-token window (up to 75%), the state
+  is truncated from the right into what remains, and an over-long question is
+  truncated from the front, keeping the options and `<answer>`;
+- per-kind calibration from the checkpoint (`noul` 0.911 / `choice` 0.734 /
+  `score` 1.328); `score` confidence is ordinal (spread-based, with the
+  training smoothing floor), not max-probability.
+
+Lower-level helpers are exported for custom runtimes:
+`renderStrandsQuestion`, `renderStrandsState`, `renderStrandsContent`,
+`buildStrandsBatch`, `collateStrandsItems`, `strandsOptionTokenIndices`,
+`strandsAnswersFromLogits`, `strandsChoiceConfidence`, `strandsScoreConfidence`.
+
+## Bekko family (Ettin cross-encoder)
+
+`createBekkoDecider(options)` runs
+[Bekko System One v0](https://github.com/hotchpotch/bekko-system-one), a
+cross-encoder that scores each (query, candidate) pair: the query renders as
+`Instruction: {instruction}\nState: {state}` and every option becomes a
+`Candidate: {id}: {description}` document. One ONNX graph
+(`prefix_ids, prefix_mask, doc_ids, doc_mask, owners → logits [N, tasks]`),
+one forward per question, with candidates batched by the reference
+attention budget:
+
+```js
+import { createBekkoDecider } from "jev-web";
+
+const decider = await createBekkoDecider({
+  // defaults to hotchpotch/bekko-system-one-v0-17m @ pinned revision,
+  // onnx_browser/ (29 MB)
+  onProgress: (p) => console.log(p.phase, p.loaded, p.total),
+});
+const { answers } = await decider.decide(stateText, questions);
+```
+
+Protocol implemented here (mirrors the reference browser runtime,
+`browser/src/core.js` + `decision.js`, MIT):
+
+- query `[cls] Instruction: …\nState: … [sep]`; instruction and state split the
+  4096-token budget 50/50 with spillover; candidates truncate to 2048 tokens;
+- choice questions accept `criteria` as `{label: description}`; noul slots are
+  fixed `true`/`false` with authored meanings (overridable via criteria);
+- 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).
+
+Lower-level helpers are exported for custom runtimes:
+`renderBekkoContent`, `renderBekkoRequest`, `tokenizeBekkoRequest`,
+`collateBekkoDocs`, `bekkoSoftmax`, `bekkoAnswerFromLogits`.
+
 ## Worker / thread
 
 `jev-web` does not bundle a worker, so hosts can create one the way their
@@ -174,18 +382,22 @@ import { createDecider } from "jev-web";
 
 - `createDecider(options)` → open-jev family: `{ info, decide, decideMany, dispose }`
 - `createLayaDecider(options)` → Laya family: `{ info, decide, dispose }` (same `decide` contract)
+- `createStrandsDecider(options)` → Strands Decider 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.
+## Demos
+
+- **Live demo** — <https://warsang.github.io/jev-web/> (built from `demo/`, deployed on every push)
+- **Local playground** — `npm run dev` → <http://localhost:5188>. Same ideas, plus
+  COOP/COEP headers that unlock `SharedArrayBuffer` for the threaded
+  onnxruntime-web build (GitHub Pages cannot set those headers, so the deployed
+  demo runs single-threaded).
+- **Verify a change visually** — `node tools/shot.mjs jobs.json` drives headless
+  Chrome over CDP, waits on a real DOM condition, and reports the page's own
+  console errors. The GIF in this README was built with it. It exists because a
+  screenshot alone cannot tell you a promise is silently rejecting.
 
 ## Limits
 

package/package.json

@@ -1,18 +1,29 @@
 {
   "name": "jev-web",
-  "version": "0.3.2",
-  "description": "Run open-jev- and Laya-shaped typed-decision models in the browser: one state plus typed questions in, calibrated probabilities out.",
+  "version": "0.4.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/warsang/jev-web.git"
+  },
+  "homepage": "https://warsang.github.io/jev-web/",
+  "bugs": {
+    "url": "https://github.com/warsang/jev-web/issues"
+  },
   "exports": {
     ".": "./src/index.mjs"
   },
   "files": [
     "src/",
+    "docs/",
     "README.md"
   ],
   "keywords": [
     "open-jev",
+    "laya",
+    "strands-decider",
     "typed-decisions",
     "onnx",
     "transformers.js",
@@ -23,6 +34,8 @@
   "scripts": {
     "dev": "vite",
     "build:dev": "vite build",
+    "demo": "vite --config vite.demo.config.js",
+    "build:demo": "vite build --config vite.demo.config.js",
     "test": "node --test test/*.test.mjs"
   },
   "peerDependencies": {