ai/src/generate-object/structured-output-events.ts

AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.

import type { LanguageModelV4Prompt } from '@ai-sdk/provider';
import type { ModelMessage, ProviderOptions } from '@ai-sdk/provider-utils';
import type { Instructions } from '../prompt';
import type {
  CallWarning,
  FinishReason,
  LanguageModelRequestMetadata,
  LanguageModelResponseMetadata,
  ProviderMetadata,
} from '../types';
import type { LanguageModelUsage } from '../types/usage';

/**
 * Event passed to the `onStart` callback of
 * `generateObject` and `streamObject`.
 *
 * Called when the operation begins, before any LLM call.
 *
 * @deprecated
 */
export interface GenerateObjectStartEvent {
  /** Unique identifier for this generation call, used to correlate events. */
  readonly callId: string;

  /** Identifies the operation type (e.g. `'ai.generateObject'` or `'ai.streamObject'`). */
  readonly operationId: string;

  /** The provider identifier (e.g., 'openai', 'anthropic'). */
  readonly provider: string;

  /** The specific model identifier (e.g., 'gpt-4o'). */
  readonly modelId: string;

  /** The system message(s) provided to the model. */
  readonly system: Instructions | undefined;

  /** The prompt string or array of messages if using the prompt option. */
  readonly prompt: string | Array<ModelMessage> | undefined;

  /** The messages array if using the messages option. */
  readonly messages: Array<ModelMessage> | undefined;

  /** Maximum number of tokens to generate. */
  readonly maxOutputTokens: number | undefined;
  /** Sampling temperature for generation. */
  readonly temperature: number | undefined;
  /** Top-p (nucleus) sampling parameter. */
  readonly topP: number | undefined;
  /** Top-k sampling parameter. */
  readonly topK: number | undefined;
  /** Presence penalty for generation. */
  readonly presencePenalty: number | undefined;
  /** Frequency penalty for generation. */
  readonly frequencyPenalty: number | undefined;
  /** Random seed for reproducible generation. */
  readonly seed: number | undefined;
  /** Maximum number of retries for failed requests. */
  readonly maxRetries: number;

  /** Additional HTTP headers sent with the request. */
  readonly headers: Record<string, string | undefined> | undefined;

  /** Additional provider-specific options. */
  readonly providerOptions: ProviderOptions | undefined;

  /** The output strategy type. */
  readonly output: 'object' | 'array' | 'enum' | 'no-schema';

  /** The JSON Schema used for object generation, if any. */
  readonly schema: Record<string, unknown> | undefined;

  /** Optional name of the schema. */
  readonly schemaName: string | undefined;

  /** Optional description of the schema. */
  readonly schemaDescription: string | undefined;
}

/**
 * Event passed to the `onStepStart` callback of
 * `generateObject` and `streamObject`.
 *
 * Called when the model call (step) begins, before the provider is called.
 * For object generation, there is always exactly one step (step 0).
 *
 * @deprecated
 */
export interface GenerateObjectStepStartEvent {
  /** Unique identifier for this generation call, used to correlate events. */
  readonly callId: string;

  /** Zero-based index of the current step. Always `0` for object generation. */
  readonly stepNumber: 0;

  /** The provider identifier (e.g., 'openai', 'anthropic'). */
  readonly provider: string;

  /** The specific model identifier (e.g., 'gpt-4o'). */
  readonly modelId: string;

  /** Additional provider-specific options. */
  readonly providerOptions: ProviderOptions | undefined;

  /** Additional HTTP headers sent with the request. */
  readonly headers: Record<string, string | undefined> | undefined;

  /** The prompt messages in provider format (for telemetry). */
  readonly promptMessages?: LanguageModelV4Prompt;
}

/**
 * Event passed to the `onStepEnd` callback of
 * `generateObject` and `streamObject`.
 *
 * Called when the model call (step) completes, with the raw result
 * before JSON parsing and schema validation.
 *
 * @deprecated
 */
export interface GenerateObjectStepEndEvent {
  /** Unique identifier for this generation call, used to correlate events. */
  readonly callId: string;

  /** Zero-based index of the current step. Always `0` for object generation. */
  readonly stepNumber: 0;

  /** The provider identifier (e.g., 'openai', 'anthropic'). */
  readonly provider: string;

  /** The specific model identifier (e.g., 'gpt-4o'). */
  readonly modelId: string;

  /** The unified reason why the generation finished. */
  readonly finishReason: FinishReason;

  /** The token usage of the generated response. */
  readonly usage: LanguageModelUsage;

  /** The raw text output from the model (before JSON parsing). */
  readonly objectText: string;

  /** The reasoning generated by the model, if any. */
  readonly reasoning: string | undefined;

  /** Warnings from the model provider (e.g. unsupported settings). */
  readonly warnings: CallWarning[] | undefined;

  /** Additional request information. */
  readonly request: Omit<LanguageModelRequestMetadata, 'messages'>;

  /** Additional response information. */
  readonly response: Omit<LanguageModelResponseMetadata, 'messages'>;

  /** Additional provider-specific metadata. */
  readonly providerMetadata: ProviderMetadata | undefined;

  /** Milliseconds from the start of the stream to the first chunk (streaming only). */
  readonly msToFirstChunk: number | undefined;
}

/**
 * Event passed to the `onFinish` callback of
 * `generateObject` and `streamObject`.
 *
 * Called when the entire operation completes, including JSON parsing
 * and schema validation. For `streamObject`, the object may be undefined
 * if validation failed (the error is provided in that case).
 *
 * @deprecated
 */
export interface GenerateObjectEndEvent<RESULT> {
  /** Unique identifier for this generation call, used to correlate events. */
  readonly callId: string;

  /**
   * The generated object (typed according to the schema).
   * Always defined for `generateObject`. May be `undefined` for `streamObject`
   * when parsing or validation fails.
   */
  readonly object: RESULT | undefined;

  /**
   * Error from parsing or schema validation, if any.
   * Always `undefined` for `generateObject` (which throws instead).
   */
  readonly error: unknown | undefined;

  /** The reasoning generated by the model, if any. */
  readonly reasoning: string | undefined;

  /** The unified reason why the generation finished. */
  readonly finishReason: FinishReason;

  /** The token usage of the generated response. */
  readonly usage: LanguageModelUsage;

  /** Warnings from the model provider (e.g. unsupported settings). */
  readonly warnings: CallWarning[] | undefined;

  /** Additional request information. */
  readonly request: Omit<LanguageModelRequestMetadata, 'messages'>;

  /** Additional response information. */
  readonly response: Omit<LanguageModelResponseMetadata, 'messages'>;

  /** Additional provider-specific metadata. */
  readonly providerMetadata: ProviderMetadata | undefined;
}