diff --git a/laya-ts/README.md b/laya-ts/README.md index 4b124855e..615dbdf76 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 294b7ad7e..77a436705 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; + async decide( + state: unknown, + schema?: unknown, + opts?: DecideOptions & PredictOptions, + ): Promise>; + async decide( + state: unknown, + schema?: unknown, + opts: DecideOptions & PredictOptions = {}, + ): Promise | 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 6f81120b0..8f281e463 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 b98941bad..e2bd472f9 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; + async decide( + state: unknown, + schema?: unknown, + opts?: DecideOptions & RouteOptions & PredictOptions, + ): Promise>; + async decide( + state: unknown, + schema?: unknown, + opts: DecideOptions & RouteOptions & PredictOptions = {}, + ): Promise | DecisionResult> { + return decide(this, state, schema, opts); + } + async systemOne( state: unknown, questions: Record, diff --git a/laya-ts/src/structured.ts b/laya-ts/src/structured.ts new file mode 100644 index 000000000..7d1f42143 --- /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; + /** Per-field confidence. */ + confidence: Record; + /** Per-field probabilities (noul fields report { false, true }). */ + probabilities: Record>; + /** Laya's raw answer per field. */ + answers: Record; + 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, + opts?: Record, + ): Promise<{ answers?: Record | undefined>; usage?: unknown; routing?: unknown }>; +} + +export interface DecideOptions { + /** Explicit questions instead of a schema (answers are returned unprojected). */ + questions?: Record; + /** 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 { + const m = model as Record; + 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, 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; + 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; + 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); + 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 { + return Object.fromEntries(planFromJsonSchema(schema).map((f) => [f.name, f.question])); +} + +function project(answers: Record | undefined>, fields: PlannedField[]): Record { + const values: Record = {}; + 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 = 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 | undefined>, + schema: unknown, +): Record { + return project(answers, planFromJsonSchema(schema)); +} + + +function detailsOf( + values: Record, + answers: Record | undefined>, + result: { usage?: unknown; routing?: unknown }, +): DecisionResult { + const confidence: Record = {}; + const probabilities: Record> = {}; + 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; +export async function decide( + runner: DecideRunner, + state: unknown, + schema?: unknown, + opts?: DecideOptions, +): Promise>; +export async function decide( + runner: DecideRunner, + state: unknown, + schema?: unknown, + opts: DecideOptions = {}, +): Promise | 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, 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 000000000..97485b1e5 --- /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"); + }); +}); +