ai 3.1.0-canary.0 → 3.1.0-canary.2

package/ai-model-specification/dist/index.d.ts

@@ -0,0 +1,539 @@
+import * as zod from 'zod';
+import { ZodSchema } from 'zod';
+
+declare class AI_InvalidArgumentError extends Error {
+    readonly parameter: string;
+    readonly value: unknown;
+    constructor({ parameter, value, message, }: {
+        parameter: string;
+        value: unknown;
+        message: string;
+    });
+    toJSON(): {
+        name: string;
+        message: string;
+        stack: string | undefined;
+        parameter: string;
+        value: unknown;
+    };
+}
+
+declare class ApiCallError extends Error {
+    readonly url: string;
+    readonly requestBodyValues: unknown;
+    readonly statusCode?: number;
+    readonly responseBody?: string;
+    readonly cause?: unknown;
+    readonly isRetryable: boolean;
+    readonly data?: unknown;
+    constructor({ message, url, requestBodyValues, statusCode, responseBody, cause, isRetryable, data, }: {
+        message: string;
+        url: string;
+        requestBodyValues: unknown;
+        statusCode?: number;
+        responseBody?: string;
+        cause?: unknown;
+        isRetryable?: boolean;
+        data?: unknown;
+    });
+    toJSON(): {
+        name: string;
+        message: string;
+        url: string;
+        requestBodyValues: unknown;
+        statusCode: number | undefined;
+        responseBody: string | undefined;
+        cause: unknown;
+        isRetryable: boolean;
+        data: unknown;
+    };
+}
+
+declare class JSONParseError extends Error {
+    readonly text: string;
+    readonly cause: unknown;
+    constructor({ text, cause }: {
+        text: string;
+        cause: unknown;
+    });
+    toJSON(): {
+        name: string;
+        message: string;
+        cause: unknown;
+        stack: string | undefined;
+        valueText: string;
+    };
+}
+
+declare class LoadAPIKeyError extends Error {
+    constructor({ message }: {
+        message: string;
+    });
+    toJSON(): {
+        name: string;
+        message: string;
+    };
+}
+
+declare class NoTextGeneratedError extends Error {
+    readonly cause: unknown;
+    constructor();
+    toJSON(): {
+        name: string;
+        cause: unknown;
+        message: string;
+        stack: string | undefined;
+    };
+}
+
+declare class TypeValidationError extends Error {
+    readonly value: unknown;
+    readonly cause: unknown;
+    constructor({ value, cause }: {
+        value: unknown;
+        cause: unknown;
+    });
+    toJSON(): {
+        name: string;
+        message: string;
+        cause: unknown;
+        stack: string | undefined;
+        value: unknown;
+    };
+}
+
+declare class UnsupportedFunctionalityError extends Error {
+    readonly functionality: string;
+    readonly provider: string;
+    constructor({ provider, functionality, }: {
+        provider: string;
+        functionality: string;
+    });
+    toJSON(): {
+        name: string;
+        message: string;
+        stack: string | undefined;
+        provider: string;
+        functionality: string;
+    };
+}
+
+type JsonSchema = Record<string, unknown>;
+
+type LanguageModelV1CallSettings = {
+    /**
+     * Maximum number of tokens to generate.
+     */
+    maxTokens?: number;
+    /**
+     * Temperature setting. This is a number between 0 (almost no randomness) and
+     * 1 (very random).
+     *
+     * Different LLM providers have different temperature
+     * scales, so they'd need to map it (without mapping, the same temperature has
+     * different effects on different models). The provider can also chose to map
+     * this to topP, potentially even using a custom setting on their model.
+     *
+     * Note: This is an example of a setting that requires a clear specification of
+     * the semantics.
+     */
+    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;
+    /**
+     * 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;
+    /**
+     * The seed (integer) to use for random sampling. If set and supported
+     * by the model, calls will generate deterministic results.
+     */
+    seed?: number;
+};
+
+/**
+ * A tool has a name, a description, and a set of parameters.
+ *
+ * Note: this is **not** the user-facing tool definition. The AI SDK methods will
+ * map the user-facing tool definitions to this format.
+ */
+type LanguageModelV1FunctionTool = {
+    /**
+     * The type of the tool. Only functions for now, but this gives us room to
+     * add more specific tool types in the future and use a discriminated union.
+     */
+    type: 'function';
+    /**
+     * The name of the tool. Unique within this model call.
+     */
+    name: string;
+    description?: string;
+    parameters: JsonSchema;
+};
+
+/**
+ * A prompt is a list of messages.
+ *
+ * Note: Not all models and prompt formats support multi-modal inputs and
+ * tool calls. The validation happens at runtime.
+ *
+ * Note: This is not a user-facing prompt. The AI SDK methods will map the
+ * user-facing prompt types such as chat or instruction prompts to this format.
+ */
+type LanguageModelV1Prompt = Array<LanguageModelV1Message>;
+type LanguageModelV1Message = {
+    role: 'system';
+    content: string;
+} | {
+    role: 'user';
+    content: Array<LanguageModelV1TextPart | LanguageModelV1ImagePart>;
+} | {
+    role: 'assistant';
+    content: Array<LanguageModelV1TextPart | LanguageModelV1ToolCallPart>;
+} | {
+    role: 'tool';
+    content: Array<LanguageModelV1ToolResultPart>;
+};
+interface LanguageModelV1TextPart {
+    type: 'text';
+    /**
+     * The text content.
+     */
+    text: string;
+}
+interface LanguageModelV1ImagePart {
+    type: 'image';
+    /**
+     * Image data as a Uint8Array.
+     */
+    image: Uint8Array;
+    /**
+     * Optional mime type of the image.
+     */
+    mimeType?: string;
+}
+interface LanguageModelV1ToolCallPart {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
+interface LanguageModelV1ToolResultPart {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+}
+
+type LanguageModelV1CallOptions = LanguageModelV1CallSettings & {
+    /**
+     * Whether the user provided the input as messages or as
+     * a prompt. This can help guide non-chat models in the
+     * expansion, bc different expansions can be needed for
+     * chat/non-chat use cases.
+     */
+    inputFormat: 'messages' | 'prompt';
+    /**
+     * The mode affects the behavior of the language model. It is required to
+     * support provider-independent streaming and generation of structured objects.
+     * The model can take this information and e.g. configure json mode, the correct
+     * low level grammar, etc. It can also be used to optimize the efficiency of the
+     * streaming, e.g. tool-delta stream parts are only needed in the
+     * object-tool mode.
+     */
+    mode: {
+        type: 'regular';
+        tools?: Array<LanguageModelV1FunctionTool>;
+    } | {
+        type: 'object-json';
+    } | {
+        type: 'object-grammar';
+        schema: JsonSchema;
+    } | {
+        type: 'object-tool';
+        tool: LanguageModelV1FunctionTool;
+    };
+    /**
+     * A language mode prompt is a standardized prompt type.
+     *
+     * Note: This is **not** the user-facing prompt. The AI SDK methods will map the
+     * user-facing prompt types such as chat or instruction prompts to this format.
+     * That approach allows us to evolve the user  facing prompts without breaking
+     * the language model interface.
+     */
+    prompt: LanguageModelV1Prompt;
+};
+
+/**
+ * Warning from the model provider for this call. The call will proceed, but e.g.
+ * some settings might not be supported, which can lead to suboptimal results.
+ */
+type LanguageModelV1CallWarning = {
+    type: 'unsupported-setting';
+    setting: keyof LanguageModelV1CallSettings;
+} | {
+    type: 'other';
+    message: string;
+};
+
+type LanguageModelV1FinishReason = 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other';
+
+type LanguageModelV1FunctionToolCall = {
+    toolCallType: 'function';
+    toolCallId: string;
+    toolName: string;
+    /**
+     * Stringified JSON object with the tool call arguments. Must match the
+     * parameters schema of the tool.
+     */
+    args: string;
+};
+
+type LanguageModelV1 = {
+    /**
+     * The language model must specify which language model interface
+     * version it implements. This will allow us to evolve the language
+     * model interface and retain backwards compatibility. The different
+     * implementation versions can be handled as a discriminated union
+     * on our side.
+     */
+    readonly specificationVersion: 'v1';
+    /**
+     * Name of the provider for logging purposes.
+     */
+    readonly provider: string;
+    /**
+     * Provider-specific model ID for logging purposes.
+     */
+    readonly modelId: string;
+    /**
+     * Default object generation mode that should be used with this model when
+     * no mode is specified. Should be the mode with the best results for this
+     * model. `undefined` can be returned if object generation is not supported.
+     *
+     * This is needed to generate the best objects possible w/o requiring the
+     * user to explicitly specify the object generation mode.
+     */
+    readonly defaultObjectGenerationMode: 'json' | 'tool' | 'grammar' | undefined;
+    /**
+     * Generates a language model output (non-streaming).
+     *
+     * Naming: "do" prefix to prevent accidental direct usage of the method
+     * by the user.
+     */
+    doGenerate(options: LanguageModelV1CallOptions): PromiseLike<{
+        /**
+         * Text that the model has generated. Can be undefined if the model
+         * has only generated tool calls.
+         */
+        text?: string;
+        /**
+         * Tool calls that the model has generated. Can be undefined if the
+         * model has only generated text.
+         */
+        toolCalls?: Array<LanguageModelV1FunctionToolCall>;
+        warnings?: LanguageModelV1CallWarning[];
+    }>;
+    /**
+     * Generates a language model output (streaming).
+     *
+     * Naming: "do" prefix to prevent accidental direct usage of the method
+     * by the user.
+     *
+     * @return A stream of higher-level language model output parts.
+     */
+    doStream(options: LanguageModelV1CallOptions): PromiseLike<{
+        stream: ReadableStream<LanguageModelV1StreamPart>;
+        warnings?: LanguageModelV1CallWarning[];
+    }>;
+};
+type LanguageModelV1StreamPart = {
+    type: 'text-delta';
+    textDelta: string;
+} | ({
+    type: 'tool-call';
+} & LanguageModelV1FunctionToolCall) | {
+    type: 'tool-call-delta';
+    toolCallId: string;
+    toolName: string;
+    argsTextDelta: string;
+} | {
+    type: 'finish-metadata';
+    finishReason: LanguageModelV1FinishReason;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+} | {
+    type: 'error';
+    error: unknown;
+};
+
+declare function loadApiKey({ apiKey, environmentVariableName, apiKeyParameterName, description, }: {
+    apiKey: string | undefined;
+    environmentVariableName: string;
+    apiKeyParameterName?: string;
+    description: string;
+}): string;
+
+/**
+ * Parses a JSON string into an unknown object.
+ *
+ * @param text - The JSON string to parse.
+ * @returns {unknown} - The parsed JSON object.
+ */
+declare function parseJSON({ text }: {
+    text: string;
+}): unknown;
+/**
+ * Parses a JSON string into a strongly-typed object using the provided schema.
+ *
+ * @template T - The type of the object to parse the JSON into.
+ * @param {string} text - The JSON string to parse.
+ * @param {Schema<T>} schema - The schema to use for parsing the JSON.
+ * @returns {T} - The parsed object.
+ */
+declare function parseJSON<T>({ text, schema, }: {
+    text: string;
+    schema: ZodSchema<T>;
+}): T;
+/**
+ * Safely parses a JSON string and returns the result as an object of type `unknown`.
+ *
+ * @param text - The JSON string to parse.
+ * @returns {object} Either an object with `success: true` and the parsed data, or an object with `success: false` and the error that occurred.
+ */
+declare function safeParseJSON({ text, }: {
+    text: string;
+}): {
+    success: true;
+    value: unknown;
+} | {
+    success: false;
+    error: JSONParseError | TypeValidationError;
+};
+/**
+ * Safely parses a JSON string into a strongly-typed object, using a provided schema to validate the object.
+ *
+ * @template T - The type of the object to parse the JSON into.
+ * @param {string} text - The JSON string to parse.
+ * @param {Schema<T>} schema - The schema to use for parsing the JSON.
+ * @returns An object with either a `success` flag and the parsed and typed data, or a `success` flag and an error object.
+ */
+declare function safeParseJSON<T>({ text, schema, }: {
+    text: string;
+    schema: ZodSchema<T>;
+}): {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: JSONParseError | TypeValidationError;
+};
+declare function isParseableJson(input: string): boolean;
+
+type ParsedChunk<T> = {
+    type: 'value';
+    value: T;
+} | {
+    type: 'error';
+    error: unknown;
+};
+
+type ResponseHandler<RETURN_TYPE> = (options: {
+    url: string;
+    requestBodyValues: unknown;
+    response: Response;
+}) => PromiseLike<RETURN_TYPE>;
+declare const createJsonErrorResponseHandler: <T>({ errorSchema, errorToMessage, isRetryable, }: {
+    errorSchema: ZodSchema<T, zod.ZodTypeDef, T>;
+    errorToMessage: (error: T) => string;
+    isRetryable?: ((response: Response, error?: T | undefined) => boolean) | undefined;
+}) => ResponseHandler<ApiCallError>;
+declare const createEventSourceResponseHandler: <T>(chunkSchema: ZodSchema<T, zod.ZodTypeDef, T>) => ResponseHandler<ReadableStream<ParsedChunk<T>>>;
+declare const createJsonResponseHandler: <T>(responseSchema: ZodSchema<T, zod.ZodTypeDef, T>) => ResponseHandler<T>;
+
+declare const postJsonToApi: <T>({ url, headers, body, failedResponseHandler, successfulResponseHandler, abortSignal, }: {
+    url: string;
+    headers?: Record<string, string> | undefined;
+    body: unknown;
+    failedResponseHandler: ResponseHandler<ApiCallError>;
+    successfulResponseHandler: ResponseHandler<T>;
+    abortSignal?: AbortSignal | undefined;
+}) => Promise<T>;
+declare const postToApi: <T>({ url, headers, body, successfulResponseHandler, failedResponseHandler, abortSignal, }: {
+    url: string;
+    headers?: Record<string, string> | undefined;
+    body: {
+        content: string | FormData | Uint8Array;
+        values: unknown;
+    };
+    failedResponseHandler: ResponseHandler<Error>;
+    successfulResponseHandler: ResponseHandler<T>;
+    abortSignal?: AbortSignal | undefined;
+}) => Promise<T>;
+
+declare function scale({ inputMin, inputMax, outputMin, outputMax, value, }: {
+    inputMin?: number;
+    inputMax?: number;
+    outputMin: number;
+    outputMax: number;
+    value: number | undefined;
+}): number | undefined;
+
+declare function convertBase64ToUint8Array(base64String: string): Uint8Array;
+declare function convertUint8ArrayToBase64(array: Uint8Array): string;
+
+/**
+ * Validates the types of an unknown object using a schema and
+ * return a strongly-typed object.
+ *
+ * @template T - The type of the object to validate.
+ * @param {string} options.value - The object to validate.
+ * @param {Schema<T>} options.schema - The schema to use for validating the JSON.
+ * @returns {T} - The typed object.
+ */
+declare function validateTypes<T>({ value, schema, }: {
+    value: unknown;
+    schema: ZodSchema<T>;
+}): T;
+/**
+ * Safely validates the types of an unknown object using a schema and
+ * return a strongly-typed object.
+ *
+ * @template T - The type of the object to validate.
+ * @param {string} options.value - The JSON object to validate.
+ * @param {Schema<T>} options.schema - The schema to use for validating the JSON.
+ * @returns An object with either a `success` flag and the parsed and typed data, or a `success` flag and an error object.
+ */
+declare function safeValidateTypes<T>({ value, schema, }: {
+    value: unknown;
+    schema: ZodSchema<T>;
+}): {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: TypeValidationError;
+};
+
+export { AI_InvalidArgumentError, ApiCallError, JSONParseError, LanguageModelV1, LanguageModelV1CallWarning, LanguageModelV1FunctionTool, LanguageModelV1FunctionToolCall, LanguageModelV1ImagePart, LanguageModelV1Message, LanguageModelV1Prompt, LanguageModelV1StreamPart, LanguageModelV1TextPart, LanguageModelV1ToolCallPart, LanguageModelV1ToolResultPart, LoadAPIKeyError, NoTextGeneratedError, ParsedChunk, ResponseHandler, TypeValidationError, UnsupportedFunctionalityError, convertBase64ToUint8Array, convertUint8ArrayToBase64, createEventSourceResponseHandler, createJsonErrorResponseHandler, createJsonResponseHandler, isParseableJson, loadApiKey, parseJSON, postJsonToApi, postToApi, safeParseJSON, safeValidateTypes, scale, validateTypes };