@tanstack/ai 0.55.0 → 0.57.0

package/dist/esm/activities/evaluate/index.d.ts

@@ -0,0 +1,255 @@
+import { DebugOption } from '../../logger/types.js';
+import { TokenUsage } from '../../types.js';
+import { GenerationMiddleware } from '../middleware/types.js';
+import { EvaluateAdapter, EvaluateInstructions, EvaluateState, WireQuestion } from './adapter.js';
+/** The adapter kind this activity handles */
+export declare const kind: "evaluate";
+/** Question key reserved for `result.meta`. */
+declare const RESERVED_QUESTION_KEY: "meta";
+/** Extract provider options from an EvaluateAdapter via ~types */
+export type EvaluateProviderOptions<TAdapter> = TAdapter extends {
+    '~types': {
+        providerOptions: infer P extends object;
+    };
+} ? P : object;
+/**
+ * Public choice answer. `.value` is the selected option key.
+ */
+export interface ChoiceAnswer<TValue extends string = string> {
+    type: 'choice';
+    value: TValue;
+    /** P(selected option). */
+    probability: number;
+    confidence: number;
+    probabilities: Record<TValue, number>;
+}
+/**
+ * Public score answer. `.value` is the nearest level label.
+ * `.score` is the raw TypeSafe fraction.
+ */
+export interface ScoreAnswer<TLevel extends string = string> {
+    type: 'score';
+    value: TLevel;
+    /** P(nearest level). */
+    probability: number;
+    confidence: number;
+    score: number;
+    legend: Record<string, string>;
+    probabilities: Record<string, number>;
+}
+/**
+ * Public yes/no answer. `.value` is `true` when P(true) is 0.5 or more.
+ * There is no `.confidence`.
+ */
+export interface BooleanAnswer {
+    type: 'boolean';
+    value: boolean;
+    /** P(true), from the wire `noul` field. */
+    probability: number;
+}
+export interface EvaluateResultMeta {
+    /** Resolved model id from the provider. */
+    model: string;
+    usage: TokenUsage;
+}
+/**
+ * Map a helper question (or wire question) to its public answer type.
+ */
+export type InferEvaluateAnswer<TQuestion> = TQuestion extends {
+    type: 'choice';
+    criteria: infer TCriteria;
+} ? TCriteria extends Record<string, string | null> ? ChoiceAnswer<Extract<keyof TCriteria, string>> : ChoiceAnswer : TQuestion extends {
+    type: 'score';
+    criteria: infer TLevels;
+} ? TLevels extends ReadonlyArray<string> ? ScoreAnswer<TLevels[number] & string> : ScoreAnswer : TQuestion extends {
+    type: 'noul';
+} ? BooleanAnswer : never;
+/**
+ * Result of `decide()`. Each question key is a top-level answer.
+ * `meta` holds the resolved model id and usage.
+ */
+export type EvaluateResult<TQuestions extends Record<string, WireQuestion>> = {
+    [K in keyof TQuestions as K extends typeof RESERVED_QUESTION_KEY ? never : K]: InferEvaluateAnswer<TQuestions[K]>;
+} & {
+    meta: EvaluateResultMeta;
+};
+/**
+ * Options for the evaluate activity. The model is extracted from the
+ * adapter's model property.
+ *
+ * @template TAdapter - The evaluate adapter type
+ * @template TQuestions - The questions object passed to `decide`
+ */
+export interface EvaluateActivityOptions<TAdapter extends EvaluateAdapter<string, EvaluateProviderOptions<TAdapter>>, TQuestions extends Record<string, WireQuestion>> {
+    /** The evaluate adapter to use (must be created with a model) */
+    adapter: TAdapter & {
+        kind: typeof kind;
+    };
+    /** Shared state every question judges. A JSON array is one state, not a batch. */
+    state: EvaluateState;
+    /**
+     * Questions built with `choice`, `score`, and `boolean`.
+     * The key `meta` is reserved.
+     */
+    questions: TQuestions;
+    /** Provider-specific options */
+    modelOptions?: EvaluateProviderOptions<TAdapter>;
+    /** Forwarded to the provider request for cancellation. */
+    abortSignal?: AbortSignal;
+    /**
+     * Observe-only middleware notified on start, usage, success, abort, and
+     * error. Pass `otelMiddleware()` to emit OpenTelemetry spans, or implement
+     * the `GenerationMiddleware` contract for a custom backend.
+     */
+    middleware?: Array<GenerationMiddleware>;
+    /**
+     * Enable debug logging. Pass `true` to enable all categories, `false` to
+     * silence everything including errors, or a `DebugConfig` object for granular
+     * control and/or a custom `Logger`.
+     */
+    debug?: DebugOption;
+}
+/**
+ * Build a choice question. The model picks one key from `options`.
+ *
+ * Option keys become the union on `.value`. Use `null` when a key needs no
+ * extra description. On the wire, `options` is sent as TypeSafe `criteria`.
+ *
+ * @param options.instructions What the model should decide.
+ * @param options.options Map of option key to description, or `null`.
+ *
+ * @example
+ * ```ts
+ * const queue = choice({
+ *   instructions: 'Which team should handle this ticket?',
+ *   options: {
+ *     billing: 'Payments, invoices, refunds',
+ *     tech: 'Bugs, outages, integrations',
+ *     sales: 'Pricing, upgrades, new accounts',
+ *   },
+ * })
+ * ```
+ */
+export declare function choice<const TOptions extends Record<string, string | null>>(options: {
+    instructions: EvaluateInstructions;
+    options: TOptions;
+}): {
+    type: "choice";
+    instructions: import('./adapter.js').EvaluateJsonValue;
+    criteria: TOptions;
+};
+/**
+ * Build a score question. The model rates `state` on ordered `levels`.
+ *
+ * You must pass at least two levels. `.value` is the nearest level label.
+ * The raw fraction stays on `.score`. On the wire, `levels` is sent as
+ * TypeSafe `criteria`.
+ *
+ * @param options.instructions What the model should rate.
+ * @param options.levels Ordered labels, lowest first. At least two.
+ *
+ * @example
+ * ```ts
+ * const urgency = score({
+ *   instructions: 'How urgent is this ticket?',
+ *   levels: ['low', 'medium', 'high'],
+ * })
+ * ```
+ */
+export declare function score<const TLevels extends ReadonlyArray<string>>(options: {
+    instructions: EvaluateInstructions;
+    levels: TLevels;
+}): {
+    type: "score";
+    instructions: import('./adapter.js').EvaluateJsonValue;
+    criteria: TLevels;
+};
+/**
+ * Build a yes/no question.
+ *
+ * `.value` is `true` when P(true) is 0.5 or more. There is no `.confidence`.
+ * On the wire, the type is TypeSafe `noul`.
+ *
+ * @param options.instructions The yes/no question to judge.
+ * @param options.criteria Optional descriptions of yes and no.
+ *
+ * @example
+ * ```ts
+ * const refund = boolean({
+ *   instructions: 'Is the customer asking for a refund?',
+ * })
+ * ```
+ */
+export declare function boolean(options: {
+    instructions: EvaluateInstructions;
+    criteria?: {
+        true?: string;
+        false?: string;
+    };
+}): {
+    type: "noul";
+    instructions: import('./adapter.js').EvaluateJsonValue;
+    criteria?: undefined;
+} | {
+    type: "noul";
+    instructions: import('./adapter.js').EvaluateJsonValue;
+    criteria: {
+        true?: string;
+        false?: string;
+    };
+};
+/**
+ * Ask typed questions about `state` and get answers your code can branch on.
+ *
+ * You have state (a ticket, a record, a log) and you need typed answers, not
+ * prose. Pass questions built with `choice`, `score`, and `boolean`. Then
+ * branch on `result.queue.value` in ordinary TypeScript.
+ *
+ * The question key `meta` is reserved. Throws if `questions` is empty or uses
+ * that key.
+ *
+ * @param options.adapter Evaluate adapter created with a model.
+ * @param options.state Shared state every question judges.
+ * @param options.questions Questions built with `choice`, `score`, `boolean`.
+ * @param options.modelOptions Provider-specific options.
+ * @param options.abortSignal Cancels the in-flight request.
+ * @param options.middleware Observe-only generation middleware.
+ * @param options.debug Debug logging option.
+ *
+ * @example Route a support ticket
+ * ```ts
+ * import { decide, choice, score, boolean } from '@tanstack/ai'
+ * import { typesafeDecider } from '@tanstack/ai-typesafe'
+ *
+ * const result = await decide({
+ *   adapter: typesafeDecider('jev-latest'),
+ *   state: ticket,
+ *   questions: {
+ *     queue: choice({
+ *       instructions: 'Which team should handle this ticket?',
+ *       options: {
+ *         billing: 'Payments, invoices, refunds',
+ *         tech: 'Bugs, outages, integrations',
+ *         sales: 'Pricing, upgrades, new accounts',
+ *       },
+ *     }),
+ *     urgency: score({
+ *       instructions: 'How urgent is this ticket?',
+ *       levels: ['low', 'medium', 'high'],
+ *     }),
+ *     refund: boolean({
+ *       instructions: 'Is the customer asking for a refund?',
+ *     }),
+ *   },
+ * })
+ *
+ * result.queue.value
+ * result.meta.model
+ * result.meta.usage
+ * ```
+ */
+export declare function decide<TAdapter extends EvaluateAdapter<string, EvaluateProviderOptions<TAdapter>>, TQuestions extends Record<string, WireQuestion>>(options: EvaluateActivityOptions<TAdapter, TQuestions>): Promise<{ [K in keyof TQuestions]: InferEvaluateAnswer<TQuestions[K]>; } & {
+    meta: EvaluateResultMeta;
+}>;
+export type { EvaluateAdapter, EvaluateAdapterConfig, AnyEvaluateAdapter, EvaluateOptions, EvaluateAdapterResult, EvaluateState, EvaluateInstructions, EvaluateJsonValue, WireQuestion, WireAnswer, WireChoiceQuestion, WireScoreQuestion, WireNoulQuestion, WireChoiceAnswer, WireScoreAnswer, WireNoulAnswer, } from './adapter.js';
+export { BaseEvaluateAdapter } from './adapter.js';

