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): add local Agent and Router predictLong

wowe62cd678ab93
diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.ts
index bfef3b9f..fa133562 100644
--- a/laya-ts/src/agent.ts
+++ b/laya-ts/src/agent.ts
@@ -22,6 +22,8 @@ import {
import type { BinningMap, InternalQ, MinConfidence, OptionStats, SequenceStats } from "./common.js";
import type { Batch, SessionProvider } from "./providers.js";
import type { OptionStabilityReport } from "./option-stability.js";
+import { predictLong, recordLongResults, finishLongResults, isLongCall, type LongPredictOptions, type LongResult } from "./predict-long.js";
+export type { LongPredictOptions, LongResult, LongUsage, LongAnswer, LongWindow } from "./predict-long.js";
import { encodeWithData, parseTokenizerJson, type TokenizerLike } from "./tokenizer.js";
import { decide, decideBatch, type DecideOptions, type DecideBatchOptions, type DecisionResult } from "./structured.js";
import {
@@ -616,11 +618,12 @@ export class Agent extends HookRegistry {
throw err;
} finally {
ctx.markElapsed();
- if (ctx.results !== null) {
+ if (ctx.results !== null && (!isLongCall(opts) || Array.isArray(ctx.results))) {
ctx.usage = aggregateUsage(ctx.results);
if (mc !== null) {
flagLowConfidence(ctx.results as unknown as Record<string, unknown>[], mc);
}
+ recordLongResults(opts, ctx);
}
try {
await dispatchAsync(active, "onPredictEnd", ctx, { raiseErrors, timeoutMs });
@@ -629,6 +632,7 @@ export class Agent extends HookRegistry {
if (ctx.error === null) throw hookErr;
}
}
+ finishLongResults(opts, ctx);
return ctx.results as unknown as SystemOneResult[];
}
@@ -882,6 +886,19 @@ export class Agent extends HookRegistry {
return this._predictHooked(states, questions, opts);
}
+ /** Scan overlapping token windows locally and keep each question's strongest answer.
+ * Attribution refers to the original candidate token slice; decoding and re-encoding can
+ * change its length. Confidence belongs to the winning window, not the whole document.
+ * Agent hooks wrap one batch of windows. A hook budget change is checked after inference.
+ */
+ async predictLong(
+ state: unknown,
+ questions: Record<string, QuestionDef>,
+ opts: LongPredictOptions = {},
+ ): Promise<LongResult> {
+ return predictLong(this, 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
diff --git a/laya-ts/src/index.ts b/laya-ts/src/index.ts
index cec8a0d0..28d2b3c7 100644
--- a/laya-ts/src/index.ts
+++ b/laya-ts/src/index.ts
@@ -1,5 +1,6 @@
export const VERSION = "0.1.0";
export { Agent, checkQuestion, toInternal, defaultTokenizer } from "./agent.js";
+export type { LongPredictOptions, LongResult, LongUsage, LongAnswer, LongWindow } from "./predict-long.js";
export type {
QuestionDef,
SystemOneResult,
@@ -16,7 +17,7 @@ export type {
export { createNodeProvider, createWebProvider, feed, feedHead, loadNodeBundle, loadWebBundle, PINNED_REVISIONS, resolveRevision } from "./providers.js";
export type { Batch, SessionProvider, ProviderOptions, NodeBundle, WebBundle } from "./providers.js";
export { Router, normaliseName, DEFAULT_MODELS, digestsFromEnv, _digestsFromEnv } from "./router.js";
-export type { RoutedResult, RouteDecision, ModelName, ModelSpec, BatchRequest, PredictBatchOptions, RouterOptions, RouteOptions } from "./router.js";
+export type { RoutedResult, RoutedLongResult, RoutedLongPredictOptions, RouteDecision, ModelName, ModelSpec, BatchRequest, PredictBatchOptions, RouterOptions, RouteOptions } from "./router.js";
export { shortlistChoice, predictShortlist, predictTournament, embedFnFromAgent, cached, cachedEmbedFn, DEFAULT_SHORTLIST_K, DEFAULT_SHORTLIST_MAXSIZE, DEFAULT_TOURNAMENT_GROUP } from "./shortlist.js";
export type { EmbedFn, ShortlistMeta, TournamentMeta, CacheInfo, CachedEmbedFn } from "./shortlist.js";
export { analyse, isEnglish, guessLatinLanguage, detectScript } from "./lang.js";
diff --git a/laya-ts/src/predict-long.ts b/laya-ts/src/predict-long.ts
new file mode 100644
index 00000000..cd350282
--- /dev/null
+++ b/laya-ts/src/predict-long.ts
@@ -0,0 +1,361 @@
+import { buildQuestionPrefix, serializeState } from "./common.js";
+import type { OptionStats } from "./common.js";
+import { checkQuestion, toInternal } from "./agent.js";
+import type { Agent, QuestionDef, SystemAnswer, PredictOptions } from "./agent.js";
+import { defaultsAlreadyRan, markDefaultsRan, normaliseHooks } from "./hooks.js";
+import type { HookArg, PredictContext, PredictHook } from "./hooks.js";
+
+export interface LongWindow {
+ index: number;
+ token_start: number;
+ token_end: number;
+ count: number;
+}
+
+export type LongAnswer = SystemAnswer & { window?: LongWindow };
+
+/** Long scans sum numeric usage, including boolean truncation flags. */
+export interface LongUsage {
+ input_tokens: number;
+ output_tokens: number;
+ windows: number;
+ state_tokens?: number;
+ state_tokens_dropped?: number;
+ truncated?: boolean | number;
+ truncated_questions?: string[];
+ options?: Record<string, OptionStats>;
+ [key: string]: unknown;
+}
+
+export interface LongResult {
+ model: string;
+ answers: Record<string, LongAnswer>;
+ usage: LongUsage;
+}
+
+// Deliberately independent of PredictOptions: windows are sized from the Agent config,
+// and the winning window's confidence is not a document-level confidence threshold.
+export interface LongPredictOptions {
+ window?: number | null;
+ stride?: number | null;
+ aggregate?: "auto";
+ batchSize?: number | null;
+ lang?: string | null;
+ hooks?: HookArg;
+ onPredictStart?: PredictHook;
+ onPredictEnd?: PredictHook;
+ hooksRaise?: boolean;
+ hooksTimeout?: number | null;
+}
+
+type Dict = Record<string, unknown>;
+function isDict(value: unknown): value is Dict {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+ const proto = Object.getPrototypeOf(value);
+ return proto === Object.prototype || proto === null;
+}
+
+function copyValue<T>(value: T): T {
+ if (Array.isArray(value)) return value.map(copyValue) as T;
+ if (isDict(value)) return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, copyValue(val)])) as T;
+ return value;
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+ if (Object.is(a, b)) return true;
+ if (Array.isArray(a) && Array.isArray(b)) {
+ return a.length === b.length && a.every((value, i) => sameValue(value, b[i]));
+ }
+ if (isDict(a) && isDict(b)) {
+ const keys = Object.keys(a);
+ return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && sameValue(a[key], b[key]));
+ }
+ return false;
+}
+
+/** Validate values supplied by hooks without widening ordinary prediction types. */
+export function validateLongResult(value: unknown, label = "predictLong result", requireWindows = true): asserts value is LongResult {
+ if (!isDict(value) || typeof value.model !== "string" || !isDict(value.answers) || !isDict(value.usage)) {
+ throw new TypeError(`${label}: expected model, answers and usage objects`);
+ }
+ const usage = value.usage;
+ for (const key of ["input_tokens", "output_tokens", "state_tokens", "state_tokens_dropped"]) {
+ if (key !== "input_tokens" && key !== "output_tokens" && usage[key] === undefined) continue;
+ if (typeof usage[key] !== "number" || !Number.isFinite(usage[key]) || usage[key] < 0) {
+ throw new TypeError(`${label}: usage.${key} must be a finite non-negative number`);
+ }
+ }
+ if ((requireWindows || usage.windows !== undefined) &&
+ (!Number.isSafeInteger(usage.windows) || (usage.windows as number) < 0)) {
+ throw new TypeError(`${label}: usage.windows must be a non-negative safe integer`);
+ }
+ if (usage.truncated !== undefined && typeof usage.truncated !== "boolean" &&
+ (typeof usage.truncated !== "number" || !Number.isFinite(usage.truncated) || usage.truncated < 0)) {
+ throw new TypeError(`${label}: usage.truncated must be a boolean or non-negative number`);
+ }
+ if (usage.truncated_questions !== undefined && (!Array.isArray(usage.truncated_questions) ||
+ usage.truncated_questions.some((qid) => typeof qid !== "string"))) {
+ throw new TypeError(`${label}: usage.truncated_questions must be an array of question ids`);
+ }
+ if (usage.options !== undefined && (!isDict(usage.options) || Object.values(usage.options).some((stats) =>
+ !isDict(stats) || ["total", "distinct"].some((key) => typeof stats[key] !== "number" || !Number.isFinite(stats[key]) || stats[key] < 0) ||
+ (stats.tokens_per_option !== null && (typeof stats.tokens_per_option !== "number" || !Number.isFinite(stats.tokens_per_option) || stats.tokens_per_option < 0))))) {
+ throw new TypeError(`${label}: usage.options must map question ids to option statistics`);
+ }
+ for (const [qid, answer] of Object.entries(value.answers)) {
+ if (!isDict(answer) || !["choice", "score", "noul"].includes(answer.type as string)) {
+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)} must have a supported type`);
+ }
+ for (const key of ["confidence", "answer_confidence", ...(answer.type === "noul" ? ["noul"] : answer.type === "score" ? ["score"] : [])]) {
+ if (typeof answer[key] !== "number" || !Number.isFinite(answer[key])) {
+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.${key} must be a finite number`);
+ }
+ }
+ if (answer.type === "choice" && typeof answer.choice !== "string") {
+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.choice must be a string`);
+ }
+ if (!isDict(answer.action) || typeof answer.action.act_probability !== "number" || !Number.isFinite(answer.action.act_probability)) {
+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.action.act_probability must be a finite number`);
+ }
+ if (answer.type !== "noul" && (!isDict(answer.probabilities) ||
+ Object.values(answer.probabilities).some((probability) => typeof probability !== "number" || !Number.isFinite(probability)))) {
+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.probabilities must map labels to finite numbers`);
+ }
+ if (answer.type === "score" && (!isDict(answer.legend) || Object.values(answer.legend).some((level) => typeof level !== "string"))) {
+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.legend must map levels to strings`);
+ }
+ if (answer.window !== undefined) {
+ const w = answer.window;
+ if (!isDict(w) || !["index", "token_start", "token_end", "count"].every((key) => Number.isSafeInteger(w[key]) && (w[key] as number) >= 0) ||
+ (w.index as number) >= (w.count as number) || (w.token_start as number) > (w.token_end as number)) {
+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.window is invalid`);
+ }
+ }
+ }
+}
+
+/** Cache results are copied; counting a skipped scan must not mutate the caller's cache. */
+export function skippedLongResult(value: unknown): LongResult {
+ validateLongResult(value, "predictLong hook result", false);
+ return { ...value, usage: { ...value.usage, windows: 0 } };
+}
+
+export function validateLongOptions(opts: LongPredictOptions): void {
+ for (const key of ["window", "stride", "batchSize"] as const) {
+ const value = opts[key];
+ if (value !== undefined && value !== null && (!Number.isSafeInteger(value) || value <= 0)) {
+ throw new TypeError(`predictLong: ${key} must be a positive safe integer`);
+ }
+ }
+ if (opts.aggregate !== undefined && opts.aggregate !== "auto") {
+ throw new Error("predictLong: only aggregate='auto' is supported");
+ }
+}
+
+interface AnswerRecord { index: number; values: Dict }
+interface Evidence {
+ answered: boolean;
+ states: unknown[] | null;
+ questionTypes: Record<string, unknown> | null;
+ questions: Dict | null;
+ maxLen: number | null;
+ headMaxLen: number | null;
+ answers: Map<object, Map<string, AnswerRecord | null>> | null;
+ resultCount: number | null;
+ trackAnswers: boolean;
+}
+
+const recorders = new WeakMap<PredictOptions, Evidence>();
+export function isLongCall(opts: PredictOptions): boolean { return recorders.has(opts); }
+
+/** The short public systemOne path returns just the first result; retain its final count. */
+export function finishLongResults(opts: PredictOptions, ctx: PredictContext): void {
+ const evidence = recorders.get(opts);
+ if (!evidence) return;
+ if (!Array.isArray(ctx.results)) throw new TypeError("predictLong: prediction hooks must return an array of results");
+ evidence.resultCount = ctx.results.length;
+}
+const predictionFields = ["type", "choice", "noul", "score", "legend", "probabilities", "confidence", "answer_confidence"];
+function answerValues(answer: Dict): Dict {
+ return Object.fromEntries(predictionFields.filter((key) => Object.hasOwn(answer, key)).map((key) => [key, copyValue(answer[key])]));
+}
+
+/** Internal dispatcher boundary: record inference results before any end hook can edit them. */
+export function recordLongResults(opts: PredictOptions, ctx: PredictContext): void {
+ const evidence = recorders.get(opts);
+ if (!evidence || !Array.isArray(ctx.results)) return;
+ evidence.resultCount = ctx.results.length;
+ if (evidence.answered || !evidence.trackAnswers) return;
+ const recorded: NonNullable<Evidence["answers"]> = new Map();
+ ctx.results.forEach((result, index) => {
+ if (!isDict(result?.answers)) return;
+ for (const [qid, answer] of Object.entries(result.answers)) {
+ if (!isDict(answer)) continue;
+ let byQuestion = recorded.get(answer);
+ if (!byQuestion) recorded.set(answer, byQuestion = new Map());
+ byQuestion.set(qid, byQuestion.has(qid) ? null : { index, values: answerValues(answer) });
+ }
+ });
+ evidence.answers = recorded;
+}
+
+function observedOptions(opts: LongPredictOptions, trackAnswers: boolean): [PredictOptions, Evidence] {
+ const evidence: Evidence = { answered: false, states: null, questionTypes: null, questions: null,
+ maxLen: null, headMaxLen: null, answers: null, resultCount: null, trackAnswers };
+ const hooks = normaliseHooks(opts.hooks, opts.onPredictStart, opts.onPredictEnd);
+ hooks.push({ onPredictStart(ctx) {
+ evidence.answered = ctx.results !== null;
+ evidence.states = Array.isArray(ctx.states) ? [...ctx.states] : null;
+ if (!evidence.answered && isDict(ctx.questions)) {
+ evidence.questionTypes = Object.fromEntries(Object.entries(ctx.questions).map(([qid, q]) => [qid, isDict(q) ? q.type : null]));
+ }
+ evidence.maxLen = ctx.maxLen;
+ evidence.headMaxLen = ctx.headMaxLen;
+ evidence.questions = isDict(ctx.questions) ? { ...ctx.questions } : null;
+ } });
+ const call: PredictOptions = { lang: opts.lang, hooks, hooksRaise: opts.hooksRaise, hooksTimeout: opts.hooksTimeout };
+ if (defaultsAlreadyRan(opts)) markDefaultsRan(call);
+ recorders.set(call, evidence);
+ return [call, evidence];
+}
+
+function stateRoom(agent: Agent, questions: Record<string, QuestionDef>, maxLen: number, headMaxLen: number): number[] {
+ return Object.values(questions).map((q) => Math.max(0, maxLen - buildQuestionPrefix(agent.tok, toInternal(q), maxLen, headMaxLen).ids.length - 1));
+}
+
+function windowBudget(agent: Agent, questions: Record<string, QuestionDef>, opts: LongPredictOptions): [number, number, number] {
+ const requested = opts.window ?? Math.max(64, agent.maxLen - agent.headMaxLen - 8);
+ const rooms = stateRoom(agent, questions, agent.maxLen, agent.headMaxLen);
+ const room = rooms.length ? Math.min(...rooms) : requested;
+ if (room <= 0) throw new Error(`predictLong: the questions' options fill the whole sequence (maxLen=${agent.maxLen}, headMaxLen=${agent.headMaxLen}), leaving no room for the state`);
+ const size = Math.min(requested, room);
+ if (size < requested && (opts.window != null || requested >= room * 2)) {
+ console.warn(`laya: predictLong: questions leave ${room} state tokens inside maxLen=${agent.maxLen}; capping window ${requested} -> ${size}. Fewer or shorter options reduce the number of full forward passes.`);
+ }
+ let step = opts.stride ?? Math.max(1, Math.floor(size / 2));
+ if (step > size) {
+ if (size < requested && step <= requested) {
+ const adjusted = Math.max(1, Math.floor(size / 2));
+ console.warn(`laya: predictLong: window was reduced to ${size}; adjusting stride ${step} -> ${adjusted} to avoid unread gaps`);
+ step = adjusted;
+ } else {
+ throw new Error(`predictLong: stride=${step} steps past the ${size}-token window; pass stride <= ${size}`);
+ }
+ }
+ return [size, step, room];
+}
+
+function checkScanBudget(agent: Agent, evidence: Evidence, sized: number, asked: Record<string, QuestionDef>): void {
+ if (evidence.answered || !evidence.questions || !Object.keys(evidence.questions).length) return;
+ const maxLen = evidence.maxLen ?? agent.maxLen;
+ const headMaxLen = evidence.headMaxLen ?? agent.headMaxLen;
+ if (maxLen === agent.maxLen && headMaxLen === agent.headMaxLen && sameValue(evidence.questions, asked)) return;
+ let rooms: number[];
+ try { rooms = stateRoom(agent, evidence.questions as Record<string, QuestionDef>, maxLen, headMaxLen); }
+ catch { return; } // Malformed questions belong to the normal inference validator.
+ const room = Math.min(...rooms);
+ if (room < sized) throw new Error(`predictLong: after the start hooks ran, the questions and token budget (maxLen=${maxLen} headMaxLen=${headMaxLen}) leave ${room} state tokens per window, but the scan was sized for ${sized} from the agent's config (maxLen=${agent.maxLen} headMaxLen=${agent.headMaxLen}). Every window would be re-truncated and parts of the document would reach no model. Pass window/stride explicitly, or call predictBatch directly, if a start hook changes either.`);
+}
+
+export async function predictLong(agent: Agent, state: unknown, questions: Record<string, QuestionDef>, opts: LongPredictOptions): Promise<LongResult> {
+ if (state === null || state === undefined) throw new TypeError("state must not be None; pass a string, dict, or list");
+ if (!isDict(questions)) throw new TypeError("questions must be a dict of question id -> definition");
+ validateLongOptions(opts);
+ for (const [qid, q] of Object.entries(questions)) checkQuestion(qid, q);
+ const [budget, step, room] = windowBudget(agent, questions, opts);
+ const asked = copyValue(questions);
+ const stateIds = agent.tok.encode(serializeState(state).split(agent.tok.maskToken).join(" "));
+ if (stateIds.length <= (opts.window != null ? budget : room)) {
+ const [call, evidence] = observedOptions(opts, false);
+ let single: unknown;
+ try { single = await agent.systemOne(state, questions, call); }
+ finally { recorders.delete(call); }
+ // Correctness checks are outside the hook dispatcher and its suppression/timeout policy.
+ // Inference has already run; changing that order would change the hook contract.
+ checkScanBudget(agent, evidence, Math.max(budget, stateIds.length), asked);
+ if (evidence.answered) {
+ if (evidence.resultCount !== 1) throw new Error(`predictLong: a start hook answered this state with ${evidence.resultCount} results; ctx.skip() takes one result for the document`);
+ console.warn("laya: predictLong: a hook answered the state before it was scanned, so no window decided the result");
+ return skippedLongResult(single);
+ }
+ validateLongResult(single, "predictLong result", false);
+ return { ...single, usage: { ...single.usage, windows: 1 } };
+ }
+ if (typeof agent.tok.decode !== "function") {
+ const name = (agent.tok as { name?: unknown }).name ?? agent.tok.constructor?.name ?? "custom tokenizer";
+ throw new Error(`predictLong: tokenizer ${JSON.stringify(name)} needs decode(ids) to split a long state`);
+ }
+ const windows: string[] = [], starts: number[] = [];
+ for (let start = 0; start < stateIds.length; start += step) {
+ windows.push(agent.tok.decode(stateIds.slice(start, start + budget)));
+ starts.push(start);
+ if (start + budget >= stateIds.length) break;
+ }
+ const [call, evidence] = observedOptions(opts, true);
+ const configBudget = Math.max(64, agent.maxLen - agent.headMaxLen - 8);
+ const unclamped = Math.max(1, Math.ceil(windows.length * Math.max(1, Math.floor(budget / 2)) / Math.max(1, Math.floor(configBudget / 2))));
+ call.batchSize = opts.batchSize ?? (budget < configBudget && windows.length > unclamped * 2 ? unclamped : null);
+ let results: unknown;
+ try { results = await agent.predictBatch([...windows], questions, call); }
+ finally { recorders.delete(call); }
+ checkScanBudget(agent, evidence, budget, asked);
+ if (!Array.isArray(results)) throw new TypeError("predictLong: prediction hooks must return an array of results");
+ if (evidence.answered) {
+ if (results.length !== 1) throw new Error(`predictLong: a start hook answered this state with ${results.length} results; ctx.skip() takes one result for the document, not one per window`);
+ console.warn("laya: predictLong: a hook answered the state before it was scanned, so no window decided the result");
+ return skippedLongResult(results[0]);
+ }
+ const rewritten = evidence.states !== null && !sameValue(evidence.states, windows);
+ if (results.length !== windows.length && !rewritten) throw new Error(`predictLong: the state was split into ${windows.length} windows and the call returned ${results.length} results`);
+ if (!results.length) {
+ console.warn("laya: predictLong: a start hook left no states to score, so the call aggregated nothing and returns no answers");
+ return { model: "laya-rl-agent", answers: {}, usage: { input_tokens: 0, output_tokens: 0, windows: 0 } };
+ }
+ for (const result of results) validateLongResult(result, "predictLong window result", false);
+ const rows = results as LongResult[];
+ const questionTypes = evidence.questionTypes ?? Object.fromEntries(Object.entries(questions).map(([qid, q]) => [qid, q.type]));
+ const answers: Record<string, LongAnswer> = {};
+ for (const [qid, qtype] of Object.entries(questionTypes)) {
+ const missing = rows.filter((r) => !Object.hasOwn(r.answers, qid)).length;
+ if (missing) {
+ if (missing === rows.length && !Object.hasOwn(asked, qid) && evidence.questionTypes !== null) continue;
+ throw new Error(`predictLong: answer ${JSON.stringify(qid)} is missing from ${missing} of ${rows.length} windows after prediction hooks`);
+ }
+ const per = rows.map((r) => r.answers[qid]);
+ if (per.some((answer) => answer.type !== per[0].type)) throw new Error(`predictLong: answer ${JSON.stringify(qid)} has inconsistent types across windows`);
+ // The inference schema chooses the aggregation rule, even when end hooks uniformly
+ // rewrite the answer schema. Such edits invalidate attribution, not the result itself.
+ const metric = (answer: LongAnswer): number => qtype === "noul" ? (answer as { noul: number }).noul : answer.answer_confidence;
+ if (per.some((answer) => !Number.isFinite(metric(answer)))) throw new TypeError(`predictLong: answer ${JSON.stringify(qid)} is missing the numeric aggregation field for ${String(qtype)}`);
+ let best = 0;
+ for (let i = 1; i < per.length; i++) if (metric(per[i]) > metric(per[best])) best = i;
+ const original = per[best];
+ let index: number | null = null;
+ if (!rewritten) {
+ if (evidence.answers === null) index = best; // A replacement predictBatch did not dispatch hooks.
+ else {
+ const record = evidence.answers.get(original)?.get(qid);
+ if (record && sameValue(record.values, answerValues(original as unknown as Dict))) index = record.index;
+ }
+ }
+ const answer = { ...original };
+ delete answer.window;
+ if (index !== null) answer.window = { index, token_start: starts[index], token_end: Math.min(starts[index] + budget, stateIds.length), count: rows.length };
+ Object.defineProperty(answers, qid, { value: answer, enumerable: true, writable: true, configurable: true });
+ }
+ const usage: Dict = Object.create(null);
+ for (const row of rows) {
+ for (const [key, value] of Object.entries(row.usage)) {
+ const previous = usage[key];
+ if (typeof value === "number" || typeof value === "boolean") {
+ usage[key] = (typeof previous === "number" || typeof previous === "boolean" ? Number(previous) : 0) + Number(value);
+ } else if (isDict(value) && isDict(previous)) usage[key] = { ...previous, ...value };
+ else Object.defineProperty(usage, key, { value, enumerable: true, writable: true, configurable: true });
+ }
+ }
+ const result = { model: "laya-rl-agent", answers, usage: { ...usage, output_tokens: 0, windows: rows.length } as LongUsage };
+ // Individually finite window counters can still overflow when summed. The Agent
+ // must uphold the same result contract that the Router checks at its boundary.
+ validateLongResult(result);
+ return result;
+}
diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.ts
index 11c6f151..5a85b104 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 { checkQuestion, type PredictOptions, type QuestionDef, type SystemOneResult } from "./agent.js";
+import { skippedLongResult, validateLongOptions, validateLongResult, type LongPredictOptions, type LongResult } from "./predict-long.js";
import { checkMinConfidence, flagLowConfidence } from "./common.js";
import { decide, decideBatch, type DecideOptions, type DecideBatchOptions, type DecisionResult } from "./structured.js";
import {
@@ -11,6 +12,7 @@ import {
markDefaultsRan,
dispatchAsync,
normaliseHooks,
+ validateHooksTimeout,
type Hook,
type HookArg,
type PredictHook,
@@ -110,6 +112,23 @@ export interface RouteDecision {
}
export type RoutedResult = SystemOneResult & { routing: RouteDecision };
+export type RoutedLongResult = LongResult & { routing: RouteDecision };
+export type RoutedLongPredictOptions = RouteOptions & LongPredictOptions;
+
+function validLongRouting(routing: RouteDecision | undefined): boolean {
+ if (!routing || typeof routing !== "object" || Array.isArray(routing) ||
+ !Object.hasOwn(DEFAULT_MODELS, routing.model) || typeof routing.repo !== "string" ||
+ typeof routing.reason !== "string" ||
+ (routing.workflow !== null && typeof routing.workflow !== "string")) return false;
+ const d = routing.detection;
+ return d === null || (typeof d === "object" && !Array.isArray(d) &&
+ typeof d.script === "string" && (d.language === null || typeof d.language === "string") &&
+ typeof d.isEnglish === "boolean" && typeof d.languageUndecided === "boolean" &&
+ Number.isFinite(d.diacriticRate) && Number.isFinite(d.nonLatinFraction) &&
+ (d.mixedSegment === null || typeof d.mixedSegment === "string") &&
+ d.scriptProfile !== null && typeof d.scriptProfile === "object" && !Array.isArray(d.scriptProfile) &&
+ Object.values(d.scriptProfile).every((value) => typeof value === "number" && Number.isFinite(value)));
+}
export type LangGuess = string | null | undefined | ((state: unknown) => unknown);
@@ -591,6 +610,25 @@ export class Router extends HookRegistry {
questions: Record<string, QuestionDef>,
opts: RouteOptions & PredictOptions = {},
): Promise<RoutedResult> {
+ return this._predict(state, questions, opts) as Promise<RoutedResult>;
+ }
+
+ /** Route the document once, then scan it using the selected Agent's window budget. */
+ async predictLong(
+ state: unknown,
+ questions: Record<string, QuestionDef>,
+ opts: RoutedLongPredictOptions = {},
+ ): Promise<RoutedLongResult> {
+ validateLongOptions(opts);
+ return this._predict(state, questions, opts, opts) as Promise<RoutedLongResult>;
+ }
+
+ private async _predict(
+ state: unknown,
+ questions: Record<string, QuestionDef>,
+ opts: RouteOptions & PredictOptions,
+ scan?: LongPredictOptions,
+ ): Promise<RoutedResult | RoutedLongResult> {
if (state === null || state === undefined) {
throw new TypeError("state must not be None; pass a string, dict, or list");
}
@@ -599,10 +637,12 @@ export class Router extends HookRegistry {
`questions must be a dict of question id -> definition, got ${questions === null ? "null" : Array.isArray(questions) ? "Array" : typeof questions}`,
);
}
- const mcOpt = opts.minConfidence ?? opts.min_confidence;
+ const mcOpt = scan ? undefined : opts.minConfidence ?? opts.min_confidence;
const mc = mcOpt !== undefined && mcOpt !== null ? checkMinConfidence(mcOpt) : null;
const active = composeHooks(this.hooks, opts.hooks, opts.onPredictStart, opts.onPredictEnd);
const raiseErrors = opts.hooksRaise ?? this.hooksRaise;
+ const timeout = scan ? validateHooksTimeout(scan.hooksTimeout) : null;
+ const timeoutMs = timeout === null ? null : timeout * 1000;
const hasStart = active.some((h) => typeof h.onPredictStart === "function");
// The per-call token-budget overrides seed the context, so a start hook can read and rewrite
// them exactly as it can `states`/`questions`; the values it leaves are what reaches the agent
@@ -615,8 +655,8 @@ export class Router extends HookRegistry {
model: null,
agent: null,
router: this,
- maxLen: opts.maxLen ?? null,
- headMaxLen: opts.headMaxLen ?? null,
+ maxLen: scan ? null : opts.maxLen ?? null,
+ headMaxLen: scan ? null : opts.headMaxLen ?? null,
});
try {
// Per-call hooks apply to the whole call, including onRoute inside route().
@@ -632,7 +672,7 @@ export class Router extends HookRegistry {
};
ctx.agent = agent;
- await dispatchAsync(active, "onPredictStart", ctx, { raiseErrors });
+ await dispatchAsync(active, "onPredictStart", ctx, { raiseErrors, timeoutMs });
if (ctx.results === null) {
if (hasStart) {
if (typeof ctx.questions !== "object" || ctx.questions === null || Array.isArray(ctx.questions)) {
@@ -659,14 +699,36 @@ export class Router extends HookRegistry {
if (ctx.maxLen !== null && ctx.maxLen !== undefined) agentOpts.maxLen = ctx.maxLen;
if (ctx.headMaxLen !== null && ctx.headMaxLen !== undefined) agentOpts.headMaxLen = ctx.headMaxLen;
markDefaultsRan(agentOpts);
- const result = (await agent.systemOne(
- ctx.states[0],
- ctx.questions as Record<string, QuestionDef>,
- agentOpts,
- )) as RoutedResult;
- result["routing"] = { ...decision };
+ let result: RoutedResult | RoutedLongResult;
+ if (scan) {
+ // Read the context after start hooks, but run inference outside hook dispatch. A
+ // timeout or suppressed hook error must never turn a scan into one truncated pass.
+ const runner = ctx.agent as { predictLong?: (s: unknown, q: Record<string, QuestionDef>, o: LongPredictOptions) => Promise<LongResult> } | null;
+ if (typeof runner?.predictLong !== "function") {
+ throw new TypeError("Router.predictLong requires the routed agent to implement predictLong");
+ }
+ const detection = ctx.decision?.detection as AnalyseResult | null | undefined;
+ const longOpts: LongPredictOptions = {
+ window: scan.window, stride: scan.stride, aggregate: scan.aggregate,
+ batchSize: scan.batchSize, lang: scan.lang ?? detection?.language ?? null,
+ };
+ markDefaultsRan(longOpts);
+ const scanned = await runner.predictLong(ctx.states[0], ctx.questions as Record<string, QuestionDef>, longOpts);
+ validateLongResult(scanned, "Router.predictLong agent result");
+ result = { ...scanned, routing: (scanned as RoutedLongResult).routing ?? { ...decision } };
+ } else {
+ result = (await agent.systemOne(ctx.states[0], ctx.questions as Record<string, QuestionDef>, agentOpts)) as RoutedResult;
+ result.routing = { ...decision };
+ }
ctx.results = [result as unknown as Record<string, unknown>];
} else {
+ if (scan) {
+ if (!Array.isArray(ctx.results) || ctx.results.length !== 1) {
+ throw new Error("Router.predictLong: a skipping hook must return exactly one document result");
+ }
+ ctx.results = [skippedLongResult(ctx.results[0]) as unknown as Record<string, unknown>];
+ console.warn("laya: Router.predictLong: a start hook answered the document without scanning; usage.windows is 0");
+ }
// A cache hit short-circuits inference, but predict still promises a `routing` key.
// Add it without overwriting a routing the cached payload already has.
for (const result of ctx.results) {
@@ -678,27 +740,37 @@ export class Router extends HookRegistry {
} catch (err) {
ctx.error = err;
try {
- await dispatchAsync(active, "onError", ctx, { raiseErrors });
+ await dispatchAsync(active, "onError", ctx, { raiseErrors, timeoutMs });
} catch {
// A failing onError hook must not hide the failure that triggered it.
}
throw err;
} finally {
ctx.markElapsed();
- if (ctx.results !== null) {
+ if (ctx.results !== null && (!scan || Array.isArray(ctx.results))) {
ctx.usage = aggregateUsage(ctx.results);
if (mc !== null) {
flagLowConfidence(ctx.results as unknown as Record<string, unknown>[], mc);
}
}
try {
- await dispatchAsync(active, "onPredictEnd", ctx, { raiseErrors });
+ await dispatchAsync(active, "onPredictEnd", ctx, { raiseErrors, timeoutMs });
} catch (hookErr) {
// End hooks run on the failure path too; do not let one mask the real error.
if (ctx.error === null) throw hookErr;
}
}
- return (ctx.results as unknown as RoutedResult[])[0];
+ if (scan) {
+ if (!Array.isArray(ctx.results) || ctx.results.length !== 1) {
+ throw new Error("Router.predictLong must return exactly one document result");
+ }
+ validateLongResult(ctx.results[0], "Router.predictLong result");
+ const routing = ctx.results[0].routing as RouteDecision | undefined;
+ if (!validLongRouting(routing)) {
+ throw new TypeError("Router.predictLong result must include a valid routing decision");
+ }
+ }
+ return (ctx.results as unknown as (RoutedResult | RoutedLongResult)[])[0];
}
/**
diff --git a/laya-ts/tests/agent-long.test.ts b/laya-ts/tests/agent-long.test.ts
new file mode 100644
index 00000000..5f0af51b
--- /dev/null
+++ b/laya-ts/tests/agent-long.test.ts
@@ -0,0 +1,286 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Agent, defaultTokenizer, type QuestionDef } from "../src/agent.js";
+import { clearDefaultHooks, setDefaultHooks, type PredictContext } from "../src/hooks.js";
+import { OptionStabilityHook } from "../src/option-stability.js";
+import type { Batch, SessionProvider } from "../src/providers.js";
+
+afterEach(() => { clearDefaultHooks(); vi.restoreAllMocks(); });
+const questions: Record<string, QuestionDef> = { q: { type: "noul", instructions: "true?" } };
+const document = "abcdefghijklmnopqrstuvwxyz".repeat(4);
+const tok = { ...defaultTokenizer(),
+ encode: (text: string) => Array.from(text, (c) => c.codePointAt(0)! + 200),
+ decode: (ids: readonly number[]) => String.fromCodePoint(...ids.map((id) => id - 200)),
+};
+function makeAgent(increasing = false, options = {}) {
+ const batches: Batch[] = [];
+ let row = 0;
+ const provider: SessionProvider = {
+ async runEncoder(batch) { batches.push(batch); return { lastHidden: batch.inputIds.map(() => [[0]]) }; },
+ async runHead(_hidden, batch) {
+ return { logits: batch.qtype.map((_, i) => batch.markerPos[i].map((_, option) => option === 1 ? increasing ? ++row / 4 : 2 : 0)), act: batch.qtype.map(() => [0, 1]) };
+ },
+ };
+ return { agent: new Agent({ provider, tok, max_len: 80, head_max_len: 32, ...options }), batches };
+}
+
+describe("Agent.predictLong", () => {
+ it("preserves short-path output and supports encode-only custom tokenizers", async () => {
+ const { agent } = makeAgent();
+ const { decode: _decode, ...encodeOnly } = tok;
+ agent.tok = encodeOnly;
+ const ordinary = await agent.predict("short", questions);
+ expect(await agent.predictLong("short", questions)).toEqual({ ...ordinary, usage: { ...ordinary.usage, windows: 1 } });
+ await expect(agent.predictLong(document, questions, { window: 20 })).rejects.toThrow("needs decode");
+ });
+
+ it("rejects bad questions and unsafe options before hooks or inference", async () => {
+ const { agent, batches } = makeAgent();
+ const hook = vi.fn();
+ await expect(agent.predictLong(document, { q: { type: "invalid" } }, { onPredictStart: hook })).rejects.toThrow('question "q"');
+ for (const key of ["window", "stride", "batchSize"]) {
+ for (const value of [0, -1, 1.1, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1, true]) {
+ await expect(agent.predictLong(document, questions, { [key]: value, onPredictStart: hook })).rejects.toThrow("positive safe integer");
+ }
+ }
+ await expect(agent.predictLong(document, questions, { window: 10, stride: 11 })).rejects.toThrow("stride=11");
+ await expect(agent.predictLong(document, questions, { aggregate: "mean" as never })).rejects.toThrow("only aggregate");
+ expect(hook).not.toHaveBeenCalled();
+ expect(batches).toHaveLength(0);
+ });
+
+ it("uses batched inference, earliest ties, candidate spans and numeric truncation counts", async () => {
+ const { agent, batches } = makeAgent();
+ const result = await agent.predictLong(document, questions, { window: 20, stride: 10, batchSize: 3 });
+ expect(result.answers.q.window).toEqual({ index: 0, token_start: 0, token_end: 20, count: 10 });
+ expect(result.usage.windows).toBe(10);
+ expect(result.usage.truncated).toBe(0);
+ expect(batches.map((b) => b.inputIds.length)).toEqual([3, 3, 3, 1]);
+ expect(result.usage.output_tokens).toBe(0);
+ });
+
+ it("keeps inference answer identity through default/installed/per-call end-hook reordering", async () => {
+ const events: string[] = [];
+ setDefaultHooks({ onPredictStart: () => { events.push("default-start"); }, onPredictEnd: (ctx) => { ctx.results!.reverse(); events.push("default-end"); } });
+ const { agent } = makeAgent(true, { hooks: { onPredictStart: () => { events.push("installed-start"); }, onPredictEnd: () => { events.push("installed-end"); } } });
+ const result = await agent.predictLong(document, questions, { window: 20,
+ onPredictStart: async () => { await Promise.resolve(); events.push("call-start"); },
+ onPredictEnd: () => { events.push("call-end"); },
+ });
+ expect(result.answers.q.window).toEqual({ index: 9, token_start: 90, token_end: 104, count: 10 });
+ expect(events).toEqual(["default-start", "installed-start", "call-start", "default-end", "installed-end", "call-end"]);
+ });
+
+ it("does not invent an origin for an answer object shared by inference rows", async () => {
+ const { agent } = makeAgent();
+ const base = await agent.predict("short", questions);
+ vi.spyOn(agent as any, "_systemOneMany").mockImplementation(async (states: unknown[]) => states.map(() => ({ ...base })));
+ const result = await agent.predictLong(document, questions, { window: 20 });
+ expect(result.answers.q).not.toHaveProperty("window");
+ });
+
+ it("preserves the replacement-batch fallback but does not excuse missing added answers", async () => {
+ const { agent } = makeAgent();
+ const base = await agent.predict("short", questions);
+ vi.spyOn(agent, "predictBatch").mockImplementation(async (states) => states.map(() => structuredClone(base)));
+ const result = await agent.predictLong(document, questions, { window: 20 });
+ expect(result.answers.q.window?.index).toBe(0);
+ await expect(agent.predictLong(document, { ...questions, extra: questions.q }, { window: 20 })).rejects.toThrow('answer "extra" is missing');
+ });
+
+ it("clamps requested windows and adjusts their stride before inference, with a bounded default batch", async () => {
+ const { agent, batches } = makeAgent();
+ const warnings = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const wide = { q: { type: "choice", instructions: "pick", criteria: Array.from({ length: 11 }, (_, i) => `label${i}`) } };
+ let actualStates: unknown[] = [];
+ const result = await agent.predictLong("x".repeat(150), wide, { window: 80, stride: 40,
+ onPredictStart(ctx) { actualStates = [...ctx.states]; },
+ });
+ const size = result.answers.q.window!.token_end;
+ expect(size).toBeLessThan(40);
+ expect(actualStates.length).toBe(result.usage.windows);
+ expect(batches.length).toBeGreaterThan(1);
+ expect(Math.max(...batches.map((b) => b.inputIds.length))).toBeLessThan(result.usage.windows);
+ expect(warnings).toHaveBeenCalledTimes(2);
+ await expect(agent.predictLong(document, wide, { window: 80, stride: 81 })).rejects.toThrow("stride=81");
+ });
+
+ it.each(["clone", "probabilities", "confidence", "shared"])("drops attribution for %s answer edits", async (edit) => {
+ const { agent } = makeAgent();
+ const result = await agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {
+ const first = ctx.results![0].answers as Record<string, any>;
+ for (const row of ctx.results!) {
+ const answers = row.answers as Record<string, any>;
+ if (edit === "clone") answers.q = { ...answers.q };
+ else if (edit === "probabilities") answers.q.probabilities = { yes: 1 };
+ else if (edit === "confidence") answers.q.confidence = 0.123;
+ else answers.q = first.q;
+ }
+ } });
+ // End hooks that share the first unchanged answer retain that first answer's known
+ // origin. Sharing at inference time, tested separately, has no unique origin.
+ if (edit === "shared") expect(result.answers.q.window?.index).toBe(0);
+ else expect(result.answers.q).not.toHaveProperty("window");
+ });
+
+ it("keeps attribution after action/reliability annotations and equal-value state replacements", async () => {
+ const { agent } = makeAgent();
+ const result = await agent.predictLong(document, questions, { window: 20,
+ onPredictStart(ctx) { ctx.states = ctx.states.map((state) => `${state}`); },
+ onPredictEnd(ctx) {
+ for (const row of ctx.results!) {
+ const answer = (row.answers as Record<string, any>).q;
+ answer.action = { act_probability: 0.1 };
+ answer.reliability = { note: "external" };
+ }
+ },
+ });
+ expect(result.answers.q.window?.index).toBe(0);
+ expect(result.answers.q.action.act_probability).toBe(0.1);
+ });
+
+ it("omits all attribution when start hooks rewrite/reorder/remove windows", async () => {
+ for (const rewrite of [(ctx: PredictContext) => { ctx.states.reverse(); },
+ (ctx: PredictContext) => { ctx.states = ["replacement"]; },
+ (ctx: PredictContext) => { ctx.states = []; }]) {
+ const { agent } = makeAgent();
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ const result = await agent.predictLong(document, questions, { window: 20, onPredictStart: rewrite });
+ if (!result.usage.windows) expect(result.answers).toEqual({});
+ else expect(result.answers.q).not.toHaveProperty("window");
+ }
+ });
+
+ it("accepts exactly one cached document, copies usage, and rejects malformed hook payloads", async () => {
+ const { agent, batches } = makeAgent();
+ const cached = await agent.predict("cached", questions);
+ const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const priorRuns = batches.length;
+ for (const state of ["short", document]) {
+ const result = await agent.predictLong(state, questions, { window: 20, onPredictStart: (ctx) => ctx.skip([cached as never]) });
+ expect(result.usage.windows).toBe(0);
+ expect(result).not.toBe(cached);
+ expect(result.usage).not.toBe(cached.usage);
+ expect(cached.usage).not.toHaveProperty("windows");
+ await expect(agent.predictLong(state, questions, { window: 20, onPredictStart: (ctx) => ctx.skip([cached as never, cached as never]) })).rejects.toThrow("one result for the document");
+ await expect(agent.predictLong(state, questions, { window: 20, onPredictStart: (ctx) => ctx.skip([{ model: "cache", answers: {}, usage: { input_tokens: "wrong", output_tokens: 0 } }]) })).rejects.toThrow("input_tokens");
+ }
+ expect(warning).toHaveBeenCalled();
+ expect(batches).toHaveLength(priorRuns);
+ });
+
+ it("validates malformed result arrays and end-hook skip counts without masking the error", async () => {
+ const { agent } = makeAgent();
+ await expect(agent.predictLong("short", questions, { onPredictStart(ctx) { ctx.results = {} as never; } })).rejects.toThrow("array of results");
+ const base = await agent.predict("short", questions);
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ await expect(agent.predictLong("short", questions, {
+ onPredictStart(ctx) { ctx.skip([base as never]); },
+ onPredictEnd(ctx) { ctx.results!.push(base as never); },
+ })).rejects.toThrow("2 results");
+ await expect(agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {
+ (ctx.results![0].answers as Record<string, any>).q.type = "choice";
+ (ctx.results![0].answers as Record<string, any>).q.choice = "yes";
+ (ctx.results![0].answers as Record<string, any>).q.probabilities = { yes: 1 };
+ } })).rejects.toThrow("inconsistent types");
+ });
+
+ it("keeps uniformly rewritten answer schemas while applying the original aggregation rule", async () => {
+ const { agent } = makeAgent();
+ const result = await agent.predictLong(document, { q: { type: "choice", instructions: "pick", criteria: ["a", "b"] } }, {
+ window: 20, onPredictEnd(ctx) {
+ for (const row of ctx.results!) Object.assign((row.answers as Record<string, any>).q,
+ { type: "score", score: 1, legend: { "0": "low", "1": "high" } });
+ },
+ });
+ expect(result.answers.q.type).toBe("score");
+ expect(result.answers.q).not.toHaveProperty("window");
+ });
+
+ it("runs the budget guard after inference even with suppressed hook errors", async () => {
+ const { agent, batches } = makeAgent();
+ await expect(agent.predictLong(document, questions, { window: 40, hooksRaise: false,
+ onPredictStart(ctx) { ctx.maxLen = 45; },
+ })).rejects.toThrow("scan was sized for 40");
+ expect(batches.length).toBeGreaterThan(0);
+ const short = makeAgent();
+ await expect(short.agent.predictLong("x".repeat(40), questions, { hooksRaise: false,
+ onPredictStart(ctx) { ctx.maxLen = 45; },
+ })).rejects.toThrow("scan was sized");
+ expect(short.batches.length).toBeGreaterThan(0);
+ });
+
+ it("rejects aggregate usage overflow after individually valid window reports", async () => {
+ const { agent } = makeAgent();
+ await expect(agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {
+ for (const result of ctx.results!) {
+ (result.usage as Record<string, unknown>).input_tokens = Number.MAX_VALUE;
+ }
+ } })).rejects.toThrow("usage.input_tokens must be a finite non-negative number");
+ });
+
+ it("preserves own prototype-named keys in generic usage without changing its prototype", async () => {
+ const { agent } = makeAgent();
+ const result = await agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {
+ for (const row of ctx.results!) {
+ row.usage = { ...(row.usage as object), ...JSON.parse('{"__proto__":2,"constructor":{"seen":true}}') };
+ }
+ } });
+ expect(Object.hasOwn(result.usage, "__proto__")).toBe(true);
+ expect(result.usage["__proto__"]).toBe(result.usage.windows * 2);
+ expect(result.usage["constructor"]).toEqual({ seen: true });
+ expect(Object.getPrototypeOf(result.usage)).toBe(Object.prototype);
+ });
+
+ it("detects nested in-place question edits against the pre-hook deep snapshot", async () => {
+ const { agent, batches } = makeAgent();
+ const q: Record<string, QuestionDef> = { q: { type: "choice", instructions: "pick", criteria: { a: "A", b: "B" } } };
+ await expect(agent.predictLong(document, q, { window: 40, hooksRaise: false, onPredictStart(ctx) {
+ Object.assign((ctx.questions.q as QuestionDef).criteria as object, Object.fromEntries(Array.from({ length: 8 }, (_, i) => [`extra${i}`, "extra"])));
+ } })).rejects.toThrow("scan was sized");
+ expect(batches.length).toBeGreaterThan(0);
+ });
+
+ it("allows only uniformly removed start-added questions", async () => {
+ const { agent } = makeAgent();
+ const start = (ctx: PredictContext) => { ctx.questions = { ...ctx.questions, probe: questions.q }; };
+ const result = await agent.predictLong(document, questions, { window: 20, onPredictStart: start, onPredictEnd(ctx) {
+ for (const row of ctx.results!) delete (row.answers as Record<string, unknown>).probe;
+ } });
+ expect(Object.keys(result.answers)).toEqual(["q"]);
+ await expect(agent.predictLong(document, questions, { window: 20, onPredictStart: start, onPredictEnd(ctx) {
+ delete (ctx.results![0].answers as Record<string, unknown>).probe;
+ } })).rejects.toThrow('answer "probe" is missing from 1 of 10');
+ await expect(agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {
+ for (const row of ctx.results!) delete (row.answers as Record<string, unknown>).q;
+ } })).rejects.toThrow('answer "q" is missing from 10 of 10');
+ });
+
+ it("uses a real OptionStabilityHook without leaking probe questions or losing spans", async () => {
+ const { agent } = makeAgent(false, { hooks: new OptionStabilityHook({ accept: null, escalate: null, variants: "fast", seed: "long" }) });
+ const result = await agent.predictLong(document, { q: { type: "choice", instructions: "pick", criteria: ["a", "b"] } }, { window: 20 });
+ expect(Object.keys(result.answers)).toEqual(["q"]);
+ expect(result.answers.q.window?.index).toBe(0);
+ expect(result.answers.q).toHaveProperty("reliability");
+ });
+
+ it("keeps concurrent long and ordinary contexts independent", async () => {
+ const { agent } = makeAgent();
+ const [left, right, ordinary] = await Promise.all([
+ agent.predictLong(document, questions, { window: 20, onPredictStart: async (ctx) => { await Promise.resolve(); ctx.states.reverse(); } }),
+ agent.predictLong(document, questions, { window: 30 }),
+ agent.predict("short", questions),
+ ]);
+ expect(left.answers.q).not.toHaveProperty("window");
+ expect(right.answers.q.window?.token_end).toBe(30);
+ expect(ordinary.usage).not.toHaveProperty("windows");
+ });
+
+ it("sums numeric usage, shallow-merges dictionaries, and preserves last other fields", async () => {
+ const { agent } = makeAgent();
+ const result = await agent.predictLong("x".repeat(30), questions, { window: 20, stride: 20, onPredictEnd(ctx) {
+ Object.assign(ctx.results![0].usage as object, { custom: 1, truncated: true, options: { first: { total: 2, distinct: 1, tokens_per_option: 4 } }, last: ["first"] });
+ Object.assign(ctx.results![1].usage as object, { custom: 2, truncated: false, options: { second: { total: 3, distinct: 2, tokens_per_option: 4 } }, last: [] });
+ } });
+ expect(result.usage).toMatchObject({ custom: 3, truncated: 1, options: { first: { total: 2 }, second: { total: 3 } }, last: [], windows: 2 });
+ });
+});
diff --git a/laya-ts/tests/package-e2e.mjs b/laya-ts/tests/package-e2e.mjs
index 3310ce38..92034f8e 100644
--- a/laya-ts/tests/package-e2e.mjs
+++ b/laya-ts/tests/package-e2e.mjs
@@ -107,7 +107,7 @@ test("the packed module installs and works in an external ESM TypeScript project
await writeFile(
join(consumerDir, "runtime.mjs"),
`import assert from "node:assert/strict";
-import { Agent, VERSION, predictTournament, DEFAULT_TOURNAMENT_GROUP,
+import { Agent, Router, defaultTokenizer, VERSION, predictTournament, DEFAULT_TOURNAMENT_GROUP,
OptionStabilityHook, calibrateReliability, decideReliability } from "laya-ts";
let encoderCalls = 0;
@@ -151,6 +151,21 @@ assert.equal(stable.answers.intent.reliability.n_variants, 3);
assert.equal(stable.answers.intent.reliability.decision, null);
const cuts = calibrateReliability([0.80001, 0.80002], [false, true], { targetAccuracy: 1 });
assert.equal(decideReliability(0.80002, ...cuts), "ACCEPT");
+const longAgent = new Agent({ provider, tok: {
+ ...defaultTokenizer(),
+ encode: (text) => Array.from(text, (c) => c.codePointAt(0) + 1000),
+ decode: (ids) => String.fromCodePoint(...ids.map((id) => id - 1000)),
+} });
+const longRouter = new Router();
+longRouter.attach("english", longAgent);
+const long = await longRouter.predictLong("a long document ".repeat(8), {
+ intent: { type: "choice", instructions: "Pick", criteria: ["refund", "other"] },
+}, { model: "english", window: 40, stride: 20, batchSize: 2 });
+assert(long.usage.windows > 1);
+assert.equal(typeof long.usage.truncated, "number");
+assert.equal(long.answers.intent.choice, "refund");
+assert.equal(long.answers.intent.window.token_start, 0);
+assert.equal(long.routing.model, "english");
`,
);
await run(process.execPath, ["runtime.mjs"], consumerDir);
@@ -168,6 +183,7 @@ assert.equal(decideReliability(0.80002, ...cuts), "ACCEPT");
type SessionProvider,
type SystemOneResult,
type TournamentMeta,
+ type LongResult,
} from "laya-ts";
const provider: SessionProvider = {
@@ -205,6 +221,8 @@ async function reliability(): Promise<OptionStabilityReport | undefined> {
return result.answers.intent.type === "choice" ? result.answers.intent.reliability : undefined;
}
void reliability;
+const longPrediction: Promise<LongResult> = new Agent({ provider }).predictLong("short", questions);
+void longPrediction;
`,
);
await writeFile(
diff --git a/laya-ts/tests/router-long.test.ts b/laya-ts/tests/router-long.test.ts
new file mode 100644
index 00000000..fb22c005
--- /dev/null
+++ b/laya-ts/tests/router-long.test.ts
@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Router } from "../src/router.js";
+import { clearDefaultHooks, defaultsAlreadyRan, setDefaultHooks } from "../src/hooks.js";
+
+const questions = { q: { type: "noul", instructions: "Is this urgent?" } };
+const result = (windows = 3) => ({ model: "test", answers: {}, usage: { input_tokens: 12, output_tokens: 0, windows } });
+afterEach(() => { clearDefaultHooks(); vi.restoreAllMocks(); });
+
+describe("Router.predictLong", () => {
+ it("routes and loads once, forwards language and scan options, wraps the document", async () => {
+ const calls: string[] = [];
+ setDefaultHooks({ onPredictStart: () => { calls.push("default"); } });
+ const predictLong = vi.fn(async (_s, _q, opts) => {
+ expect(defaultsAlreadyRan(opts)).toBe(true);
+ calls.push("scan");
+ return result();
+ });
+ const loader = vi.fn(async () => ({ predictLong }));
+ const router = new Router({ loader, hooks: {
+ onRoute: () => { calls.push("route"); },
+ onPredictStart: (ctx) => { expect(ctx.states).toHaveLength(1); calls.push("start"); },
+ onPredictEnd: () => { calls.push("end"); },
+ } });
+ const out = await router.predictLong("Please refund the duplicate charge on my invoice", questions,
+ { window: 80, stride: 40, batchSize: 2, aggregate: "auto" });
+ expect(loader).toHaveBeenCalledTimes(1);
+ expect(predictLong).toHaveBeenCalledTimes(1);
+ expect(predictLong.mock.calls[0][2]).toMatchObject({ lang: "en", window: 80, stride: 40, batchSize: 2, aggregate: "auto" });
+ expect(out.routing.model).toBe("english");
+ expect(out.usage.windows).toBe(3);
+ expect(calls).toEqual(["route", "default", "start", "scan", "end"]);
+ });
+
+ it("uses the post-start agent, state, questions and detected language", async () => {
+ const original = { predictLong: vi.fn() };
+ const changed = { predictLong: vi.fn(async () => result(2)) };
+ const router = new Router({ loader: async () => original });
+ const changedQuestions = { other: { type: "noul", instructions: "Changed?" } };
+ await router.predictLong("hello", questions, { onPredictStart(ctx) {
+ ctx.agent = changed;
+ ctx.states = ["changed"];
+ ctx.questions = changedQuestions;
+ ctx.decision = { ...ctx.decision, detection: { language: "de" } };
+ ctx.maxLen = 1; ctx.headMaxLen = 1;
+ } });
+ expect(original.predictLong).not.toHaveBeenCalled();
+ expect(changed.predictLong).toHaveBeenCalledWith("changed", changedQuestions, expect.objectContaining({ lang: "de" }));
+ expect(changed.predictLong.mock.calls[0]).toHaveLength(3);
+ const opts = changed.predictLong.mock.calls[0][2] as Record<string, unknown>;
+ expect(opts).not.toHaveProperty("maxLen");
+ expect(opts).not.toHaveProperty("headMaxLen");
+ });
+
+ it("copies a skipped cached document and usage, warns and reports zero windows", async () => {
+ const cached = { model: "cached", answers: {}, usage: { input_tokens: 8, output_tokens: 0 } };
+ const predictLong = vi.fn();
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const router = new Router({ loader: async () => ({ predictLong }) });
+ const out = await router.predictLong("hello", questions, { onPredictStart: (ctx) => ctx.skip([cached]) });
+ expect(predictLong).not.toHaveBeenCalled();
+ expect(out).not.toBe(cached);
+ expect(out.usage).not.toBe(cached.usage);
+ expect(out.usage.windows).toBe(0);
+ expect(cached.usage).not.toHaveProperty("windows");
+ expect(cached).not.toHaveProperty("routing");
+ expect(warn).toHaveBeenCalled();
+ });
+
+ it.each([{ results: [] }, { results: [result(), result()] }])("rejects ambiguous hook document results", async ({ results }) => {
+ const router = new Router({ loader: async () => ({}) });
+ await expect(router.predictLong("hello", questions, { hooksRaise: false,
+ onPredictStart: (ctx) => ctx.skip(results),
+ })).rejects.toThrow(/exactly one/);
+ });
+
+ it("propagates missing scan support and inference errors even when hooks are suppressed", async () => {
+ const systemOne = vi.fn(async () => result());
+ const router = new Router({ loader: async () => ({ systemOne }) });
+ await expect(router.predictLong("hello", questions, { hooksRaise: false })).rejects.toThrow(/implement predictLong/);
+ expect(systemOne).not.toHaveBeenCalled();
+ router.attach("english", { predictLong: async () => { throw new Error("scan failed"); } });
+ await expect(router.predictLong("hello", questions, { model: "english", hooksRaise: false })).rejects.toThrow("scan failed");
+ });
+
+ it("does not apply hook timeouts to inference", async () => {
+ const router = new Router({ loader: async () => ({ predictLong: async () => {
+ await new Promise((resolve) => setTimeout(resolve, 30));
+ return result();
+ } }) });
+ await expect(router.predictLong("hello", questions, { hooksTimeout: 0.001, hooksRaise: true })).resolves.toMatchObject({ usage: { windows: 3 } });
+ });
+
+ it("keeps concurrent ordinary and long calls isolated, including reentrant ordinary prediction", async () => {
+ const calls: string[] = [];
+ const agent = {
+ systemOne: vi.fn(async (state) => { calls.push(`ordinary:${state}`); return result(1); }),
+ predictLong: vi.fn(async (state) => { calls.push(`long:${state}`); return result(4); }),
+ };
+ const router = new Router({ loader: async () => agent });
+ const [long, ordinary] = await Promise.all([
+ router.predictLong("long", questions, { onPredictStart: async () => { await router.predict("nested", questions); } }),
+ router.predict("ordinary", questions),
+ ]);
+ expect(long.usage.windows).toBe(4);
+ expect(ordinary.model).toBe("test");
+ expect(calls.sort()).toEqual(["long:long", "ordinary:nested", "ordinary:ordinary"]);
+ });
+
+ it("validates the final document supplied by an end hook", async () => {
+ const router = new Router({ loader: async () => ({ predictLong: async () => result() }) });
+ await expect(router.predictLong("hello", questions, { hooksRaise: false, onPredictEnd(ctx) {
+ ctx.results = [{ ...result(), usage: { input_tokens: 0, output_tokens: 0, windows: -1 } }];
+ } })).rejects.toThrow(/windows/);
+ });
+
+ it("refuses an end-hook replacement that drops the promised routing decision", async () => {
+ const router = new Router({ loader: async () => ({ predictLong: async () => result() }) });
+ await expect(router.predictLong("hello", questions, { hooksRaise: false, onPredictEnd(ctx) {
+ ctx.results = [result()];
+ } })).rejects.toThrow(/routing decision/);
+ });
+
+ it("validates detection metadata in a hook-supplied routing decision", async () => {
+ const router = new Router({ loader: async () => ({ predictLong: async () => result() }) });
+ await expect(router.predictLong("hello", questions, { onPredictEnd(ctx) {
+ (ctx.results![0].routing as Record<string, unknown>).detection = {};
+ } })).rejects.toThrow(/routing decision/);
+ });
+
+ it.each([{ window: 0 }, { stride: 1.5 }, { batchSize: -1 }, { window: Number.MAX_SAFE_INTEGER + 1 }])("rejects invalid scan options before loading: %j", async (opts) => {
+ const loader = vi.fn();
+ await expect(new Router({ loader }).predictLong("hello", questions, opts)).rejects.toThrow();
+ expect(loader).not.toHaveBeenCalled();
+ });
+});
diff --git a/laya-ts/tests/types/predict-long.ts b/laya-ts/tests/types/predict-long.ts
new file mode 100644
index 00000000..51f1cdea
--- /dev/null
+++ b/laya-ts/tests/types/predict-long.ts
@@ -0,0 +1,31 @@
+import {
+ Agent, Router, type TokenizerLike, type LongPredictOptions, type LongResult,
+ type RoutedLongResult, type SystemOneResult,
+} from "../../src/index.js";
+
+declare const agent: Agent;
+declare const router: Router;
+declare const encodeOnly: Omit<TokenizerLike, "decode">;
+const oldTokenizer: TokenizerLike = encodeOnly;
+const options: LongPredictOptions = { window: 80, stride: 40, batchSize: 2, aggregate: "auto", hooksTimeout: 1 };
+const questions = { q: { type: "noul", instructions: "Is this urgent?" } };
+const long: Promise<LongResult> = agent.predictLong("document", questions, options);
+const routed: Promise<RoutedLongResult> = router.predictLong("document", questions, { ...options, lang: "en" });
+const ordinary: Promise<SystemOneResult> = agent.predict("document", questions);
+async function inspect() {
+ const truncated: boolean | number | undefined = (await long).usage.truncated;
+ const originalTruncated: boolean | undefined = (await ordinary).usage.truncated;
+ const windowStart: number | undefined = (await long).answers.q.window?.token_start;
+ return [truncated, originalTruncated, windowStart];
+}
+// @ts-expect-error long prediction uses the checkpoint budget, not ordinary per-call truncation
+agent.predictLong("document", questions, { maxLen: 128 });
+// @ts-expect-error headMaxLen does not belong to the long options
+router.predictLong("document", questions, { headMaxLen: 64 });
+// @ts-expect-error a window winner's confidence is not a calibrated document confidence gate
+agent.predictLong("document", questions, { minConfidence: 0.9 });
+// @ts-expect-error only the reference auto aggregator is supported
+agent.predictLong("document", questions, { aggregate: "mean" });
+void oldTokenizer;
+void routed;
+void inspect;