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
/**
* Schema-driven decisions: turn a JSON schema into Laya questions.
*
* Port of `laya/structured.py` (#280). Provider-free. The mapping is a documented subset:
* an object of properties, each an enum choice, a boolean, or a bounded integer scale.
* Anything that cannot be answered from a fixed option set (free strings, arrays, nested
* objects, $ref) is rejected with a SchemaError that names the path.
*
* const values = await agent.decide(state, {
* type: "object",
* properties: {
* department: { type: "string", enum: ["billing", "support", "sales"] },
* urgency: { type: "integer", minimum: 0, maximum: 2 },
* needs_human: { type: "boolean" },
* },
* });
*
* Zod/TypeBox users can pass their schema's JSON form (`z.toJSONSchema(Model)`); anything
* with a `toJSONSchema()` method is accepted.
*/
import type { QuestionDef } from "./agent.js";
import type { PredictBatchOptions } from "./router.js";
import { checkMinConfidence, flagLowConfidence } from "./common.js";
import type { MinConfidence } from "./common.js";
export const MAX_PROPERTIES = 32;
export const MAX_OPTIONS = 32;
export const MAX_SCORE_LEVELS = 10;
/** A schema cannot be expressed as Laya questions; the message names the path. */
export class SchemaError extends Error {
constructor(message: string) {
super(message);
this.name = "SchemaError";
}
}
/** The detailed result of `decide(..., { returnDetails: true })`. */
export interface DecisionResult {
/** Schema-shaped output (choice values, integer levels, booleans). */
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. */
answers: Record<string, unknown>;
usage?: unknown;
routing?: unknown;
}
/** One planned field: the Laya question plus how to project its answer back. */
export interface PlannedField {
name: string;
kind: "choice" | "score" | "noul";
question: QuestionDef;
/** choice: (label, value) pairs, in enum order. */
options?: [string, unknown][];
/** score: value of level 0. */
minimum?: number;
}
/** Anything with an async predict(state, questions, opts) — Agent and Router both qualify. */
export interface DecideRunner {
predict(
state: unknown,
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 {
/** Explicit questions instead of a schema (answers are returned unprojected). */
questions?: Record<string, QuestionDef>;
/** Return a DecisionResult with confidence, probabilities and raw answers. */
returnDetails?: boolean;
/** Minimum confidence threshold in [0.0, 1.0] or per-bucket map. Low confidence answers project to null. */
minConfidence?: MinConfidence | null;
/** Python parity alias for minConfidence. */
min_confidence?: MinConfidence | null;
/** Anything else is forwarded to runner.predict (hooks, model, ...). */
[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;
/** Python-parity alias for minConfidence. */
min_confidence?: 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 {
if (v === null || v === undefined) return "NoneType";
if (Array.isArray(v)) return "list";
switch (typeof v) {
case "boolean": return "bool";
case "number": return Number.isInteger(v) ? "int" : "float";
case "string": return "str";
case "object": return "dict";
default: return typeof v;
}
}
/** Accept a JSON schema object or a model exposing toJSONSchema()/model_json_schema()/schema(). */
function schemaOf(model: unknown): Record<string, unknown> {
const m = model as Record<string, any>;
for (const key of ["toJSONSchema", "model_json_schema", "schema"]) {
if (typeof m?.[key] === "function") return m[key]();
}
if (m !== null && typeof m === "object" && !Array.isArray(m)) return m;
throw new SchemaError(`expected a JSON schema object or a model with toJSONSchema(), got ${pyType(model)}`);
}
function noulField(name: string, description: unknown): PlannedField {
return {
name,
kind: "noul",
question: { type: "noul", instructions: description || `Is \`${name}\` true?` },
};
}
function enumField(path: string, name: string, values: unknown[], description: unknown): PlannedField {
if (values.length > MAX_OPTIONS) {
throw new SchemaError(`${path}: ${values.length} options exceeds MAX_OPTIONS=${MAX_OPTIONS}`);
}
if (values.length === 0) throw new SchemaError(`${path}: 'enum' must not be empty`);
// Python's `_enum_field` takes the noul shortcut only for exactly two DISTINCT booleans
// (`all(isinstance(v, bool) ...) and len(set(values)) == 2`). Without the distinctness test a
// one-value enum became a noul here and a one-option choice there -- a different question type
// and a different projected value type (boolean vs "true") from the documented mapping -- and
// `[true, true]` became a noul instead of the duplicate-label SchemaError both SDKs promise.
if (values.length === 2 && values.every((v) => typeof v === "boolean") && values[0] !== values[1]) {
return noulField(name, description);
}
const options: [string, unknown][] = values.map((v) => [v == null ? "null" : String(v), v]);
if (new Set(options.map(([label]) => label)).size !== options.length) {
throw new SchemaError(`${path}: enum values produce duplicate choice labels`);
}
return {
name,
kind: "choice",
question: {
type: "choice",
instructions: description || `What is \`${name}\`?`,
criteria: Object.fromEntries(options.map(([label]) => [label, null])),
},
options,
};
}
function scoreField(path: string, name: string, prop: Record<string, unknown>, description: unknown): PlannedField {
const lo = prop.minimum;
const hi = prop.maximum;
if (!Number.isInteger(lo) || !Number.isInteger(hi)) {
throw new SchemaError(`${path}: a numeric field needs integer 'minimum' and 'maximum' to become a score`);
}
const loN = lo as number;
const hiN = hi as number;
if (hiN < loN) throw new SchemaError(`${path}: 'maximum' ${hiN} is below 'minimum' ${loN}`);
const span = hiN - loN + 1;
if (span > MAX_SCORE_LEVELS) {
throw new SchemaError(
`${path}: ${span} levels exceeds MAX_SCORE_LEVELS=${MAX_SCORE_LEVELS}; narrow the range or use an enum`,
);
}
return {
name,
kind: "score",
question: {
type: "score",
instructions: description || `Score \`${name}\` from ${loN} to ${hiN}`,
criteria: Array.from({ length: span }, (_, i) => String(loN + i)),
},
minimum: loN,
};
}
function fieldFor(path: string, name: string, prop: unknown): PlannedField {
if (prop === null || typeof prop !== "object" || Array.isArray(prop)) {
throw new SchemaError(`${path}: property must be an object, got ${pyType(prop)}`);
}
const p = prop as Record<string, unknown>;
const description = p.description;
if (!("const" in p || "enum" in p || "type" in p)) {
const union = (p.anyOf ?? p.oneOf) as unknown[] | undefined;
if (union !== undefined && Array.isArray(union)) {
const branches = union.filter(
(b) => b !== null && typeof b === "object" && !Array.isArray(b) && (b as Record<string, unknown>).type !== "null",
) as Record<string, unknown>[];
if (branches.length !== 1) {
throw new SchemaError(
`${path}: only 'Optional[...]' unions (one non-null branch) are supported, got ${branches.length}`,
);
}
const branch: Record<string, unknown> = { ...branches[0] };
if (branch.description === undefined && description !== undefined) {
branch.description = description;
}
return fieldFor(path, name, branch);
}
}
if ("const" in p) return enumField(path, name, [p.const], description);
if ("enum" in p) {
if (!Array.isArray(p.enum)) throw new SchemaError(`${path}: 'enum' must be a list, got ${pyType(p.enum)}`);
return enumField(path, name, p.enum, description);
}
let jtype = p.type;
if (Array.isArray(jtype)) {
const nonNullTypes = jtype.filter((t) => t !== "null"); // nullable: ["string", "null"]
if (nonNullTypes.length > 1) {
throw new SchemaError(`${path}: 'type' has multiple non-null types; unions are not supported`);
}
jtype = nonNullTypes[0];
}
if (jtype === "boolean") return noulField(name, description);
if (jtype === "string") {
throw new SchemaError(`${path}: a free string cannot be a fixed option set; use 'enum' or a boolean`);
}
if (jtype === "integer" || jtype === "number") return scoreField(path, name, p, description);
if (jtype === "array") throw new SchemaError(`${path}: arrays are not supported; ask one field per element`);
if (jtype === "object") throw new SchemaError(`${path}: nested objects are not supported; flatten the schema`);
if ("$ref" in p) throw new SchemaError(`${path}: $ref/recursion is not supported; flatten the schema`);
throw new SchemaError(`${path}: unsupported schema ${JSON.stringify(prop)}`);
}
/** Validate a JSON schema and return one planned field per property. */
export function planFromJsonSchema(schema: unknown): PlannedField[] {
if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
throw new SchemaError(`expected a JSON schema object, got ${pyType(schema)}`);
}
const s = schema as Record<string, unknown>;
if (!(s.type === undefined || s.type === null || s.type === "object") || !("properties" in s)) {
throw new SchemaError("the top level must be an object with 'properties'");
}
const properties = s.properties;
if (properties === null || typeof properties !== "object" || Array.isArray(properties)
|| Object.keys(properties).length === 0) {
throw new SchemaError("'properties' must be a non-empty object");
}
const entries = Object.entries(properties as Record<string, unknown>);
if (entries.length > MAX_PROPERTIES) {
throw new SchemaError(`${entries.length} properties exceeds MAX_PROPERTIES=${MAX_PROPERTIES}`);
}
return entries.map(([name, prop]) => fieldFor(`properties.${name}`, name, prop));
}
/** Turn a JSON schema into Laya questions (a documented subset; see the module docstring). */
export function questionsFromJsonSchema(schema: unknown): Record<string, QuestionDef> {
return Object.fromEntries(planFromJsonSchema(schema).map((f) => [f.name, f.question]));
}
/**
* Is this entry an answer object? Python's `_project` and `_details` ask the same question with
* `isinstance(answer, dict)` and skip the field when it is not true (structured.py:281, :323).
* Answers reach this port as parsed remote JSON, so the value under a field name can be a string,
* a number, a boolean or an array -- and `answer.low_confidence` on any of those is `undefined`
* rather than an error, so the unguarded read below did not crash: it invented a value. Measured
* with the other three answers well-formed and one replaced, against `laya/structured.py`:
*
* answer py (all fields) ts (before)
* "oops" omitted "undefined" (choice) / 0 (score) / false (noul)
* ["x"] omitted same
* 7 omitted same
* true omitted same
* null omitted omitted
*
* `Array.isArray` is load-bearing: `typeof` reports an array as "object", and `common.ts:408` --
* the port of the same skip -- has the primitive half of the check but not that one.
*/
function isAnswerObject(answer: unknown): answer is Record<string, any> {
return answer !== null && typeof answer === "object" && !Array.isArray(answer);
}
function project(answers: Record<string, unknown>, fields: PlannedField[]): Record<string, unknown> {
const values: Record<string, unknown> = {};
for (const f of fields) {
const answer = answers[f.name];
if (!isAnswerObject(answer)) continue;
if (answer.low_confidence) {
values[f.name] = null;
continue;
}
if (f.kind === "noul") {
values[f.name] = Number(answer.noul ?? 0.0) >= 0.5;
} else if (f.kind === "score") {
const probs: Record<string, unknown> = answer.probabilities ?? {};
const n = Object.keys(probs).length;
let idx: number;
if (n > 0) {
idx = 0;
let best = -Infinity;
for (let i = 0; i < n; i++) {
const v = Number(probs[String(i)] ?? 0.0);
if (v > best) { best = v; idx = i; }
}
} else {
// `score` is always the probability-weighted 0-based level index,
// the same space `idx` is in above -- not an absolute field value --
// so it is rounded on its own, with no `minimum` subtracted first.
idx = Math.round(Number(answer.score ?? 0.0));
}
values[f.name] = (f.minimum ?? 0) + idx;
} else {
const label = String(answer.choice);
const hit = (f.options ?? []).find(([l]) => l === label);
values[f.name] = hit ? hit[1] : label;
}
}
return values;
}
/** Project Laya answers onto the schema values (choice value, integer level, boolean). */
export function answersToJson(
answers: Record<string, unknown>,
schema: unknown,
): Record<string, unknown> {
return project(answers, planFromJsonSchema(schema));
}
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, unknown>,
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)) {
// Same rule as `project`: a non-object answer reports no confidence, no max(p) and no
// probability map, rather than a 0.0/null/{} entry for a question that was never answered.
if (!isAnswerObject(answer)) 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) };
} else {
probabilities[name] = { ...(answer.probabilities ?? {}) };
}
}
return {
values,
confidence,
answerConfidence,
probabilities,
answers: { ...answers },
usage: result.usage,
routing: result.routing,
};
}
/**
* Answer `state` against a schema (or explicit questions) and return the decided values.
*
* Pass exactly one of `schema` or `opts.questions`. With `schema`, the values follow the
* schema (choice values, integer levels, booleans). With `questions`, the raw answers are
* returned. Extra options are forwarded to `runner.predict`.
*/
export async function decide(
runner: DecideRunner,
state: unknown,
schema: unknown,
opts: DecideOptions & { returnDetails: true },
): Promise<DecisionResult>;
export async function decide(
runner: DecideRunner,
state: unknown,
schema?: unknown,
opts?: DecideOptions,
): Promise<Record<string, unknown>>;
export async function decide(
runner: DecideRunner,
state: unknown,
schema?: unknown,
opts: DecideOptions = {},
): Promise<Record<string, unknown> | DecisionResult> {
const { questions, returnDetails = false, minConfidence, min_confidence, ...predictOpts } = opts;
if ((schema == null) === (questions == null)) {
throw new Error("pass exactly one of schema= or questions=");
}
const mcOpt = minConfidence ?? min_confidence;
const mc = mcOpt !== undefined && mcOpt !== null ? checkMinConfidence(mcOpt) : null;
if (mc !== null) {
predictOpts.minConfidence = mc;
}
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 result = await runner.predict(state, qs as Record<string, QuestionDef>, predictOpts);
if (mc !== null && result && typeof result === "object") {
flagLowConfidence(result as Record<string, unknown>, mc);
}
const answers = result.answers ?? {};
const values = fields ? project(answers, fields) : { ...answers };
if (returnDetails) return detailsOf(values, answers, result);
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,
min_confidence,
...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 mcOpt = minConfidence ?? min_confidence;
const mc = mcOpt !== undefined && mcOpt !== null ? checkMinConfidence(mcOpt) : 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) {
// `Router.predictBatch` reads the routing overrides off each REQUEST and takes the hook
// controls as its third argument. Spreading everything into the request objects (what this
// path used to do) put `hooks`/`onPredictStart`/`onPredictEnd`/`hooksRaise` where
// `predictBatch` never looks, so every per-call hook -- the tracing/metrics/audit hooks this
// option exists for -- silently observed nothing on the Router path while the Agent path
// fired them. Python's `decide_batch` makes the same split: `_ROUTER_REQUEST_KEYS` onto each
// request, everything else as call keywords.
const requestKeys = ["model", "task", "lang", "langGuess", "lang_guess", "maxLen", "headMaxLen"];
const perRequest: Record<string, unknown> = {};
const callOpts: PredictBatchOptions = {};
for (const [key, value] of Object.entries(predictOpts)) {
if (requestKeys.includes(key)) {
perRequest[key] = value;
} else if (key === "hooks" || key === "onPredictStart" || key === "onPredictEnd" || key === "hooksRaise") {
(callOpts as Record<string, unknown>)[key] = value;
}
}
const requests = states.map((s) => ({ state: s, questions: qs, ...perRequest }));
const batchSize = (predictOpts.batchSize ?? null) as number | null;
results = await predictBatchFn.call(runner, requests, batchSize, callOpts);
} 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);
}