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 structured decisions (decide) to laya-ts

Aashish15fcff64814c
diff --git a/laya-ts/README.md b/laya-ts/README.md
index 4b124855..615dbdf7 100644
--- a/laya-ts/README.md
+++ b/laya-ts/README.md
@@ -67,6 +67,36 @@ class MetricsHook extends BaseHook {
setDefaultHooks([new MetricsHook()]); // addDefaultHook(...) appends; clearDefaultHooks() resets
```
+## Structured decisions (`decide`)
+
+Turn a JSON schema into typed values in one call — the port of Python's `laya.structured`
+(#280). Enum properties become choice questions, booleans become noul, bounded integers
+become scores; anything the fixed-option model cannot answer (free strings, arrays, nested
+objects, `$ref`) is rejected with a `SchemaError` naming the path:
+
+```ts
+import { Agent, decide } from "laya-ts";
+
+const agent = await Agent.load("./dist/laya");
+const values = await agent.decide(ticketText, {
+ type: "object",
+ properties: {
+ department: { type: "string", enum: ["billing", "support", "sales"] },
+ urgency: { type: "integer", minimum: 0, maximum: 2 },
+ needs_human: { type: "boolean" },
+ },
+});
+// { department: "billing", urgency: 2, needs_human: false }
+```
+
+`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)` —
+any object with a `toJSONSchema()` method is accepted. `planFromJsonSchema`,
+`questionsFromJsonSchema` and `answersToJson` expose the planning and projection steps.
+
+## Shortlist (many labels)
## Shortlist (many labels)
```ts
diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.ts
index 294b7ad7..77a43670 100644
--- a/laya-ts/src/agent.ts
+++ b/laya-ts/src/agent.ts
@@ -13,6 +13,7 @@ import {
} 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 {
HookRegistry,
PredictContext,
@@ -441,6 +442,29 @@ export class Agent extends HookRegistry {
return this.systemOne(state, questions, opts);
}
+ /**
+ * Answer `state` against a JSON schema (or explicit `opts.questions`) and return typed
+ * values — see `structured.ts`. Pass exactly one of `schema` or `opts.questions`; other
+ * options are forwarded to `predict`.
+ */
+ async decide(
+ state: unknown,
+ schema: unknown,
+ opts: DecideOptions & PredictOptions & { returnDetails: true },
+ ): Promise<DecisionResult>;
+ async decide(
+ state: unknown,
+ schema?: unknown,
+ opts?: DecideOptions & PredictOptions,
+ ): Promise<Record<string, unknown>>;
+ async decide(
+ state: unknown,
+ schema?: unknown,
+ opts: DecideOptions & PredictOptions = {},
+ ): Promise<Record<string, unknown> | DecisionResult> {
+ return decide(this, state, schema, opts);
+ }
+
static async load(
modelDirOrRepo: string,
opts?: {
diff --git a/laya-ts/src/index.ts b/laya-ts/src/index.ts
index 6f81120b..8f281e46 100644
--- a/laya-ts/src/index.ts
+++ b/laya-ts/src/index.ts
@@ -38,6 +38,17 @@ export {
} from "./hooks.js";
export type { Hook, HookEvent, HookArg, PredictHook, PredictHookArg } from "./hooks.js";
export { triageQuestions, emailQuestions, guardQuestions, moderationQuestions, routerQuestions } from "./presets.js";
+export {
+ decide,
+ planFromJsonSchema,
+ questionsFromJsonSchema,
+ answersToJson,
+ SchemaError,
+ MAX_PROPERTIES,
+ MAX_OPTIONS,
+ MAX_SCORE_LEVELS,
+} from "./structured.js";
+export type { DecisionResult, DecideOptions, DecideRunner, PlannedField } from "./structured.js";
export {
renderOptions,
serializeState,
diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.ts
index b98941ba..e2bd472f 100644
--- a/laya-ts/src/router.ts
+++ b/laya-ts/src/router.ts
@@ -1,5 +1,6 @@
import { analyse, type AnalyseResult } from "./lang.js";
import type { PredictOptions, QuestionDef, SystemOneResult } from "./agent.js";
+import { decide, type DecideOptions, type DecisionResult } from "./structured.js";
import {
HookRegistry,
PredictContext,
@@ -488,6 +489,29 @@ export class Router extends HookRegistry {
return (ctx.results as unknown as RoutedResult[])[0];
}
+ /**
+ * Answer `state` against a JSON schema (or explicit `opts.questions`) and return typed
+ * values — see `structured.ts`. Routing options (`model`, `task`, ...) are forwarded to
+ * `predict`.
+ */
+ async decide(
+ state: unknown,
+ schema: unknown,
+ opts: DecideOptions & RouteOptions & PredictOptions & { returnDetails: true },
+ ): Promise<DecisionResult>;
+ async decide(
+ state: unknown,
+ schema?: unknown,
+ opts?: DecideOptions & RouteOptions & PredictOptions,
+ ): Promise<Record<string, unknown>>;
+ async decide(
+ state: unknown,
+ schema?: unknown,
+ opts: DecideOptions & RouteOptions & PredictOptions = {},
+ ): Promise<Record<string, unknown> | DecisionResult> {
+ return decide(this, state, schema, opts);
+ }
+
async systemOne(
state: unknown,
questions: Record<string, QuestionDef>,
diff --git a/laya-ts/src/structured.ts b/laya-ts/src/structured.ts
new file mode 100644
index 00000000..7d1f4214
--- /dev/null
+++ b/laya-ts/src/structured.ts
@@ -0,0 +1,308 @@
+/**
+ * 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";
+
+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 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 }>;
+}
+
+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;
+ /** Anything else is forwarded to runner.predict (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`);
+ if (values.every((v) => typeof v === "boolean")) return noulField(name, description);
+ const options: [string, unknown][] = values.map((v) => [v == null ? "null" : String(v), v]);
+ 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) 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)) jtype = jtype.find((t) => t !== "null"); // nullable: ["string", "null"]
+ 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]));
+}
+
+function project(answers: Record<string, Record<string, any> | undefined>, fields: PlannedField[]): Record<string, unknown> {
+ const values: Record<string, unknown> = {};
+ for (const f of fields) {
+ const answer = answers[f.name];
+ if (answer == 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 {
+ idx = Math.round(Number(answer.score ?? 0.0)) - (f.minimum ?? 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, Record<string, any> | undefined>,
+ schema: unknown,
+): Record<string, unknown> {
+ return project(answers, planFromJsonSchema(schema));
+}
+
+
+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 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);
+ 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, 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, ...predictOpts } = opts;
+ if ((schema == null) === (questions == null)) {
+ throw new Error("pass exactly one of schema= or questions=");
+ }
+ 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);
+ const answers = result.answers ?? {};
+ const values = fields ? project(answers, fields) : { ...answers };
+ if (returnDetails) return detailsOf(values, answers, result);
+ return values;
+}
+
diff --git a/laya-ts/tests/structured.test.ts b/laya-ts/tests/structured.test.ts
new file mode 100644
index 00000000..97485b1e
--- /dev/null
+++ b/laya-ts/tests/structured.test.ts
@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import {
+ answersToJson,
+ decide,
+ planFromJsonSchema,
+ questionsFromJsonSchema,
+ SchemaError,
+ MAX_OPTIONS,
+ MAX_PROPERTIES,
+ MAX_SCORE_LEVELS,
+} from "../src/structured.js";
+import { Agent } from "../src/agent.js";
+import { Router } from "../src/router.js";
+
+// Mirrors tests/test_structured.py on the Python side.
+const SCHEMA = {
+ type: "object",
+ properties: {
+ department: { type: "string", enum: ["billing", "support", "sales"], description: "Which team?" },
+ urgency: { type: "integer", minimum: 0, maximum: 2 },
+ needs_human: { type: "boolean" },
+ priority: { enum: [1, 2, 3] },
+ },
+};
+
+const ANSWERS = {
+ department: { type: "choice", choice: "billing", confidence: 0.9,
+ probabilities: { billing: 0.9, support: 0.1, sales: 0.0 } },
+ urgency: { type: "score", score: 1.2, confidence: 0.5,
+ probabilities: { "0": 0.1, "1": 0.2, "2": 0.7 }, legend: {} },
+ needs_human: { type: "noul", noul: 0.8, confidence: 0.8 },
+ priority: { type: "choice", choice: "2", confidence: 0.7,
+ probabilities: { "1": 0.2, "2": 0.7, "3": 0.1 } },
+};
+
+describe("structured/mapping", () => {
+ const questions = questionsFromJsonSchema(SCHEMA);
+ it("enum is a choice, description becomes instructions", () => {
+ expect(questions.department.type).toBe("choice");
+ expect(questions.department.instructions).toBe("Which team?");
+ expect(Object.keys(questions.department.criteria as object)).toEqual(["billing", "support", "sales"]);
+ });
+ it("bounded number is a score with level labels", () => {
+ expect(questions.urgency.type).toBe("score");
+ expect(questions.urgency.criteria).toEqual(["0", "1", "2"]);
+ expect(questions.urgency.instructions).toBe("Score `urgency` from 0 to 2");
+ });
+ it("boolean is noul", () => {
+ expect(questions.needs_human.type).toBe("noul");
+ expect(questions.needs_human.instructions).toBe("Is `needs_human` true?");
+ });
+ it("integer enum becomes a choice with string labels", () => {
+ expect(questions.priority.type).toBe("choice");
+ expect(Object.keys(questions.priority.criteria as object)).toEqual(["1", "2", "3"]);
+ });
+ it("null enum member gets the 'null' label", () => {
+ const q = questionsFromJsonSchema({
+ type: "object", properties: { x: { enum: ["a", null] } },
+ });
+ expect(Object.keys(q.x.criteria as object)).toEqual(["a", "null"]);
+ });
+ it("const is a single-option choice", () => {
+ const q = questionsFromJsonSchema({ type: "object", properties: { x: { const: "billing" } } });
+ expect(q.x.type).toBe("choice");
+ expect(Object.keys(q.x.criteria as object)).toEqual(["billing"]);
+ });
+ it("all-boolean enum is noul", () => {
+ const q = questionsFromJsonSchema({ type: "object", properties: { x: { enum: [true, false] } } });
+ expect(q.x.type).toBe("noul");
+ });
+ it("plan has one field per property", () => {
+ expect(planFromJsonSchema(SCHEMA)).toHaveLength(4);
+ });
+});
+
+describe("structured/projection", () => {
+ it("projects answers onto schema values", () => {
+ const values = answersToJson(ANSWERS, SCHEMA);
+ expect(values.department).toBe("billing");
+ expect(values.urgency).toBe(2); // argmax level, not the raw 1.2 score
+ expect(values.needs_human).toBe(true);
+ expect(values.priority).toBe(2); // integer enum keeps its type
+ expect(typeof values.priority).toBe("number");
+ });
+ it("false noul stays false", () => {
+ const v = answersToJson({ x: { type: "noul", noul: 0.2 } },
+ { type: "object", properties: { x: { type: "boolean" } } });
+ expect(v.x).toBe(false);
+ });
+ it("score without probabilities falls back to the rounded score", () => {
+ const v = answersToJson({ x: { type: "score", score: 1.6, confidence: 0.5 } },
+ { type: "object", properties: { x: { type: "integer", minimum: 0, maximum: 2 } } });
+ expect(v.x).toBe(2);
+ });
+ it("null choice value projects back to null", () => {
+ const v = answersToJson({ x: { type: "choice", choice: "null" } },
+ { type: "object", properties: { x: { enum: ["a", null] } } });
+ expect(v.x).toBe(null);
+ });
+});
+
+describe("structured/rejections", () => {
+ const bad = (schema: unknown) => () => questionsFromJsonSchema(schema);
+ it("rejects a free string", () => {
+ expect(bad({ type: "object", properties: { a: { type: "string" } } }))
+ .toThrowError(/properties\.a: a free string cannot be a fixed option set/);
+ });
+ it("rejects arrays, nested objects and $ref", () => {
+ expect(bad({ type: "object", properties: { a: { type: "array", items: { type: "string" } } } }))
+ .toThrowError(SchemaError);
+ expect(bad({ type: "object", properties: { a: { type: "object", properties: {} } } }))
+ .toThrowError(/nested objects are not supported/);
+ expect(bad({ type: "object", properties: { a: { $ref: "#/$defs/X" } } }))
+ .toThrowError(/\$ref\/recursion is not supported/);
+ });
+ it("rejects an unbounded or too-wide number", () => {
+ expect(bad({ type: "object", properties: { a: { type: "integer", minimum: 0 } } }))
+ .toThrowError(/needs integer 'minimum' and 'maximum'/);
+ expect(bad({ type: "object", properties: { a: { type: "integer", minimum: 0, maximum: 100 } } }))
+ .toThrowError(new RegExp(`exceeds MAX_SCORE_LEVELS=${MAX_SCORE_LEVELS}`));
+ });
+ it("rejects too many properties or options", () => {
+ const manyProps = Object.fromEntries(
+ Array.from({ length: MAX_PROPERTIES + 1 }, (_, i) => [`p${i}`, { type: "boolean" }]));
+ expect(bad({ type: "object", properties: manyProps }))
+ .toThrowError(new RegExp(`exceeds MAX_PROPERTIES=${MAX_PROPERTIES}`));
+ const manyOpts = Array.from({ length: MAX_OPTIONS + 1 }, (_, i) => `v${i}`);
+ expect(bad({ type: "object", properties: { a: { type: "string", enum: manyOpts } } }))
+ .toThrowError(new RegExp(`exceeds MAX_OPTIONS=${MAX_OPTIONS}`));
+ });
+ it("rejects a non-object root and empty properties", () => {
+ expect(bad({ type: "array" })).toThrowError(/top level must be an object with 'properties'/);
+ expect(bad({ type: "object", properties: {} })).toThrowError(/non-empty object/);
+ expect(bad("nope")).toThrowError(/expected a JSON schema object, got str/);
+ });
+});
+
+describe("structured/decide", () => {
+ class FakeRunner {
+ calls: { state: unknown; questions: unknown; opts: unknown }[] = [];
+ constructor(private answers: unknown) {}
+ async predict(state: unknown, questions: any, opts: any = {}) {
+ this.calls.push({ state, questions, opts });
+ return { answers: this.answers, usage: { input_tokens: 1, output_tokens: 0 },
+ routing: { model: "english" } };
+ }
+ }
+
+ it("returns schema-shaped values and forwards state + kwargs", async () => {
+ const runner = new FakeRunner(ANSWERS);
+ const out: any = await decide(runner, "some state", SCHEMA, { hooksRaise: false });
+ expect(out.department).toBe("billing");
+ expect(runner.calls[0].state).toBe("some state");
+ expect((runner.calls[0].questions as any).department.type).toBe("choice");
+ expect((runner.calls[0].opts as any).hooksRaise).toBe(false);
+ });
+
+ it("returnDetails exposes confidence, probabilities, usage and routing", async () => {
+ const runner = new FakeRunner(ANSWERS);
+ const d = await decide(runner, "some state", SCHEMA, { returnDetails: true });
+ expect(d.confidence.department).toBe(0.9);
+ expect(d.probabilities.needs_human).toEqual({ false: 0.2, true: 0.8 });
+ expect(d.usage).toEqual({ input_tokens: 1, output_tokens: 0 });
+ expect(d.routing).toEqual({ model: "english" });
+ expect(d.values.priority).toBe(2);
+ });
+
+ it("questions pass-through returns the raw answers", async () => {
+ const raw = { a: { type: "noul", noul: 0.9, confidence: 0.9 } };
+ const runner = new FakeRunner(raw);
+ const out = await decide(runner, "s", undefined,
+ { questions: { a: { type: "noul", instructions: "?" } } });
+ expect(out).toEqual(raw);
+ });
+
+ it("requires exactly one of schema or questions", async () => {
+ const runner = new FakeRunner({});
+ await expect(decide(runner, "s")).rejects.toThrow(/exactly one of schema= or questions=/);
+ await expect(decide(runner, "s", SCHEMA, { questions: {} }))
+ .rejects.toThrow(/exactly one of schema= or questions=/);
+ });
+
+ it("accepts a model exposing toJSONSchema()", async () => {
+ const runner = new FakeRunner(ANSWERS);
+ const out: any = await decide(runner, "s", { toJSONSchema: () => SCHEMA });
+ expect(out.department).toBe("billing");
+ });
+});
+
+describe("structured/methods", () => {
+ const fakeProvider = () => ({
+ async runEncoder(b: any) {
+ const n = b?.inputIds?.length ?? 2;
+ return { lastHidden: Array.from({ length: n }, (_, i) => [i + 1, 0]) };
+ },
+ async runHead(h: any) {
+ const n = h?.length ?? 1;
+ return {
+ logits: Array.from({ length: n }, (_, i) => (i % 2 === 0 ? [2, 0] : [0, 2])),
+ act: Array.from({ length: n }, () => [3, 0]),
+ };
+ },
+ });
+
+ it("Agent.decide runs end to end against a stub provider", async () => {
+ const a = new Agent({ provider: fakeProvider() } as any);
+ const values = await a.decide("hi", {
+ type: "object",
+ properties: {
+ department: { type: "string", enum: ["billing", "support"] },
+ needs_human: { type: "boolean" },
+ },
+ });
+ expect(values.department).toBe("billing"); // argmax of the fake logits
+ expect(values.needs_human).toBe(true); // fake act head strongly positive
+ });
+
+ it("Router exposes decide", () => {
+ expect(typeof (Router.prototype as any).decide).toBe("function");
+ });
+});
+