Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
feat(ts): port decideBatch and expose answerConfidence
zhanganga2ca7df02e05
diff --git a/laya-ts/README.md b/laya-ts/README.mdindex 713f7e56..c2bec48e 100644--- a/laya-ts/README.md+++ b/laya-ts/README.md@@ -93,8 +93,14 @@ const values = await agent.decide(ticketText, {`router.decide(...)` works the same way (routing options are forwarded to `predict`), and thefree `decide(runner, state, schema, opts)` accepts anything with a `predict` method. Pass-`{ returnDetails: true }` for per-field confidence and probabilities, or `{ questions }`-instead of a schema to get raw answers. Zod/TypeBox users can pass `z.toJSONSchema(Model)` —+`{ returnDetails: true }` for per-field `confidence`, `answerConfidence` (calibrated `max(p)`),+and probabilities, or `{ questions }` instead of a schema to get raw answers.++For high throughput over multiple inputs, `agent.decideBatch(states, schema)` (and `router.decideBatch`,+or the free `decideBatch(runner, states, schema, opts)`) plans the schema once and evaluates every state+through shared forward passes on `predictBatch` (mirroring Python's `laya.decide_batch`).++Zod/TypeBox users can pass `z.toJSONSchema(Model)` —any object with a `toJSONSchema()` method is accepted. `planFromJsonSchema`,`questionsFromJsonSchema` and `answersToJson` expose the planning and projection steps.diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.tsindex cd368278..b28e3f49 100644--- a/laya-ts/src/agent.ts+++ b/laya-ts/src/agent.ts@@ -21,7 +21,7 @@ import {import type { BinningMap, MinConfidence, OptionStats, SequenceStats } from "./common.js";import type { Batch, SessionProvider } from "./providers.js";import { encodeWithData, parseTokenizerJson, type TokenizerLike } from "./tokenizer.js";-import { decide, type DecideOptions, type DecisionResult } from "./structured.js";+import { decide, decideBatch, type DecideOptions, type DecideBatchOptions, type DecisionResult } from "./structured.js";import {HookRegistry,PredictContext,@@ -837,6 +837,31 @@ export class Agent extends HookRegistry {return decide(this, state, schema, opts);}+ /**+ * Answer many states against one schema in one batched call, in input order.+ *+ * The throughput form of `decide`: the schema is planned once and evaluated+ * over every state through `predictBatch` (shared forward passes, results in input order).+ * See `structured.ts`.+ */+ async decideBatch(+ states: unknown[],+ schema: unknown,+ opts: DecideBatchOptions & PredictOptions & { returnDetails: true },+ ): Promise<DecisionResult[]>;+ async decideBatch(+ states: unknown[],+ schema?: unknown,+ opts?: DecideBatchOptions & PredictOptions,+ ): Promise<Record<string, unknown>[]>;+ async decideBatch(+ states: unknown[],+ schema?: unknown,+ opts: DecideBatchOptions & PredictOptions = {},+ ): Promise<Record<string, unknown>[] | DecisionResult[]> {+ return decideBatch(this, states, schema, opts);+ }+static async load(modelDirOrRepo: string,opts?: {diff --git a/laya-ts/src/index.ts b/laya-ts/src/index.tsindex 1f62f73b..163937bd 100644--- a/laya-ts/src/index.ts+++ b/laya-ts/src/index.ts@@ -40,6 +40,7 @@ export type { Hook, HookEvent, HookArg, PredictHook, PredictHookArg } from "./hoexport { triageQuestions, emailQuestions, guardQuestions, moderationQuestions, routerQuestions } from "./presets.js";export {decide,+ decideBatch,planFromJsonSchema,questionsFromJsonSchema,answersToJson,@@ -48,7 +49,7 @@ export {MAX_OPTIONS,MAX_SCORE_LEVELS,} from "./structured.js";-export type { DecisionResult, DecideOptions, DecideRunner, PlannedField } from "./structured.js";+export type { DecisionResult, DecideOptions, DecideBatchOptions, DecideRunner, PlannedField } from "./structured.js";export {renderOptions,serializeState,diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.tsindex a5cd0e6a..6e42438d 100644--- a/laya-ts/src/router.ts+++ b/laya-ts/src/router.ts@@ -1,7 +1,7 @@import { analyse, type AnalyseResult } from "./lang.js";import type { PredictOptions, QuestionDef, SystemOneResult } from "./agent.js";import { checkMinConfidence, flagLowConfidence } from "./common.js";-import { decide, type DecideOptions, type DecisionResult } from "./structured.js";+import { decide, decideBatch, type DecideOptions, type DecideBatchOptions, type DecisionResult } from "./structured.js";import {HookRegistry,PredictContext,@@ -683,6 +683,29 @@ export class Router extends HookRegistry {return decide(this, state, schema, opts);}+ /**+ * Answer many states against one schema in one batched call (Python `Router.decide_batch` parity).+ * Requests route per state and evaluate through `predictBatch` (grouped forward passes, results+ * in input order). See `structured.ts`.+ */+ async decideBatch(+ states: unknown[],+ schema: unknown,+ opts: DecideBatchOptions & RouteOptions & PredictOptions & { returnDetails: true },+ ): Promise<DecisionResult[]>;+ async decideBatch(+ states: unknown[],+ schema?: unknown,+ opts?: DecideBatchOptions & RouteOptions & PredictOptions,+ ): Promise<Record<string, unknown>[]>;+ async decideBatch(+ states: unknown[],+ schema?: unknown,+ opts: DecideBatchOptions & RouteOptions & PredictOptions = {},+ ): Promise<Record<string, unknown>[] | DecisionResult[]> {+ return decideBatch(this, states, schema, opts);+ }+async systemOne(state: unknown,questions: Record<string, QuestionDef>,diff --git a/laya-ts/src/structured.ts b/laya-ts/src/structured.tsindex bc5ef1b7..6b027ba8 100644--- a/laya-ts/src/structured.ts+++ b/laya-ts/src/structured.ts@@ -40,6 +40,12 @@ export interface DecisionResult {values: Record<string, unknown>;/** Per-field confidence. */confidence: Record<string, number>;+ /**+ * Per-field answerConfidence (max(p)), matching Python DecisionResult.answer_confidence.+ * The quantity minConfidence gates on and calibration figures evaluate.+ * Maps to null if no valid answer_confidence was reported.+ */+ answerConfidence: Record<string, number | null>;/** Per-field probabilities (noul fields report { false, true }). */probabilities: Record<string, Record<string, unknown>>;/** Laya's raw answer per field. */@@ -66,6 +72,12 @@ export interface DecideRunner {questions: Record<string, QuestionDef>,opts?: Record<string, unknown>,): Promise<{ answers?: Record<string, Record<string, any> | undefined>; usage?: unknown; routing?: unknown }>;+ predictBatch?(+ statesOrRequests: unknown[] | any[],+ questionsOrBatchSize?: unknown,+ opts?: Record<string, unknown>,+ ): Promise<any[]>;+ routeBatch?(requests: any[]): any[];}export interface DecideOptions {@@ -81,6 +93,19 @@ export interface DecideOptions {[k: string]: unknown;}+export interface DecideBatchOptions {+ /** Explicit questions instead of a schema (answers are returned unprojected). */+ questions?: Record<string, QuestionDef>;+ /** Return a DecisionResult per state with confidence, probabilities and raw answers. */+ returnDetails?: boolean;+ /** Minimum confidence threshold in [0.0, 1.0]. Low confidence answers project to null. */+ minConfidence?: number | null;+ /** Batch size forwarded to runner.predictBatch. */+ batchSize?: number | null;+ /** Anything else is forwarded to runner.predictBatch (hooks, model, ...). */+ [k: string]: unknown;+}+const r4 = (v: number): number => Math.round(v * 1e4) / 1e4;function pyType(v: unknown): string {@@ -284,16 +309,26 @@ export function answersToJson(}+function answerConfidenceValue(answer: Record<string, any>): number | null {+ const conf = answer.answer_confidence;+ if (typeof conf === "number" && typeof conf !== "boolean" && Number.isFinite(conf)) {+ return conf;+ }+ return null;+}+function detailsOf(values: Record<string, unknown>,answers: Record<string, Record<string, any> | undefined>,result: { usage?: unknown; routing?: unknown },): DecisionResult {const confidence: Record<string, number> = {};+ const answerConfidence: Record<string, number | null> = {};const probabilities: Record<string, Record<string, unknown>> = {};for (const [name, answer] of Object.entries(answers)) {if (answer == null) continue;confidence[name] = Number(answer.confidence ?? 0.0);+ answerConfidence[name] = answerConfidenceValue(answer);if (answer.type === "noul") {const p = Number(answer.noul ?? 0.0);probabilities[name] = { false: r4(1.0 - p), true: r4(p) };@@ -301,7 +336,15 @@ function detailsOf(probabilities[name] = { ...(answer.probabilities ?? {}) };}}- return { values, confidence, probabilities, answers: { ...answers }, usage: result.usage, routing: result.routing };+ return {+ values,+ confidence,+ answerConfidence,+ probabilities,+ answers: { ...answers },+ usage: result.usage,+ routing: result.routing,+ };}/**@@ -354,3 +397,84 @@ export async function decide(return values;}+/**+ * Answer many states against one schema in one batched call, in input order.+ *+ * The throughput form of `decide`: the schema is planned once and its questions+ * are evaluated over every state through `runner.predictBatch` (shared forward+ * passes, results in input order), then each state's answers are projected exactly+ * as `decide` does. Pass exactly one of `schema` or `opts.questions`.+ */+export async function decideBatch(+ runner: DecideRunner,+ states: unknown[],+ schema: unknown,+ opts: DecideBatchOptions & { returnDetails: true },+): Promise<DecisionResult[]>;+export async function decideBatch(+ runner: DecideRunner,+ states: unknown[],+ schema?: unknown,+ opts?: DecideBatchOptions,+): Promise<Record<string, unknown>[]>;+export async function decideBatch(+ runner: DecideRunner,+ states: unknown[],+ schema?: unknown,+ opts: DecideBatchOptions = {},+): Promise<Record<string, unknown>[] | DecisionResult[]> {+ const {+ questions,+ returnDetails = false,+ minConfidence,+ ...predictOpts+ } = opts;+ if ((schema == null) === (questions == null)) {+ throw new Error("pass exactly one of schema= or questions=");+ }+ if (typeof states === "string" || !Array.isArray(states)) {+ throw new TypeError(`states must be an array of states, not ${pyType(states)}`);+ }++ const mc = minConfidence !== undefined && minConfidence !== null ? checkMinConfidence(minConfidence) : null;++ let fields: PlannedField[] | null = null;+ let qs = questions;+ if (schema != null) {+ fields = planFromJsonSchema(schemaOf(schema));+ qs = Object.fromEntries(fields.map((f) => [f.name, f.question]));+ }++ const r = runner as any;+ const predictBatchFn = typeof r.predictBatch === "function" ? r.predictBatch : null;+ if (!predictBatchFn) {+ const runnerName = r?.constructor?.name ?? typeof runner;+ throw new TypeError(`${runnerName} has no predictBatch; loop decide() over the states instead`);+ }++ const isRouter = typeof r.routeBatch === "function";+ let results: any[];+ if (isRouter) {+ const requests = states.map((s) => ({ state: s, questions: qs, ...predictOpts }));+ const batchSize = (predictOpts.batchSize ?? null) as number | null;+ results = await predictBatchFn.call(runner, requests, batchSize);+ } else {+ results = await predictBatchFn.call(runner, states, qs as Record<string, QuestionDef>, predictOpts);+ }++ if (mc !== null && Array.isArray(results)) {+ flagLowConfidence(results as Record<string, unknown>[], mc);+ }++ const one = (res: any) => {+ const answers = (res && typeof res === "object" ? res.answers : null) || {};+ const values = fields !== null ? project(answers, fields) : { ...answers };+ if (returnDetails) {+ return detailsOf(values, answers, res || {});+ }+ return values;+ };++ return (results || []).map(one);+}+diff --git a/laya-ts/tests/agent.test.ts b/laya-ts/tests/agent.test.tsindex 69a817be..d1e8f8a7 100644--- a/laya-ts/tests/agent.test.ts+++ b/laya-ts/tests/agent.test.ts@@ -85,5 +85,23 @@ describe("agent", () => {});expect(result.answers.q.type).toBe("noul");});++ it("decideBatch projects schema across states", async () => {+ const a = new Agent({ provider: fakeProvider() } as any);+ const schema = {+ type: "object",+ properties: { flag: { type: "boolean" } },+ };+ const res1 = await a.decideBatch(["s1", "s2"], schema);+ expect(res1).toHaveLength(2);+ expect(typeof res1[0].flag).toBe("boolean");+ expect(typeof res1[1].flag).toBe("boolean");++ const res2 = await a.decideBatch(["s1"], schema, { returnDetails: true });+ expect(res2).toHaveLength(1);+ expect(res2[0].values.flag).toBeDefined();+ expect(res2[0].confidence).toBeDefined();+ expect(res2[0].answerConfidence).toBeDefined();+ });});diff --git a/laya-ts/tests/router-batch.test.ts b/laya-ts/tests/router-batch.test.tsindex 8407d0eb..f4a4bd36 100644--- a/laya-ts/tests/router-batch.test.ts+++ b/laya-ts/tests/router-batch.test.ts@@ -529,4 +529,22 @@ describe("Agent.predictBatch", () => {expect(results[0].model).toBe("cached");expect(encodeCalls).toEqual([]);});++ it("router.decideBatch evaluates schema across batch", async () => {+ const { router } = makeRouter();+ const schema = {+ type: "object",+ properties: {+ flag: { type: "boolean" },+ },+ };+ const res1 = await router.decideBatch(["alpha", "beta"], schema);+ expect(res1).toHaveLength(2);++ const res2 = await router.decideBatch(["alpha"], schema, { returnDetails: true });+ expect(res2).toHaveLength(1);+ expect(res2[0].values).toBeDefined();+ expect(res2[0].answerConfidence).toBeDefined();+ expect(res2[0].confidence).toBeDefined();+ });});diff --git a/laya-ts/tests/structured.test.ts b/laya-ts/tests/structured.test.tsindex 00bd03a6..1436f98a 100644--- a/laya-ts/tests/structured.test.ts+++ b/laya-ts/tests/structured.test.ts@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";import {answersToJson,decide,+ decideBatch,planFromJsonSchema,questionsFromJsonSchema,SchemaError,@@ -363,3 +364,169 @@ describe("structured/min_confidence", () => {});});+describe("structured/answerConfidence", () => {+ const fakeRunner = (answers: Record<string, any>) => ({+ async predict(state: unknown, questions: any, opts: any) {+ return { model: "fake", answers: JSON.parse(JSON.stringify(answers)) };+ },+ });++ it("exposes answerConfidence per field on DecisionResult", async () => {+ const calAnswers = {+ department: { type: "choice", choice: "billing", confidence: 0.3, answer_confidence: 0.95 },+ urgency: {+ type: "score",+ score: 2.0,+ confidence: 0.9,+ answer_confidence: 0.4,+ probabilities: { "0": 0.1, "1": 0.5, "2": 0.4 },+ },+ };+ const runner = fakeRunner(calAnswers);+ const det = await decide(runner, "state", SCHEMA, { returnDetails: true });++ expect(det.confidence.department).toBe(0.3);+ expect(det.confidence.urgency).toBe(0.9);+ expect(det.answerConfidence.department).toBe(0.95);+ expect(det.answerConfidence.urgency).toBe(0.4);++ // Entropy conf ranks urgency > department, whereas answerConfidence reverses it+ expect(det.confidence.department).toBeLessThan(det.confidence.urgency);+ expect(det.answerConfidence.department).toBeGreaterThan(det.answerConfidence.urgency!);+ });++ it("maps absent or non-finite answer_confidence to null", async () => {+ const runner = fakeRunner({+ department: { type: "choice", choice: "billing", confidence: 0.8 },+ urgency: { type: "score", score: 1.0, confidence: 0.5, answer_confidence: NaN },+ needs_human: { type: "noul", noul: 0.9, confidence: 0.9, answer_confidence: true as any },+ });+ const det = await decide(runner, "state", SCHEMA, { returnDetails: true });+ expect(det.answerConfidence.department).toBeNull();+ expect(det.answerConfidence.urgency).toBeNull();+ expect(det.answerConfidence.needs_human).toBeNull();+ });+});++describe("structured/decideBatch", () => {+ const fakeBatchRunner = (answersPerState: Record<string, any>[]) => ({+ calls: [] as any[],+ async predict(state: unknown, questions: any, opts: any) {+ return { model: "fake", answers: answersPerState[0] };+ },+ async predictBatch(states: unknown[], questions: any, opts: any) {+ this.calls.push({ states, questions, opts });+ return states.map((_s, i) => ({+ model: "fake",+ answers: JSON.parse(JSON.stringify(answersPerState[i % answersPerState.length])),+ }));+ },+ });++ it("evaluates a batch of states against a schema in input order", async () => {+ const a1 = { ...ANSWERS, department: { type: "choice", choice: "sales", confidence: 0.9 } };+ const a2 = { ...ANSWERS, department: { type: "choice", choice: "billing", confidence: 0.9 } };+ const runner = fakeBatchRunner([a1, a2]);++ const results = await decideBatch(runner, ["state 1", "state 2"], SCHEMA);+ expect(results).toHaveLength(2);+ expect(results[0].department).toBe("sales");+ expect(results[1].department).toBe("billing");+ expect(runner.calls).toHaveLength(1);+ expect(runner.calls[0].states).toEqual(["state 1", "state 2"]);+ });++ it("supports returnDetails: true returning DecisionResult array", async () => {+ const calAnswer = {+ department: { type: "choice", choice: "billing", confidence: 0.3, answer_confidence: 0.95 },+ urgency: { type: "score", score: 2.0, confidence: 0.8, answer_confidence: 0.85, probabilities: { "2": 0.85 } },+ };+ const runner = fakeBatchRunner([calAnswer]);+ const results = await decideBatch(runner, ["s1", "s2"], SCHEMA, { returnDetails: true });+ expect(results).toHaveLength(2);+ expect(results[0].values.department).toBe("billing");+ expect(results[0].answerConfidence.department).toBe(0.95);+ expect(results[0].confidence.department).toBe(0.3);+ expect(results[1].values.department).toBe("billing");+ expect(results[1].answerConfidence.department).toBe(0.95);+ });++ it("evaluates with explicit questions instead of schema", async () => {+ const qs = questionsFromJsonSchema(SCHEMA);+ const runner = fakeBatchRunner([ANSWERS]);+ const results = await decideBatch(runner, ["s1"], undefined, { questions: qs });+ expect(results).toHaveLength(1);+ expect(results[0].department.choice).toBe("billing");+ });++ it("gates low confidence answers when minConfidence is provided", async () => {+ const answersWithLowConf = {+ department: { type: "choice", choice: "billing", confidence: 0.9, answer_confidence: 0.95 },+ urgency: { type: "score", score: 2.0, confidence: 0.4, answer_confidence: 0.4 },+ };+ const runner = fakeBatchRunner([answersWithLowConf]);+ const results = await decideBatch(runner, ["s1"], SCHEMA, { minConfidence: 0.85, returnDetails: true });+ expect(results[0].values.department).toBe("billing");+ expect(results[0].values.urgency).toBeNull();+ expect((results[0].answers.urgency as any).low_confidence).toBe(true);+ });++ it("handles empty states array cleanly", async () => {+ const runner = fakeBatchRunner([ANSWERS]);+ const results = await decideBatch(runner, [], SCHEMA);+ expect(results).toEqual([]);+ });++ it("throws TypeError if states is not an array", async () => {+ const runner = fakeBatchRunner([ANSWERS]);+ await expect(decideBatch(runner, "not-an-array" as any, SCHEMA)).rejects.toThrow(TypeError);+ await expect(decideBatch(runner, 123 as any, SCHEMA)).rejects.toThrow(TypeError);+ await expect(decideBatch(runner, null as any, SCHEMA)).rejects.toThrow(TypeError);+ });++ it("throws Error if neither or both schema and questions are passed", async () => {+ const runner = fakeBatchRunner([ANSWERS]);+ await expect(decideBatch(runner, ["s1"])).rejects.toThrow("pass exactly one of schema= or questions=");+ await expect(decideBatch(runner, ["s1"], SCHEMA, { questions: {} as any })).rejects.toThrow(+ "pass exactly one of schema= or questions=",+ );+ });++ it("throws TypeError if runner has no predictBatch", async () => {+ const plainRunner = {+ async predict() {+ return { answers: {} };+ },+ };+ await expect(decideBatch(plainRunner as any, ["s1"], SCHEMA)).rejects.toThrow(/has no predictBatch/);+ });++ it("routes batch using routeBatch Router convention", async () => {+ const routerRunner = {+ calls: [] as any[],+ routeBatch(reqs: any[]) {+ return reqs.map(() => ({ model: "router-m" }));+ },+ async predictBatch(requests: any[], batchSize?: number | null) {+ this.calls.push({ requests, batchSize });+ return requests.map((r: any) => ({+ model: "router-m",+ answers: JSON.parse(JSON.stringify(ANSWERS)),+ }));+ },+ async predict() {+ return { answers: ANSWERS };+ },+ };++ const results = await decideBatch(routerRunner as any, ["req1", "req2"], SCHEMA, { batchSize: 4 });+ expect(results).toHaveLength(2);+ expect(routerRunner.calls).toHaveLength(1);+ expect(routerRunner.calls[0].batchSize).toBe(4);+ expect(routerRunner.calls[0].requests).toHaveLength(2);+ expect(routerRunner.calls[0].requests[0].state).toBe("req1");+ expect(routerRunner.calls[0].requests[1].state).toBe("req2");+ });+});++