package/dist/esm/activities/evaluate/index.js

@@ -0,0 +1,317 @@
+import { isAbortShapedError } from "../error-payload.js";
+import { resolveDebugOption } from "../../logger/resolve.js";
+import { createGenerationContext, runGenerationAbort, runGenerationError, runGenerationFinish, runGenerationStart, runGenerationUsage } from "../middleware/run.js";
+import "./adapter.js";
+import { aiEventClient } from "@tanstack/ai-event-client";
+//#region src/activities/evaluate/index.ts
+/**
+* Evaluate Activity
+*
+* Asks typed questions about a shared state and returns values your code can
+* branch on. This is a self-contained module with implementation, types, and
+* JSDoc.
+*/
+/** The adapter kind this activity handles */
+var kind = "evaluate";
+/** Question key reserved for `result.meta`. */
+var RESERVED_QUESTION_KEY = "meta";
+function createId(prefix) {
+	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function isAbortError(error, signal) {
+	if (isAbortShapedError(error)) return true;
+	return error instanceof Error ? false : signal?.aborted === true;
+}
+function questionKeys(questions) {
+	return Object.keys(questions);
+}
+function assertQuestions(questions) {
+	const keys = questionKeys(questions);
+	if (keys.length === 0) throw new Error("decide() requires at least one question");
+	if (Object.hasOwn(questions, RESERVED_QUESTION_KEY)) throw new Error("decide() reserves the question key \"meta\"");
+	return keys;
+}
+function mapChoiceAnswer(wire, key) {
+	const probability = wire.probabilities[wire.choice];
+	if (typeof probability !== "number") throw new Error(`decide(): missing probability for choice "${wire.choice}" on "${key}"`);
+	return {
+		type: "choice",
+		value: wire.choice,
+		probability,
+		confidence: wire.confidence,
+		probabilities: wire.probabilities
+	};
+}
+function mapScoreAnswer(question, wire, key) {
+	const levels = question.criteria;
+	if (levels.length < 2) throw new Error(`decide(): score question "${key}" needs at least two levels`);
+	const lastIndex = levels.length - 1;
+	const rounded = Math.round(wire.score);
+	const nearestIndex = rounded < 0 ? 0 : rounded > lastIndex ? lastIndex : rounded;
+	const value = levels[nearestIndex];
+	if (value === void 0) throw new Error(`decide(): score question "${key}" has no level at index ${nearestIndex}`);
+	const probability = wire.probabilities[String(nearestIndex)];
+	if (typeof probability !== "number") throw new Error(`decide(): missing probability for score level ${nearestIndex} on "${key}"`);
+	return {
+		type: "score",
+		value,
+		probability,
+		confidence: wire.confidence,
+		score: wire.score,
+		legend: wire.legend,
+		probabilities: wire.probabilities
+	};
+}
+function mapBooleanAnswer(wire) {
+	return {
+		type: "boolean",
+		value: wire.noul >= .5,
+		probability: wire.noul
+	};
+}
+function mapWireAnswer(question, wire, key) {
+	switch (question.type) {
+		case "choice":
+			if (wire.type !== "choice") throw new Error(`decide(): expected choice answer for "${key}", got ${wire.type}`);
+			return mapChoiceAnswer(wire, key);
+		case "score":
+			if (wire.type !== "score") throw new Error(`decide(): expected score answer for "${key}", got ${wire.type}`);
+			return mapScoreAnswer(question, wire, key);
+		case "noul":
+			if (wire.type !== "noul") throw new Error(`decide(): expected noul answer for "${key}", got ${wire.type}`);
+			return mapBooleanAnswer(wire);
+	}
+}
+function mapAnswers(questions, wireAnswers) {
+	const answers = {};
+	const keys = Object.keys(questions);
+	for (const key of keys) {
+		const question = questions[key];
+		const wire = wireAnswers[String(key)];
+		if (question === void 0) throw new Error(`decide(): missing question "${String(key)}"`);
+		if (wire === void 0) throw new Error(`decide(): missing answer for question "${String(key)}"`);
+		answers[key] = mapWireAnswer(question, wire, String(key));
+	}
+	return answers;
+}
+function withMeta(answers, meta) {
+	return {
+		...answers,
+		meta
+	};
+}
+/**
+* Build a choice question. The model picks one key from `options`.
+*
+* Option keys become the union on `.value`. Use `null` when a key needs no
+* extra description. On the wire, `options` is sent as TypeSafe `criteria`.
+*
+* @param options.instructions What the model should decide.
+* @param options.options Map of option key to description, or `null`.
+*
+* @example
+* ```ts
+* const queue = choice({
+*   instructions: 'Which team should handle this ticket?',
+*   options: {
+*     billing: 'Payments, invoices, refunds',
+*     tech: 'Bugs, outages, integrations',
+*     sales: 'Pricing, upgrades, new accounts',
+*   },
+* })
+* ```
+*/
+function choice(options) {
+	return {
+		type: "choice",
+		instructions: options.instructions,
+		criteria: options.options
+	};
+}
+/**
+* Build a score question. The model rates `state` on ordered `levels`.
+*
+* You must pass at least two levels. `.value` is the nearest level label.
+* The raw fraction stays on `.score`. On the wire, `levels` is sent as
+* TypeSafe `criteria`.
+*
+* @param options.instructions What the model should rate.
+* @param options.levels Ordered labels, lowest first. At least two.
+*
+* @example
+* ```ts
+* const urgency = score({
+*   instructions: 'How urgent is this ticket?',
+*   levels: ['low', 'medium', 'high'],
+* })
+* ```
+*/
+function score(options) {
+	if (options.levels.length < 2) throw new Error("score() requires at least two levels");
+	return {
+		type: "score",
+		instructions: options.instructions,
+		criteria: options.levels
+	};
+}
+/**
+* Build a yes/no question.
+*
+* `.value` is `true` when P(true) is 0.5 or more. There is no `.confidence`.
+* On the wire, the type is TypeSafe `noul`.
+*
+* @param options.instructions The yes/no question to judge.
+* @param options.criteria Optional descriptions of yes and no.
+*
+* @example
+* ```ts
+* const refund = boolean({
+*   instructions: 'Is the customer asking for a refund?',
+* })
+* ```
+*/
+function boolean(options) {
+	if (options.criteria === void 0) return {
+		type: "noul",
+		instructions: options.instructions
+	};
+	return {
+		type: "noul",
+		instructions: options.instructions,
+		criteria: options.criteria
+	};
+}
+/**
+* Ask typed questions about `state` and get answers your code can branch on.
+*
+* You have state (a ticket, a record, a log) and you need typed answers, not
+* prose. Pass questions built with `choice`, `score`, and `boolean`. Then
+* branch on `result.queue.value` in ordinary TypeScript.
+*
+* The question key `meta` is reserved. Throws if `questions` is empty or uses
+* that key.
+*
+* @param options.adapter Evaluate adapter created with a model.
+* @param options.state Shared state every question judges.
+* @param options.questions Questions built with `choice`, `score`, `boolean`.
+* @param options.modelOptions Provider-specific options.
+* @param options.abortSignal Cancels the in-flight request.
+* @param options.middleware Observe-only generation middleware.
+* @param options.debug Debug logging option.
+*
+* @example Route a support ticket
+* ```ts
+* import { decide, choice, score, boolean } from '@tanstack/ai'
+* import { typesafeDecider } from '@tanstack/ai-typesafe'
+*
+* const result = await decide({
+*   adapter: typesafeDecider('jev-latest'),
+*   state: ticket,
+*   questions: {
+*     queue: choice({
+*       instructions: 'Which team should handle this ticket?',
+*       options: {
+*         billing: 'Payments, invoices, refunds',
+*         tech: 'Bugs, outages, integrations',
+*         sales: 'Pricing, upgrades, new accounts',
+*       },
+*     }),
+*     urgency: score({
+*       instructions: 'How urgent is this ticket?',
+*       levels: ['low', 'medium', 'high'],
+*     }),
+*     refund: boolean({
+*       instructions: 'Is the customer asking for a refund?',
+*     }),
+*   },
+* })
+*
+* result.queue.value
+* result.meta.model
+* result.meta.usage
+* ```
+*/
+async function decide(options) {
+	const { adapter, state, questions, modelOptions, abortSignal, middleware, debug } = options;
+	const model = adapter.model;
+	const keys = assertQuestions(questions);
+	const requestId = createId("evaluate");
+	const startTime = Date.now();
+	const logger = resolveDebugOption(debug);
+	const mwCtx = createGenerationContext({
+		requestId,
+		activity: "evaluate",
+		provider: adapter.name,
+		model,
+		modelOptions,
+		createId
+	});
+	await runGenerationStart(middleware, mwCtx);
+	aiEventClient.emit("evaluate:request:started", {
+		requestId,
+		provider: adapter.name,
+		model,
+		questionCount: keys.length,
+		timestamp: startTime
+	});
+	logger.request(`activity=evaluate provider=${adapter.name}`, {
+		provider: adapter.name,
+		model,
+		questionCount: keys.length
+	});
+	try {
+		const result = await adapter.evaluate({
+			model,
+			state,
+			questions,
+			modelOptions,
+			abortSignal,
+			logger
+		});
+		const answers = mapAnswers(questions, result.answers);
+		const duration = Date.now() - startTime;
+		aiEventClient.emit("evaluate:request:completed", {
+			requestId,
+			provider: adapter.name,
+			model: result.model,
+			questionCount: keys.length,
+			duration,
+			timestamp: Date.now()
+		});
+		aiEventClient.emit("evaluate:usage", {
+			requestId,
+			model: result.model,
+			usage: result.usage,
+			timestamp: Date.now()
+		});
+		logger.output(`activity=evaluate answers=${keys.length}`, { answerCount: keys.length });
+		await runGenerationUsage(middleware, mwCtx, result.usage);
+		await runGenerationFinish(middleware, mwCtx, {
+			duration,
+			usage: result.usage
+		});
+		return withMeta(answers, {
+			model: result.model,
+			usage: result.usage
+		});
+	} catch (error) {
+		const duration = Date.now() - startTime;
+		if (isAbortError(error, abortSignal)) await runGenerationAbort(middleware, mwCtx, {
+			reason: error instanceof Error ? error.message : void 0,
+			duration
+		});
+		else await runGenerationError(middleware, mwCtx, {
+			error,
+			duration
+		});
+		logger.errors("evaluate activity failed", {
+			error,
+			source: "evaluate"
+		});
+		throw error;
+	}
+}
+//#endregion
+export { boolean, choice, decide, kind, score };
+
+//# sourceMappingURL=index.js.map

package/dist/esm/activities/evaluate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/activities/evaluate/index.ts"],"sourcesContent":["/**\n * Evaluate Activity\n *\n * Asks typed questions about a shared state and returns values your code can\n * branch on. This is a self-contained module with implementation, types, and\n * JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport { isAbortShapedError } from '../error-payload'\nimport {\n  createGenerationContext,\n  runGenerationAbort,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware/run'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { TokenUsage } from '../../types'\nimport type { GenerationMiddleware } from '../middleware/types'\nimport type {\n  EvaluateAdapter,\n  EvaluateInstructions,\n  EvaluateState,\n  WireAnswer,\n  WireChoiceAnswer,\n  WireNoulAnswer,\n  WireQuestion,\n  WireScoreAnswer,\n  WireScoreQuestion,\n} from './adapter'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'evaluate' as const\n\n/** Question key reserved for `result.meta`. */\nconst RESERVED_QUESTION_KEY = 'meta' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/** Extract provider options from an EvaluateAdapter via ~types */\nexport type EvaluateProviderOptions<TAdapter> = TAdapter extends {\n  '~types': { providerOptions: infer P extends object }\n}\n  ? P\n  : object\n\n// ===========================\n// Unified answers\n// ===========================\n\n/**\n * Public choice answer. `.value` is the selected option key.\n */\nexport interface ChoiceAnswer<TValue extends string = string> {\n  type: 'choice'\n  value: TValue\n  /** P(selected option). */\n  probability: number\n  confidence: number\n  probabilities: Record<TValue, number>\n}\n\n/**\n * Public score answer. `.value` is the nearest level label.\n * `.score` is the raw TypeSafe fraction.\n */\nexport interface ScoreAnswer<TLevel extends string = string> {\n  type: 'score'\n  value: TLevel\n  /** P(nearest level). */\n  probability: number\n  confidence: number\n  score: number\n  legend: Record<string, string>\n  probabilities: Record<string, number>\n}\n\n/**\n * Public yes/no answer. `.value` is `true` when P(true) is 0.5 or more.\n * There is no `.confidence`.\n */\nexport interface BooleanAnswer {\n  type: 'boolean'\n  value: boolean\n  /** P(true), from the wire `noul` field. */\n  probability: number\n}\n\nexport interface EvaluateResultMeta {\n  /** Resolved model id from the provider. */\n  model: string\n  usage: TokenUsage\n}\n\n/**\n * Map a helper question (or wire question) to its public answer type.\n */\nexport type InferEvaluateAnswer<TQuestion> = TQuestion extends {\n  type: 'choice'\n  criteria: infer TCriteria\n}\n  ? TCriteria extends Record<string, string | null>\n    ? ChoiceAnswer<Extract<keyof TCriteria, string>>\n    : ChoiceAnswer\n  : TQuestion extends { type: 'score'; criteria: infer TLevels }\n    ? TLevels extends ReadonlyArray<string>\n      ? ScoreAnswer<TLevels[number] & string>\n      : ScoreAnswer\n    : TQuestion extends { type: 'noul' }\n      ? BooleanAnswer\n      : never\n\n/**\n * Result of `decide()`. Each question key is a top-level answer.\n * `meta` holds the resolved model id and usage.\n */\nexport type EvaluateResult<TQuestions extends Record<string, WireQuestion>> = {\n  [K in keyof TQuestions as K extends typeof RESERVED_QUESTION_KEY\n    ? never\n    : K]: InferEvaluateAnswer<TQuestions[K]>\n} & {\n  meta: EvaluateResultMeta\n}\n\n// ===========================\n// Activity Options Types\n// ===========================\n\n/**\n * Options for the evaluate activity. The model is extracted from the\n * adapter's model property.\n *\n * @template TAdapter - The evaluate adapter type\n * @template TQuestions - The questions object passed to `decide`\n */\nexport interface EvaluateActivityOptions<\n  TAdapter extends EvaluateAdapter<string, EvaluateProviderOptions<TAdapter>>,\n  TQuestions extends Record<string, WireQuestion>,\n> {\n  /** The evaluate adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** Shared state every question judges. A JSON array is one state, not a batch. */\n  state: EvaluateState\n  /**\n   * Questions built with `choice`, `score`, and `boolean`.\n   * The key `meta` is reserved.\n   */\n  questions: TQuestions\n  /** Provider-specific options */\n  modelOptions?: EvaluateProviderOptions<TAdapter>\n  /** Forwarded to the provider request for cancellation. */\n  abortSignal?: AbortSignal\n  /**\n   * Observe-only middleware notified on start, usage, success, abort, and\n   * error. Pass `otelMiddleware()` to emit OpenTelemetry spans, or implement\n   * the `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n}\n\n// ===========================\n// Helper Functions\n// ===========================\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\nfunction isAbortError(error: unknown, signal?: AbortSignal): boolean {\n  // Prefer the error's own identity over the signal state. A genuine\n  // cancellation throws an abort-shaped error (DOM `AbortError`, the OpenRouter\n  // SDK's `RequestAbortedError`, ...). Classifying on `signal.aborted` alone\n  // would misroute a real failure to the abort hook whenever a shared signal\n  // happens to already be aborted, hiding it from `onError` observers.\n  if (isAbortShapedError(error)) return true\n  // Fall back to signal state only for non-Error throws we can't otherwise\n  // identify; a real Error with a non-abort name is never an abort.\n  return error instanceof Error ? false : signal?.aborted === true\n}\n\nfunction questionKeys(questions: Record<string, WireQuestion>) {\n  return Object.keys(questions)\n}\n\nfunction assertQuestions(questions: Record<string, WireQuestion>) {\n  const keys = questionKeys(questions)\n  if (keys.length === 0) {\n    throw new Error('decide() requires at least one question')\n  }\n  if (Object.hasOwn(questions, RESERVED_QUESTION_KEY)) {\n    throw new Error('decide() reserves the question key \"meta\"')\n  }\n  return keys\n}\n\nfunction mapChoiceAnswer(wire: WireChoiceAnswer, key: string) {\n  const probability = wire.probabilities[wire.choice]\n  if (typeof probability !== 'number') {\n    throw new Error(\n      `decide(): missing probability for choice \"${wire.choice}\" on \"${key}\"`,\n    )\n  }\n  return {\n    type: 'choice' as const,\n    value: wire.choice,\n    probability,\n    confidence: wire.confidence,\n    probabilities: wire.probabilities,\n  }\n}\n\nfunction mapScoreAnswer(\n  question: WireScoreQuestion,\n  wire: WireScoreAnswer,\n  key: string,\n) {\n  const levels = question.criteria\n  if (levels.length < 2) {\n    throw new Error(\n      `decide(): score question \"${key}\" needs at least two levels`,\n    )\n  }\n  const lastIndex = levels.length - 1\n  const rounded = Math.round(wire.score)\n  const nearestIndex =\n    rounded < 0 ? 0 : rounded > lastIndex ? lastIndex : rounded\n  const value = levels[nearestIndex]\n  if (value === undefined) {\n    throw new Error(\n      `decide(): score question \"${key}\" has no level at index ${nearestIndex}`,\n    )\n  }\n  const probability = wire.probabilities[String(nearestIndex)]\n  if (typeof probability !== 'number') {\n    throw new Error(\n      `decide(): missing probability for score level ${nearestIndex} on \"${key}\"`,\n    )\n  }\n  return {\n    type: 'score' as const,\n    value,\n    probability,\n    confidence: wire.confidence,\n    score: wire.score,\n    legend: wire.legend,\n    probabilities: wire.probabilities,\n  }\n}\n\nfunction mapBooleanAnswer(wire: WireNoulAnswer) {\n  return {\n    type: 'boolean' as const,\n    value: wire.noul >= 0.5,\n    probability: wire.noul,\n  }\n}\n\nfunction mapWireAnswer(question: WireQuestion, wire: WireAnswer, key: string) {\n  switch (question.type) {\n    case 'choice': {\n      if (wire.type !== 'choice') {\n        throw new Error(\n          `decide(): expected choice answer for \"${key}\", got ${wire.type}`,\n        )\n      }\n      return mapChoiceAnswer(wire, key)\n    }\n    case 'score': {\n      if (wire.type !== 'score') {\n        throw new Error(\n          `decide(): expected score answer for \"${key}\", got ${wire.type}`,\n        )\n      }\n      return mapScoreAnswer(question, wire, key)\n    }\n    case 'noul': {\n      if (wire.type !== 'noul') {\n        throw new Error(\n          `decide(): expected noul answer for \"${key}\", got ${wire.type}`,\n        )\n      }\n      return mapBooleanAnswer(wire)\n    }\n  }\n}\n\nfunction mapAnswers<TQuestions extends Record<string, WireQuestion>>(\n  questions: TQuestions,\n  wireAnswers: Record<string, WireAnswer>,\n) {\n  const answers = {} as {\n    [K in keyof TQuestions]: InferEvaluateAnswer<TQuestions[K]>\n  }\n  const keys = Object.keys(questions) as Array<keyof TQuestions>\n  for (const key of keys) {\n    const question = questions[key]\n    const wire = wireAnswers[String(key)]\n    if (question === undefined) {\n      throw new Error(`decide(): missing question \"${String(key)}\"`)\n    }\n    if (wire === undefined) {\n      throw new Error(`decide(): missing answer for question \"${String(key)}\"`)\n    }\n    answers[key] = mapWireAnswer(\n      question,\n      wire,\n      String(key),\n    ) as InferEvaluateAnswer<TQuestions[typeof key]>\n  }\n  return answers\n}\n\nfunction withMeta<TAnswers extends object>(\n  answers: TAnswers,\n  meta: EvaluateResultMeta,\n) {\n  return { ...answers, meta }\n}\n\n// ===========================\n// Question helpers\n// ===========================\n\n/**\n * Build a choice question. The model picks one key from `options`.\n *\n * Option keys become the union on `.value`. Use `null` when a key needs no\n * extra description. On the wire, `options` is sent as TypeSafe `criteria`.\n *\n * @param options.instructions What the model should decide.\n * @param options.options Map of option key to description, or `null`.\n *\n * @example\n * ```ts\n * const queue = choice({\n *   instructions: 'Which team should handle this ticket?',\n *   options: {\n *     billing: 'Payments, invoices, refunds',\n *     tech: 'Bugs, outages, integrations',\n *     sales: 'Pricing, upgrades, new accounts',\n *   },\n * })\n * ```\n */\nexport function choice<\n  const TOptions extends Record<string, string | null>,\n>(options: { instructions: EvaluateInstructions; options: TOptions }) {\n  return {\n    type: 'choice' as const,\n    instructions: options.instructions,\n    criteria: options.options,\n  }\n}\n\n/**\n * Build a score question. The model rates `state` on ordered `levels`.\n *\n * You must pass at least two levels. `.value` is the nearest level label.\n * The raw fraction stays on `.score`. On the wire, `levels` is sent as\n * TypeSafe `criteria`.\n *\n * @param options.instructions What the model should rate.\n * @param options.levels Ordered labels, lowest first. At least two.\n *\n * @example\n * ```ts\n * const urgency = score({\n *   instructions: 'How urgent is this ticket?',\n *   levels: ['low', 'medium', 'high'],\n * })\n * ```\n */\nexport function score<const TLevels extends ReadonlyArray<string>>(options: {\n  instructions: EvaluateInstructions\n  levels: TLevels\n}) {\n  if (options.levels.length < 2) {\n    throw new Error('score() requires at least two levels')\n  }\n  return {\n    type: 'score' as const,\n    instructions: options.instructions,\n    criteria: options.levels,\n  }\n}\n\n/**\n * Build a yes/no question.\n *\n * `.value` is `true` when P(true) is 0.5 or more. There is no `.confidence`.\n * On the wire, the type is TypeSafe `noul`.\n *\n * @param options.instructions The yes/no question to judge.\n * @param options.criteria Optional descriptions of yes and no.\n *\n * @example\n * ```ts\n * const refund = boolean({\n *   instructions: 'Is the customer asking for a refund?',\n * })\n * ```\n */\nexport function boolean(options: {\n  instructions: EvaluateInstructions\n  criteria?: {\n    true?: string\n    false?: string\n  }\n}) {\n  if (options.criteria === undefined) {\n    return {\n      type: 'noul' as const,\n      instructions: options.instructions,\n    }\n  }\n  return {\n    type: 'noul' as const,\n    instructions: options.instructions,\n    criteria: options.criteria,\n  }\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Ask typed questions about `state` and get answers your code can branch on.\n *\n * You have state (a ticket, a record, a log) and you need typed answers, not\n * prose. Pass questions built with `choice`, `score`, and `boolean`. Then\n * branch on `result.queue.value` in ordinary TypeScript.\n *\n * The question key `meta` is reserved. Throws if `questions` is empty or uses\n * that key.\n *\n * @param options.adapter Evaluate adapter created with a model.\n * @param options.state Shared state every question judges.\n * @param options.questions Questions built with `choice`, `score`, `boolean`.\n * @param options.modelOptions Provider-specific options.\n * @param options.abortSignal Cancels the in-flight request.\n * @param options.middleware Observe-only generation middleware.\n * @param options.debug Debug logging option.\n *\n * @example Route a support ticket\n * ```ts\n * import { decide, choice, score, boolean } from '@tanstack/ai'\n * import { typesafeDecider } from '@tanstack/ai-typesafe'\n *\n * const result = await decide({\n *   adapter: typesafeDecider('jev-latest'),\n *   state: ticket,\n *   questions: {\n *     queue: choice({\n *       instructions: 'Which team should handle this ticket?',\n *       options: {\n *         billing: 'Payments, invoices, refunds',\n *         tech: 'Bugs, outages, integrations',\n *         sales: 'Pricing, upgrades, new accounts',\n *       },\n *     }),\n *     urgency: score({\n *       instructions: 'How urgent is this ticket?',\n *       levels: ['low', 'medium', 'high'],\n *     }),\n *     refund: boolean({\n *       instructions: 'Is the customer asking for a refund?',\n *     }),\n *   },\n * })\n *\n * result.queue.value\n * result.meta.model\n * result.meta.usage\n * ```\n */\nexport async function decide<\n  TAdapter extends EvaluateAdapter<string, EvaluateProviderOptions<TAdapter>>,\n  TQuestions extends Record<string, WireQuestion>,\n>(options: EvaluateActivityOptions<TAdapter, TQuestions>) {\n  const {\n    adapter,\n    state,\n    questions,\n    modelOptions,\n    abortSignal,\n    middleware,\n    debug,\n  } = options\n  const model = adapter.model\n  const keys = assertQuestions(questions)\n  const requestId = createId('evaluate')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(debug)\n\n  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'evaluate',\n    provider: adapter.name,\n    model,\n    modelOptions,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  aiEventClient.emit('evaluate:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    questionCount: keys.length,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=evaluate provider=${adapter.name}`, {\n    provider: adapter.name,\n    model,\n    questionCount: keys.length,\n  })\n\n  try {\n    const result = await adapter.evaluate({\n      model,\n      state,\n      questions,\n      modelOptions,\n      abortSignal,\n      logger,\n    })\n\n    const answers = mapAnswers(questions, result.answers)\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('evaluate:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model: result.model,\n      questionCount: keys.length,\n      duration,\n      timestamp: Date.now(),\n    })\n\n    aiEventClient.emit('evaluate:usage', {\n      requestId,\n      model: result.model,\n      usage: result.usage,\n      timestamp: Date.now(),\n    })\n\n    logger.output(`activity=evaluate answers=${keys.length}`, {\n      answerCount: keys.length,\n    })\n\n    await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration,\n      usage: result.usage,\n    })\n\n    return withMeta(answers, {\n      model: result.model,\n      usage: result.usage,\n    })\n  } catch (error) {\n    const duration = Date.now() - startTime\n    if (isAbortError(error, abortSignal)) {\n      await runGenerationAbort(middleware, mwCtx, {\n        reason: error instanceof Error ? error.message : undefined,\n        duration,\n      })\n    } else {\n      await runGenerationError(middleware, mwCtx, { error, duration })\n    }\n    logger.errors('evaluate activity failed', { error, source: 'evaluate' })\n    throw error\n  }\n}\n\n// Re-export adapter types\nexport type {\n  EvaluateAdapter,\n  EvaluateAdapterConfig,\n  AnyEvaluateAdapter,\n  EvaluateOptions,\n  EvaluateAdapterResult,\n  EvaluateState,\n  EvaluateInstructions,\n  EvaluateJsonValue,\n  WireQuestion,\n  WireAnswer,\n  WireChoiceQuestion,\n  WireScoreQuestion,\n  WireNoulQuestion,\n  WireChoiceAnswer,\n  WireScoreAnswer,\n  WireNoulAnswer,\n} from './adapter'\nexport { BaseEvaluateAdapter } from './adapter'\n"],"mappings":"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"}

package/dist/esm/activities/generateSpeech/adapter.d.ts

@@ -1,4 +1,20 @@
-import { TTSOptions, TTSResult } from '../../types.js';
+import { ListVoicesOptions, ListVoicesResult, TTSOptions, TTSResult } from '../../types.js';
+/**
+ * What a TTS adapter can do beyond a single voice reading a single string.
+ *
+ * Declared statically so `generateSpeech()` can reject an unsupported request
+ * before it reaches the provider, instead of surfacing a provider 422.
+ */
+export interface TTSCapabilities {
+    /**
+     * Maximum number of distinct voices accepted across `turns`
+     * (ElevenLabs 10, Gemini 2). Omit it when the adapter has no dialogue
+     * endpoint — then `turns` is rejected outright.
+     */
+    maxSpeakers?: number;
+    /** Set when the adapter can honour `timestamps: true`. */
+    timestamps?: boolean;
+}
 /**
  * Configuration for TTS adapter instances
  */
@@ -26,6 +42,11 @@ export interface TTSAdapter<TModel extends string = string, TProviderOptions ext
     readonly name: string;
     /** The model this adapter is configured for */
     readonly model: TModel;
+    /**
+     * Optional static capability declaration. Absent means "single voice, no
+     * timestamps" — the contract every adapter had before dialogue existed.
+     */
+    readonly capabilities?: TTSCapabilities;
     /**
      * @internal Type-only properties for inference. Not assigned at runtime.
      */
@@ -36,6 +57,17 @@ export interface TTSAdapter<TModel extends string = string, TProviderOptions ext
      * Generate speech from text
      */
     generateSpeech: (options: TTSOptions<TProviderOptions>) => Promise<TTSResult>;
+    /**
+     * List the voices this account can use.
+     *
+     * Optional, because only some providers have a catalog worth querying at
+     * runtime. A provider whose voices are a fixed list known at build time
+     * publishes that list from its own package instead (`GeminiTTSVoices`, or
+     * the `OpenAITTSVoice` union), which is strictly better than a network
+     * call. Implement this only when the catalog is per-account and can change,
+     * which is the case wherever `generateVoice()` can add to it.
+     */
+    listVoices?: (options?: ListVoicesOptions) => Promise<ListVoicesResult>;
 }
 /**
  * A TTSAdapter with any/unknown type parameters.
@@ -52,11 +84,17 @@ export declare abstract class BaseTTSAdapter<TModel extends string = string, TPr
     readonly kind: "tts";
     abstract readonly name: string;
     readonly model: TModel;
+    readonly capabilities?: TTSCapabilities;
     '~types': {
         providerOptions: TProviderOptions;
     };
     protected config: TTSAdapterConfig;
     constructor(model: TModel, config?: TTSAdapterConfig);
     abstract generateSpeech(options: TTSOptions<TProviderOptions>): Promise<TTSResult>;
+    /**
+     * Not abstract: a provider with a fixed voice list has nothing to query and
+     * should not be forced to write a stub.
+     */
+    listVoices?(options?: ListVoicesOptions): Promise<ListVoicesResult>;
     protected generateId(): string;
 }