ai/src/prompt/call-settings.ts

AI SDK by Vercel - The AI Toolkit for TypeScript and JavaScript

/**
Timeout configuration for API calls. Can be specified as:
- A number representing milliseconds
- An object with `totalMs` property for the total timeout in milliseconds
- An object with `stepMs` property for the timeout of each step in milliseconds
- An object with `chunkMs` property for the timeout between stream chunks (streaming only)
 */
export type TimeoutConfiguration =
  | number
  | { totalMs?: number; stepMs?: number; chunkMs?: number };

/**
Extracts the total timeout value in milliseconds from a TimeoutConfiguration.

@param timeout - The timeout configuration.
@returns The total timeout in milliseconds, or undefined if no timeout is configured.
 */
export function getTotalTimeoutMs(
  timeout: TimeoutConfiguration | undefined,
): number | undefined {
  if (timeout == null) {
    return undefined;
  }
  if (typeof timeout === 'number') {
    return timeout;
  }
  return timeout.totalMs;
}

/**
Extracts the step timeout value in milliseconds from a TimeoutConfiguration.

@param timeout - The timeout configuration.
@returns The step timeout in milliseconds, or undefined if no step timeout is configured.
 */
export function getStepTimeoutMs(
  timeout: TimeoutConfiguration | undefined,
): number | undefined {
  if (timeout == null || typeof timeout === 'number') {
    return undefined;
  }
  return timeout.stepMs;
}

/**
Extracts the chunk timeout value in milliseconds from a TimeoutConfiguration.
This timeout is for streaming only - it aborts if no new chunk is received within the specified duration.

@param timeout - The timeout configuration.
@returns The chunk timeout in milliseconds, or undefined if no chunk timeout is configured.
 */
export function getChunkTimeoutMs(
  timeout: TimeoutConfiguration | undefined,
): number | undefined {
  if (timeout == null || typeof timeout === 'number') {
    return undefined;
  }
  return timeout.chunkMs;
}

export type CallSettings = {
  /**
Maximum number of tokens to generate.
   */
  maxOutputTokens?: number;

  /**
Temperature setting. The range depends on the provider and model.

It is recommended to set either `temperature` or `topP`, but not both.
   */
  temperature?: number;

  /**
Nucleus sampling. This is a number between 0 and 1.

E.g. 0.1 would mean that only tokens with the top 10% probability mass
are considered.

It is recommended to set either `temperature` or `topP`, but not both.
   */
  topP?: number;

  /**
Only sample from the top K options for each subsequent token.

Used to remove "long tail" low probability responses.
Recommended for advanced use cases only. You usually only need to use temperature.
   */
  topK?: number;

  /**
Presence penalty setting. It affects the likelihood of the model to
repeat information that is already in the prompt.

The presence penalty is a number between -1 (increase repetition)
and 1 (maximum penalty, decrease repetition). 0 means no penalty.
   */
  presencePenalty?: number;

  /**
Frequency penalty setting. It affects the likelihood of the model
to repeatedly use the same words or phrases.

The frequency penalty is a number between -1 (increase repetition)
and 1 (maximum penalty, decrease repetition). 0 means no penalty.
   */
  frequencyPenalty?: number;

  /**
Stop sequences.
If set, the model will stop generating text when one of the stop sequences is generated.
Providers may have limits on the number of stop sequences.
   */
  stopSequences?: string[];

  /**
The seed (integer) to use for random sampling. If set and supported
by the model, calls will generate deterministic results.
   */
  seed?: number;

  /**
Maximum number of retries. Set to 0 to disable retries.

@default 2
   */
  maxRetries?: number;

  /**
Abort signal.
   */
  abortSignal?: AbortSignal;

  /**
Timeout in milliseconds. The call will be aborted if it takes longer
than the specified timeout. Can be used alongside abortSignal.

Can be specified as a number (milliseconds) or as an object with `totalMs`.
   */
  timeout?: TimeoutConfiguration;

  /**
Additional HTTP headers to be sent with the request.
Only applicable for HTTP-based providers.
   */
  headers?: Record<string, string | undefined>;
};