Structured Outputs API Reference

/**
 * Create a tool-based structured output strategy
 * @param schema - Zod schema for the structured output
 * @param options - Optional configuration
 * @returns Tool strategy instance
 */
function toolStrategy<T>(
  schema: ZodType<T>,
  options?: ToolStrategyOptions
): ToolStrategy<T>;

/**
 * Create a provider-native structured output strategy
 * @param schema - Zod schema for the structured output
 * @returns Provider strategy instance
 */
function providerStrategy<T>(schema: ZodType<T>): ProviderStrategy<T>;

interface ToolStrategyOptions {
  /**
   * Tool name for the structured output function
   */
  name?: string;

  /**
   * Whether to require the tool to be called
   */
  strict?: boolean;
}

/**
 * Structured output strategy using function calling
 */
class ToolStrategy<T> {
  schema: ZodType<T> | Record<string, unknown>;
  options?: ToolStrategyOptions;

  constructor(schema: ZodType<T>, options?: ToolStrategyOptions);

  /**
   * Create from Zod schema
   */
  static fromSchema<S extends ZodType>(
    schema: S,
    outputOptions?: ToolStrategyOptions
  ): ToolStrategy<z.infer<S>>;

  /**
   * Create from JSON schema
   */
  static fromSchema(
    schema: Record<string, unknown>,
    outputOptions?: ToolStrategyOptions
  ): ToolStrategy<any>;

  /**
   * Parse tool arguments to extract structured output
   */
  parse(toolArgs: any): T;

  /**
   * Get tool name
   */
  get name(): string;

  /**
   * Get tool definition
   */
  get tool(): ToolDefinition;
}

/**
 * Structured output strategy using native JSON schema support
 */
class ProviderStrategy<T> {
  schema: ZodType<T> | Record<string, unknown>;
  strict?: boolean;

  constructor(schema: ZodType<T>);

  /**
   * Create from Zod schema
   */
  static fromSchema<T>(schema: ZodType<T>, strict?: boolean): ProviderStrategy<T>;

  /**
   * Create from JSON schema
   */
  static fromSchema(schema: Record<string, unknown>, strict?: boolean): ProviderStrategy<any>;

  /**
   * Parse AI message to extract structured output
   */
  parse(response: AIMessage): T;
}

/**
 * Response format union type
 */
type ResponseFormat =
  | ZodType<any> // Single Zod schema
  | ZodType<any>[] // Array of Zod schemas (union type)
  | JsonSchemaFormat // Single JSON schema
  | JsonSchemaFormat[] // Array of JSON schemas
  | ToolStrategy<any> // Tool-based strategy
  | ProviderStrategy<any> // Provider-native strategy
  | TypedToolStrategy<any>; // Typed tool strategy array

/**
 * JSON Schema format
 */
interface JsonSchemaFormat {
  /**
   * Schema name
   */
  name: string;

  /**
   * Whether to use strict mode (when supported by provider)
   */
  strict?: boolean;

  /**
   * JSON Schema object
   */
  schema: Record<string, any>;
}

/**
 * Typed tool strategy (for union types)
 */
type TypedToolStrategy<T> = ToolStrategy<T>[];

/**
 * Marker type for when no response format is set
 */
type ResponseFormatUndefined = undefined;

/**
 * Error type for tool strategy errors
 */
type ToolStrategyError =
  | "multiple_outputs"
  | "no_output"
  | "parsing_error";

/**
 * Tool definition interface
 */
interface ToolDefinition {
  type: "function";
  function: {
    name: string;
    description?: string;
    parameters: Record<string, any>;
  };
}

/**
 * Transform user-provided response format into internal format
 * @param responseFormat - User response format specification
 * @returns Normalized response format
 * @internal
 */
function transformResponseFormat(responseFormat: ResponseFormat): any;

/**
 * Check if model supports native JSON schema output
 * @param model - Chat model instance
 * @returns True if model supports JSON schema output
 */
function hasSupportForJsonSchemaOutput(model: ChatModel): boolean;

/**
 * Thrown when structured output parsing fails
 */
class StructuredOutputParsingError extends Error {
  name: "StructuredOutputParsingError";
  message: string;
  cause?: Error;
  rawOutput?: string;
}

/**
 * Thrown when multiple structured outputs are returned but only one was expected
 */
class MultipleStructuredOutputsError extends Error {
  name: "MultipleStructuredOutputsError";
  message: "Multiple structured outputs returned when one was expected";
  outputs: any[];
}