@hikae/jev-algorithms 0.1.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HikaruEgashira
+
+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

@@ -0,0 +1,161 @@
+# jev-algorithms
+
+## Gallery
+
+![sortByPairwise](https://cdn.jsdelivr.net/npm/@hikae/jev-algorithms@0.1.0/docs/animations/sort-by-pairwise.gif)
+![selectTopK](https://cdn.jsdelivr.net/npm/@hikae/jev-algorithms@0.1.0/docs/animations/select-top-k.gif)
+![findFirstTrue](https://cdn.jsdelivr.net/npm/@hikae/jev-algorithms@0.1.0/docs/animations/find-first-true.gif)
+![clusterByRelation](https://cdn.jsdelivr.net/npm/@hikae/jev-algorithms@0.1.0/docs/animations/cluster-by-relation.gif)
+
+## Install
+
+```sh
+npm install @hikae/jev-algorithms
+```
+
+## Quick start
+
+```ts
+import { createTypeSafeClient, sortByPairwise } from "@hikae/jev-algorithms";
+
+const jev = createTypeSafeClient({ apiKey: process.env.TYPESAFE_API_KEY! });
+
+const inbox = [
+  { id: "1", from: "ceo@acme.com", subject: "Contract", unread: true, body: "Please sign by Friday." },
+  { id: "2", from: "news@acme.com", subject: "Weekly digest", unread: false, body: "This week in..." },
+];
+
+const ordered = await sortByPairwise(jev, inbox, {
+  task: "for replying first",
+  stateOf: (mail) => ({
+    from: mail.from,
+    subject: mail.subject,
+    unread: mail.unread,
+    preview: mail.body.slice(0, 300),
+  }),
+});
+// [Contract mail, Weekly digest]
+```
+
+## The client contract
+
+```ts
+interface JevClient {
+  evaluate(input: { state: JevState; questions: JevQuestions }): Promise<JevAnswers>;
+}
+```
+
+| Adapter | Factory | Notes |
+| --- | --- | --- |
+| TypeSafe API | `createTypeSafeClient({ apiKey, model?, baseUrl?, fetch? })` | Runtime-agnostic default. Keep the key on the server. |
+| Workers AI | `createWorkersAiClient(binding, model?)` | Pass `env.AI`. Structural, no Cloudflare types required. |
+| In memory | `createMemoryClient(responder)` | Test double; records every `calls` evaluation. |
+
+Question builders (`noul`, `choice`, `score`) and answer readers
+(`readNoul`, `readChoice`, `readScore`) are exported for building your own
+algorithms on the same contract.
+
+## Algorithms
+
+Every algorithm states its request cost in terms of `n` items. A request
+carries many questions, so "one request" is rarely one comparison.
+
+### Sorting and selection
+
+| Function | What it does | Requests |
+| --- | --- | --- |
+| `sortByPairwise(client, items, options)` | Total order from pairwise "which ranks higher?" answers | `O(log n)` |
+| `sortByPairwiseWith(items, compare)` | Same, with an injected comparator (no client) | `O(log n)` |
+| `selectTopK(client, items, k, options)` | Top-k, ordered, via quickselect | `O(log n)` |
+| `selectTopKWith(items, k, compare)` | Same, with an injected comparator | `O(log n)` |
+| `createPairComparator(client, items, options)` | Build the comparator to plug Jev into any sort you own | — |
+
+The sort is randomized quicksort whose recursion runs level by level. Nodes on
+a level are disjoint, so all their pivot comparisons fit in one request — the
+whole order costs `~log n` round trips instead of `n log n`. `selectTopK` skips
+the side that cannot contain the k-th item.
+
+### Threshold search
+
+```ts
+const cutoff = await findFirstTrue(jev, emailsByRecency, {
+  stateOf: (mail) => ({ ageDays: mail.ageDays }),
+  instruction: "Is `candidate` older than 30 days?",
+});
+```
+
+`findFirstTrue` binary-searches a monotone predicate in `O(log n)` calls.
+
+### Ranking from noisy comparisons
+
+Pairwise answers can cycle (A > B > C > A). `elo` and `bradleyTerry` turn a
+list of `Comparison`s into one score per id; `rankByElo` and
+`rankByBradleyTerry` order them. `winner` is `"first" | "second" | "draw"`,
+named by position so a player called `"a"` or `"b"` is never ambiguous.
+
+### Clustering
+
+```ts
+const groups = await clusterByRelation(jev, tickets, {
+  relation: "duplicate support ticket",
+  stateOf: (t) => ({ subject: t.subject, body: t.body.slice(0, 300) }),
+});
+```
+
+Union-find over pairwise equivalence. Every unordered pair is compared once;
+`threshold` controls how confident Jev must be to merge, and `maxComparisons`
+caps sampling for large inputs.
+
+### Classification and scoring
+
+- `classifyChoice(client, state, { instruction, labels, abstainBelow })` —
+  Choice with an abstain band, so uncertain cases can be escalated instead of
+  guessed.
+- `booleanDecision(client, state, { instruction, threshold })` — Noul plus a
+  thresholded verdict.
+- `rubricScore(client, state, { instruction, levels })` — Score normalized to
+  `0..1`, with the nearest level label.
+
+### Matching
+
+`stableMatching(proposers, receivers, proposerPrefs, receiverPrefs)` is a pure
+Gale-Shapley implementation. `buildPreferences(client, choosers, candidates, options)`
+builds each side's preference order with pairwise comparisons first.
+
+## Design notes
+
+- **Batch by default.** Every algorithm packs many questions into one
+  `evaluate` call and references items through a chunk-local index so a shared
+  item travels once.
+- **Fail loud, not wrong.** If Jev omits an answer, algorithms throw. They
+  never persist a fabricated order. The one exception is up to the caller:
+  `classifyChoice` can abstain by design.
+- **Persistence is yours.** Algorithms return orders and scores; storing them
+  (for example, an integer priority column) is a schema decision, not a library
+  one.
+
+## Testing and mutation testing
+
+```sh
+npm test        # build + node:test
+npm run typecheck
+npm run mutation # build + Stryker
+```
+
+Tests are judged by mutation coverage, not line coverage: a test only earns its
+place if it kills a mutant. Stryker runs with the `command` test runner against
+the built `dist` and a break threshold of 80; the current score is ~85%.
+
+Two policies keep the signal honest and the suite lean:
+
+- `StringLiteral` mutants are excluded. Prompts and error wording are content,
+  not logic; asserting exact prompt text would make the suite brittle without
+  catching real bugs.
+- Remaining survivors are equivalent mutants — union-by-size size bookkeeping,
+  path compression, and randomized pivot selection that produces the same order
+  either way. They are documented rather than chased with tests that assert
+  internals.
+
+## License
+
+MIT

package/dist/adapters/memory.d.ts

@@ -0,0 +1,10 @@
+import type { JevAnswers, JevClient, JevEvaluation } from "../client.js";
+/** Produce the answers for one evaluation. May be async. */
+export type MemoryResponder = (evaluation: JevEvaluation) => JevAnswers | Promise<JevAnswers>;
+export interface MemoryClient extends JevClient {
+    /** Every evaluation this client saw, in order. Handy in assertions. */
+    readonly calls: JevEvaluation[];
+}
+/** In-memory Jev client driven by a responder, for tests and deterministic oracles. */
+export declare function createMemoryClient(responder: MemoryResponder): MemoryClient;
+//# sourceMappingURL=memory.d.ts.map

package/dist/adapters/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEzE,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,CAC7B,UAAU,EAAE,aAAa,KACrB,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC9C,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC;CAChC;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,eAAe,GAAG,YAAY,CAS3E"}

package/dist/adapters/memory.js

@@ -0,0 +1,12 @@
+/** In-memory Jev client driven by a responder, for tests and deterministic oracles. */
+export function createMemoryClient(responder) {
+    const calls = [];
+    return {
+        calls,
+        async evaluate(input) {
+            calls.push(input);
+            return responder(input);
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/adapters/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAYA,uFAAuF;AACvF,MAAM,UAAU,kBAAkB,CAAC,SAA0B;IAC5D,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,OAAO;QACN,KAAK;QACL,KAAK,CAAC,QAAQ,CAAC,KAAoB;YAClC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/adapters/typesafe.d.ts

@@ -0,0 +1,15 @@
+import type { JevClient } from "../client.js";
+export interface TypeSafeClientOptions {
+    /** TypeSafe API key. Keep it on the server; never ship it to a browser. */
+    apiKey: string;
+    /** Model id. Defaults to `jev-latest`. */
+    model?: string;
+    /** Endpoint override, e.g. for a gateway or a test double. */
+    baseUrl?: string;
+    /** Fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/** Jev over TypeSafe's HTTP API. */
+export declare function createTypeSafeClient(options: TypeSafeClientOptions): JevClient;
+//# sourceMappingURL=typesafe.d.ts.map

package/dist/adapters/typesafe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesafe.d.ts","sourceRoot":"","sources":["../../src/adapters/typesafe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,SAAS,EAAiB,MAAM,cAAc,CAAC;AAMzE,MAAM,WAAW,qBAAqB;IACrC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAOD,oCAAoC;AACpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,CA6B9E"}

package/dist/adapters/typesafe.js

@@ -0,0 +1,27 @@
+const DEFAULT_BASE_URL = "https://api.typesafe.ai/v1/systemone";
+const DEFAULT_MODEL = "jev-latest";
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** Jev over TypeSafe's HTTP API. */
+export function createTypeSafeClient(options) {
+    const { apiKey, model = DEFAULT_MODEL, baseUrl = DEFAULT_BASE_URL, timeoutMs = DEFAULT_TIMEOUT_MS, } = options;
+    const doFetch = options.fetch ?? fetch;
+    return {
+        async evaluate({ state, questions }) {
+            const response = await doFetch(baseUrl, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${apiKey}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({ model, state, questions }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!response.ok) {
+                throw new Error(`TypeSafe request failed: ${response.status}`);
+            }
+            const body = (await response.json());
+            return body.answers ?? {};
+        },
+    };
+}
+//# sourceMappingURL=typesafe.js.map

package/dist/adapters/typesafe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesafe.js","sourceRoot":"","sources":["../../src/adapters/typesafe.ts"],"names":[],"mappings":"AAEA,MAAM,gBAAgB,GAAG,sCAAsC,CAAC;AAChE,MAAM,aAAa,GAAG,YAAY,CAAC;AACnC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAmBlC,oCAAoC;AACpC,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IAClE,MAAM,EACL,MAAM,EACN,KAAK,GAAG,aAAa,EACrB,OAAO,GAAG,gBAAgB,EAC1B,SAAS,GAAG,kBAAkB,GAC9B,GAAG,OAAO,CAAC;IACZ,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IAEvC,OAAO;QACN,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,EAAiB;YACjD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE;gBACvC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACR,aAAa,EAAE,UAAU,MAAM,EAAE;oBACjC,cAAc,EAAE,kBAAkB;iBAClC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;gBACjD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACtC,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YAChE,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAsB,CAAC;YAC1D,OAAO,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;QAC3B,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/adapters/workers-ai.d.ts

@@ -0,0 +1,8 @@
+import type { JevClient } from "../client.js";
+/** The shape of a Workers AI binding (`env.AI`). Structural, so no CF types. */
+export interface AiBinding {
+    run(model: string, input: unknown): Promise<unknown>;
+}
+/** Jev over a Cloudflare Workers AI binding (`env.AI`). */
+export declare function createWorkersAiClient(binding: AiBinding, model?: string): JevClient;
+//# sourceMappingURL=workers-ai.d.ts.map

package/dist/adapters/workers-ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers-ai.d.ts","sourceRoot":"","sources":["../../src/adapters/workers-ai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,SAAS,EAAiB,MAAM,cAAc,CAAC;AAIzE,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACzB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED,2DAA2D;AAC3D,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,SAAS,EAClB,KAAK,GAAE,MAAsB,GAC3B,SAAS,CASX"}

package/dist/adapters/workers-ai.js

@@ -0,0 +1,11 @@
+const DEFAULT_MODEL = "typesafe/jev";
+/** Jev over a Cloudflare Workers AI binding (`env.AI`). */
+export function createWorkersAiClient(binding, model = DEFAULT_MODEL) {
+    return {
+        async evaluate({ state, questions }) {
+            const raw = (await binding.run(model, { state, questions }));
+            return raw?.answers ?? {};
+        },
+    };
+}
+//# sourceMappingURL=workers-ai.js.map

package/dist/adapters/workers-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers-ai.js","sourceRoot":"","sources":["../../src/adapters/workers-ai.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAAG,cAAc,CAAC;AAOrC,2DAA2D;AAC3D,MAAM,UAAU,qBAAqB,CACpC,OAAkB,EAClB,QAAgB,aAAa;IAE7B,OAAO;QACN,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,EAAiB;YACjD,MAAM,GAAG,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAE1D,CAAC;YACF,OAAO,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC;QAC3B,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/algorithms/aggregate.d.ts

@@ -0,0 +1,39 @@
+/** Aggregate noisy pairwise outcomes (which may cycle) into a global ranking. */
+export interface Comparison {
+    a: string;
+    b: string;
+    /**
+     * Which side won: "first" is `a`, "second" is `b`. Named by position, not
+     * by id, so a player literally called "a" or "b" cannot be confused.
+     * "draw" splits the point.
+     */
+    winner: "first" | "second" | "draw";
+}
+export interface EloOptions {
+    /** K-factor: how far one result moves a rating. Default 32. */
+    k?: number;
+    /** Starting rating for unseen players. Default 1000. */
+    initial?: number;
+    /** Passes over the comparison list. Default 1. */
+    rounds?: number;
+}
+/** Elo ratings after replaying every comparison in order. */
+export declare function elo(comparisons: readonly Comparison[], options?: EloOptions): Record<string, number>;
+export interface BradleyTerryOptions {
+    /** MM iterations. Default 100. */
+    iterations?: number;
+    /** Stop when the largest change falls below this. Default 1e-9. */
+    tolerance?: number;
+}
+/**
+ * Bradley-Terry strengths via the MM (minorize-maximize) algorithm.
+ *
+ * Draws count as half a win for each side. Players with no wins keep strength
+ * 0, which is correct: BT is defined up to scale, only the order matters.
+ */
+export declare function bradleyTerry(comparisons: readonly Comparison[], options?: BradleyTerryOptions): Record<string, number>;
+/** Ids ordered strongest-first by Bradley-Terry, ties broken by id. */
+export declare function rankByBradleyTerry(comparisons: readonly Comparison[]): string[];
+/** Ids ordered strongest-first by Elo, ties broken by id. */
+export declare function rankByElo(comparisons: readonly Comparison[]): string[];
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/algorithms/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../src/algorithms/aggregate.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,MAAM,WAAW,UAAU;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV;;;;OAIG;IACH,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IAC1B,+DAA+D;IAC/D,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6DAA6D;AAC7D,wBAAgB,GAAG,CAClB,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,OAAO,GAAE,UAAe,GACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BxB;AAED,MAAM,WAAW,mBAAmB;IACnC,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,OAAO,GAAE,mBAAwB,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyDxB;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,EAAE,CAK/E;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,EAAE,CAKtE"}

package/dist/algorithms/aggregate.js

@@ -0,0 +1,100 @@
+/** Aggregate noisy pairwise outcomes (which may cycle) into a global ranking. */
+/** Elo ratings after replaying every comparison in order. */
+export function elo(comparisons, options = {}) {
+    const { k = 32, initial = 1000, rounds = 1 } = options;
+    const ratings = new Map();
+    const rating = (id) => {
+        let value = ratings.get(id);
+        if (value === undefined) {
+            value = initial;
+            ratings.set(id, value);
+        }
+        return value;
+    };
+    for (let round = 0; round < rounds; round++) {
+        for (const { a, b, winner } of comparisons) {
+            const ra = rating(a);
+            const rb = rating(b);
+            const expectedA = 1 / (1 + 10 ** ((rb - ra) / 400));
+            const scoreA = winner === "first" ? 1 : winner === "second" ? 0 : 0.5;
+            const delta = k * (scoreA - expectedA);
+            ratings.set(a, ra + delta);
+            ratings.set(b, rb - delta);
+        }
+    }
+    return Object.fromEntries(ratings);
+}
+/**
+ * Bradley-Terry strengths via the MM (minorize-maximize) algorithm.
+ *
+ * Draws count as half a win for each side. Players with no wins keep strength
+ * 0, which is correct: BT is defined up to scale, only the order matters.
+ */
+export function bradleyTerry(comparisons, options = {}) {
+    const { iterations = 100, tolerance = 1e-9 } = options;
+    const players = new Set();
+    const wins = new Map();
+    // Pairwise game counts, keyed "i\u0000j" with i < j.
+    const games = new Map();
+    const bump = (map, key, by) => {
+        map.set(key, (map.get(key) ?? 0) + by);
+    };
+    const pairKey = (i, j) => (i < j ? `${i}\u0000${j}` : `${j}\u0000${i}`);
+    for (const { a, b, winner } of comparisons) {
+        players.add(a);
+        players.add(b);
+        bump(games, pairKey(a, b), 1);
+        if (winner === "first")
+            bump(wins, a, 1);
+        else if (winner === "second")
+            bump(wins, b, 1);
+        else {
+            bump(wins, a, 0.5);
+            bump(wins, b, 0.5);
+        }
+    }
+    const ids = [...players];
+    const strength = new Map();
+    for (const id of ids)
+        strength.set(id, Math.max(wins.get(id) ?? 0, 1e-6));
+    // Denominator term for each player: sum_j n_ij / (p_i + p_j).
+    for (let iteration = 0; iteration < iterations; iteration++) {
+        const next = new Map();
+        let maxChange = 0;
+        for (const id of ids) {
+            let denominator = 0;
+            for (const other of ids) {
+                if (other === id)
+                    continue;
+                const n = games.get(pairKey(id, other));
+                if (!n)
+                    continue;
+                denominator += n / (strength.get(id) + strength.get(other));
+            }
+            const w = wins.get(id) ?? 0;
+            const value = denominator > 0 && w > 0 ? w / denominator : 1e-6;
+            next.set(id, value);
+            maxChange = Math.max(maxChange, Math.abs(value - strength.get(id)));
+        }
+        // Normalize to keep the scale from drifting.
+        const total = [...next.values()].reduce((sum, v) => sum + v, 0) || 1;
+        for (const [id, value] of next)
+            next.set(id, value / total);
+        for (const [id, value] of next)
+            strength.set(id, value);
+        if (maxChange < tolerance)
+            break;
+    }
+    return Object.fromEntries(strength);
+}
+/** Ids ordered strongest-first by Bradley-Terry, ties broken by id. */
+export function rankByBradleyTerry(comparisons) {
+    const strengths = bradleyTerry(comparisons);
+    return Object.keys(strengths).sort((a, b) => strengths[b] - strengths[a] || a.localeCompare(b));
+}
+/** Ids ordered strongest-first by Elo, ties broken by id. */
+export function rankByElo(comparisons) {
+    const ratings = elo(comparisons);
+    return Object.keys(ratings).sort((a, b) => ratings[b] - ratings[a] || a.localeCompare(b));
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/algorithms/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.js","sourceRoot":"","sources":["../../src/algorithms/aggregate.ts"],"names":[],"mappings":"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"}

package/dist/algorithms/classify.d.ts

@@ -0,0 +1,59 @@
+import { type JevClient, type JevState } from "../client.js";
+export interface ClassifyChoiceOptions {
+    /** Question text, e.g. "Which team should handle this ticket?" */
+    instruction: string;
+    /** Option key -> description. */
+    labels: Record<string, string>;
+    /**
+     * Abstain when Jev's confidence is below this. Default 0, which never
+     * abstains. Raise it to route uncertain cases to a human.
+     */
+    abstainBelow?: number;
+    /** Question id. Default "choice". */
+    id?: string;
+}
+export interface ClassifyChoiceResult {
+    /** Chosen label, or null when abstaining. */
+    label: string | null;
+    confidence: number;
+    probabilities: Record<string, number>;
+}
+/** Pick one label, abstaining below `abstainBelow` confidence. */
+export declare function classifyChoice(client: JevClient, state: JevState, options: ClassifyChoiceOptions): Promise<ClassifyChoiceResult>;
+export interface BooleanDecisionOptions {
+    instruction: string;
+    criteria?: {
+        true?: string;
+        false?: string;
+    };
+    /** Probability at or above which the decision is true. Default 0.5. */
+    threshold?: number;
+    /** Question id. Default "decision". */
+    id?: string;
+}
+/** Ask a yes/no question and return the probability plus a thresholded verdict. */
+export declare function booleanDecision(client: JevClient, state: JevState, options: BooleanDecisionOptions): Promise<{
+    value: boolean;
+    probability: number;
+}>;
+export interface RubricScoreOptions {
+    instruction: string;
+    /** Ordered labels, lowest first. */
+    levels: string[];
+    /** Question id. Default "rubric". */
+    id?: string;
+}
+export interface RubricScoreResult {
+    /** Interpolated position on the scale, 0..levels.length-1. */
+    score: number;
+    /** Nearest level index. */
+    level: number;
+    /** Scale label for `level`. */
+    label: string;
+    /** `score` mapped to 0–1. */
+    normalized: number;
+    confidence: number;
+}
+/** Grade a state against an ordered rubric and return the interpolated score. */
+export declare function rubricScore(client: JevClient, state: JevState, options: RubricScoreOptions): Promise<RubricScoreResult>;
+//# sourceMappingURL=classify.d.ts.map

package/dist/algorithms/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/algorithms/classify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAElF,MAAM,WAAW,qBAAqB;IACrC,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,oBAAoB;IACpC,6CAA6C;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,kEAAkE;AAClE,wBAAsB,cAAc,CACnC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CA2B/B;AAED,MAAM,WAAW,sBAAsB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,mFAAmF;AACnF,wBAAsB,eAAe,CACpC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,sBAAsB,GAC7B,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAalD;AAED,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qCAAqC;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,iBAAiB;IACjC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,iFAAiF;AACjF,wBAAsB,WAAW,CAChC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,kBAAkB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAyB5B"}

package/dist/algorithms/classify.js

@@ -0,0 +1,65 @@
+import { choice, noul, score } from "../client.js";
+/** Pick one label, abstaining below `abstainBelow` confidence. */
+export async function classifyChoice(client, state, options) {
+    const { instruction, labels, abstainBelow = 0, id = "choice" } = options;
+    if (Object.keys(labels).length < 2) {
+        throw new Error("classifyChoice needs at least two labels");
+    }
+    const answers = await client.evaluate({
+        state,
+        questions: { [id]: choice(instruction, labels) },
+    });
+    const answer = answers[id];
+    if (!answer || !("choice" in answer)) {
+        throw new Error("classifyChoice: Jev returned no choice");
+    }
+    const probabilities = answer.probabilities ?? {};
+    const confidence = typeof answer.confidence === "number"
+        ? answer.confidence
+        : (probabilities[answer.choice] ?? 1);
+    return {
+        label: confidence >= abstainBelow ? answer.choice : null,
+        confidence,
+        probabilities,
+    };
+}
+/** Ask a yes/no question and return the probability plus a thresholded verdict. */
+export async function booleanDecision(client, state, options) {
+    const { instruction, criteria, threshold = 0.5, id = "decision" } = options;
+    const answers = await client.evaluate({
+        state,
+        questions: { [id]: noul(instruction, criteria) },
+    });
+    const answer = answers[id];
+    const probability = answer && "noul" in answer ? answer.noul : undefined;
+    if (typeof probability !== "number" || !Number.isFinite(probability)) {
+        throw new Error("booleanDecision: Jev returned no answer");
+    }
+    return { value: probability >= threshold, probability };
+}
+/** Grade a state against an ordered rubric and return the interpolated score. */
+export async function rubricScore(client, state, options) {
+    const { instruction, levels, id = "rubric" } = options;
+    if (levels.length < 2)
+        throw new Error("rubricScore needs at least two levels");
+    const answers = await client.evaluate({
+        state,
+        questions: { [id]: score(instruction, levels) },
+    });
+    const answer = answers[id];
+    const value = answer && "score" in answer ? answer.score : undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error("rubricScore: Jev returned no score");
+    }
+    const max = levels.length - 1;
+    const clamped = Math.max(0, Math.min(max, value));
+    const level = Math.round(clamped);
+    return {
+        score: value,
+        level,
+        label: levels[level],
+        normalized: clamped / max,
+        confidence: answer && "confidence" in answer ? (answer.confidence ?? 0) : 0,
+    };
+}
+//# sourceMappingURL=classify.js.map

package/dist/algorithms/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/algorithms/classify.ts"],"names":[],"mappings":"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"}

package/dist/algorithms/cluster.d.ts

@@ -0,0 +1,30 @@
+import { type JevClient, type JevState } from "../client.js";
+/** Total comparisons allowed before the pair set is sampled. */
+export declare const DEFAULT_MAX_COMPARISONS = 2000;
+/** Pairs per Jev request. */
+export declare const DEFAULT_MAX_CLUSTER_PAIRS_PER_REQUEST = 40;
+/** Answers pairs with the probability that the two items are the same. */
+export type EquivalenceComparator = (pairs: Array<[number, number]>) => Promise<number[]>;
+export interface ClusterOptions<T> {
+    /** Relation name woven into the question, e.g. "duplicate support ticket". */
+    relation: string;
+    stateOf: (item: T) => JevState;
+    /** Probability at or above which two items are joined. Default 0.5. */
+    threshold?: number;
+    /** Pairs per request. Default {@link DEFAULT_MAX_CLUSTER_PAIRS_PER_REQUEST}. */
+    maxPairsPerRequest?: number;
+    /** Cap on total comparisons. Pairs are sampled beyond it. Default 2000. */
+    maxComparisons?: number;
+    /** Injectable RNG used when sampling. Default `Math.random`. */
+    random?: () => number;
+}
+export declare function createRelationComparator<T>(client: JevClient, items: readonly T[], options: Pick<ClusterOptions<T>, "relation" | "stateOf" | "maxPairsPerRequest">): EquivalenceComparator;
+/** Union-find clustering over an injected equivalence comparator. */
+export declare function clusterWith<T>(items: readonly T[], compare: EquivalenceComparator, options?: {
+    threshold?: number;
+    maxComparisons?: number;
+    random?: () => number;
+}): Promise<T[][]>;
+/** Cluster items by a Jev equivalence question, one request per 40 pairs. */
+export declare function clusterByRelation<T>(client: JevClient, items: readonly T[], options: ClusterOptions<T>): Promise<T[][]>;
+//# sourceMappingURL=cluster.d.ts.map

package/dist/algorithms/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../src/algorithms/cluster.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,SAAS,EAAqB,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAGtF,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,6BAA6B;AAC7B,eAAO,MAAM,qCAAqC,KAAK,CAAC;AAExD,0EAA0E;AAC1E,MAAM,MAAM,qBAAqB,GAAG,CACnC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAC1B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAEvB,MAAM,WAAW,cAAc,CAAC,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,QAAQ,CAAC;IAC/B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EACzC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,oBAAoB,CAAC,GAC7E,qBAAqB,CAwDvB;AAED,qEAAqE;AACrE,wBAAsB,WAAW,CAAC,CAAC,EAClC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,EAAE,qBAAqB,EAC9B,OAAO,GAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACjB,GACJ,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CA4BhB;AAED,6EAA6E;AAC7E,wBAAsB,iBAAiB,CAAC,CAAC,EACxC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAOhB"}