Skip to content

armgit / laya

Public Imported from GitHub
0

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.

feat(ts): port decideBatch and expose answerConfidence

zhanganga2ca7df02e05
diff --git a/laya-ts/README.md b/laya-ts/README.md
index 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 the
free `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.ts
index 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.ts
index 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 "./ho
export { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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");
+ });
+});
+
+