@ai-sdk/provider-utils 4.0.0-beta.41 → 4.0.0-beta.43

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @ai-sdk/provider-utils
 
+## 4.0.0-beta.43
+
+### Patch Changes
+
+- dce03c4: feat: tool input examples
+- Updated dependencies [dce03c4]
+  - @ai-sdk/provider@3.0.0-beta.24
+
+## 4.0.0-beta.42
+
+### Patch Changes
+
+- 3ed5519: chore: rename ToolCallOptions to ToolExecutionOptions
+
 ## 4.0.0-beta.41
 
 ### Patch Changes

package/dist/index.d.mts

@@ -863,7 +863,7 @@ type ModelMessage = SystemModelMessage | UserModelMessage | AssistantModelMessag
 /**
  * Additional options that are sent into each tool call.
  */
-interface ToolCallOptions {
+interface ToolExecutionOptions {
     /**
      * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
@@ -904,7 +904,7 @@ type ToolNeedsApprovalFunction<INPUT> = (input: INPUT, options: {
      */
     experimental_context?: unknown;
 }) => boolean | PromiseLike<boolean>;
-type ToolExecuteFunction<INPUT, OUTPUT> = (input: INPUT, options: ToolCallOptions) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
+type ToolExecuteFunction<INPUT, OUTPUT> = (input: INPUT, options: ToolExecutionOptions) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
 type NeverOptional<N, T> = 0 extends 1 & N ? Partial<T> : [N] extends [never] ? Partial<Record<keyof T, undefined>> : T;
 type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
     /**
@@ -944,13 +944,22 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      */
     providerOptions?: ProviderOptions;
     /**
-  The schema of the input that the tool expects. The language model will use this to generate the input.
-  It is also used to validate the output of the language model.
-  Use descriptions to make the input understandable for the language model.
+     * The schema of the input that the tool expects.
+     * The language model will use this to generate the input.
+     * It is also used to validate the output of the language model.
+     *
+     * You can use descriptions on the schema properties to make the input understandable for the language model.
      */
     inputSchema: FlexibleSchema<INPUT>;
     /**
-  Whether the tool needs approval before it can be executed.
+     * An optional list of input examples that show the language
+     * model what the input should look like.
+     */
+    inputExamples?: Array<{
+        input: INPUT;
+    }>;
+    /**
+     * Whether the tool needs approval before it can be executed.
      */
     needsApproval?: boolean | ToolNeedsApprovalFunction<[INPUT] extends [never] ? unknown : INPUT>;
     /**
@@ -965,21 +974,21 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      * Optional function that is called when the argument streaming starts.
      * Only called when the tool is used in a streaming context.
      */
-    onInputStart?: (options: ToolCallOptions) => void | PromiseLike<void>;
+    onInputStart?: (options: ToolExecutionOptions) => void | PromiseLike<void>;
     /**
      * Optional function that is called when an argument streaming delta is available.
      * Only called when the tool is used in a streaming context.
      */
     onInputDelta?: (options: {
         inputTextDelta: string;
-    } & ToolCallOptions) => void | PromiseLike<void>;
+    } & ToolExecutionOptions) => void | PromiseLike<void>;
     /**
      * Optional function that is called when a tool call can be started,
      * even if the execute function is not provided.
      */
     onInputAvailable?: (options: {
         input: [INPUT] extends [never] ? unknown : INPUT;
-    } & ToolCallOptions) => void | PromiseLike<void>;
+    } & ToolExecutionOptions) => void | PromiseLike<void>;
 } & ToolOutputProperties<INPUT, OUTPUT> & {
     /**
 Optional conversion function that maps the tool result to an output that can be used by the language model.
@@ -1143,7 +1152,7 @@ declare function withoutTrailingSlash(url: string | undefined): string | undefin
 declare function executeTool<INPUT, OUTPUT>({ execute, input, options, }: {
     execute: ToolExecuteFunction<INPUT, OUTPUT>;
     input: INPUT;
-    options: ToolCallOptions;
+    options: ToolExecutionOptions;
 }): AsyncGenerator<{
     type: 'preliminary';
     output: OUTPUT;
@@ -1211,4 +1220,9 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-export { type AssistantContent, type AssistantModelMessage, type DataContent, DelayedPromise, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, tool, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+/**
+ * @deprecated Use ToolExecutionOptions instead.
+ */
+type ToolCallOptions = ToolExecutionOptions;
+
+export { type AssistantContent, type AssistantModelMessage, type DataContent, DelayedPromise, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, tool, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };

package/dist/index.d.ts

@@ -863,7 +863,7 @@ type ModelMessage = SystemModelMessage | UserModelMessage | AssistantModelMessag
 /**
  * Additional options that are sent into each tool call.
  */
-interface ToolCallOptions {
+interface ToolExecutionOptions {
     /**
      * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
@@ -904,7 +904,7 @@ type ToolNeedsApprovalFunction<INPUT> = (input: INPUT, options: {
      */
     experimental_context?: unknown;
 }) => boolean | PromiseLike<boolean>;
-type ToolExecuteFunction<INPUT, OUTPUT> = (input: INPUT, options: ToolCallOptions) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
+type ToolExecuteFunction<INPUT, OUTPUT> = (input: INPUT, options: ToolExecutionOptions) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
 type NeverOptional<N, T> = 0 extends 1 & N ? Partial<T> : [N] extends [never] ? Partial<Record<keyof T, undefined>> : T;
 type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
     /**
@@ -944,13 +944,22 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      */
     providerOptions?: ProviderOptions;
     /**
-  The schema of the input that the tool expects. The language model will use this to generate the input.
-  It is also used to validate the output of the language model.
-  Use descriptions to make the input understandable for the language model.
+     * The schema of the input that the tool expects.
+     * The language model will use this to generate the input.
+     * It is also used to validate the output of the language model.
+     *
+     * You can use descriptions on the schema properties to make the input understandable for the language model.
      */
     inputSchema: FlexibleSchema<INPUT>;
     /**
-  Whether the tool needs approval before it can be executed.
+     * An optional list of input examples that show the language
+     * model what the input should look like.
+     */
+    inputExamples?: Array<{
+        input: INPUT;
+    }>;
+    /**
+     * Whether the tool needs approval before it can be executed.
      */
     needsApproval?: boolean | ToolNeedsApprovalFunction<[INPUT] extends [never] ? unknown : INPUT>;
     /**
@@ -965,21 +974,21 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      * Optional function that is called when the argument streaming starts.
      * Only called when the tool is used in a streaming context.
      */
-    onInputStart?: (options: ToolCallOptions) => void | PromiseLike<void>;
+    onInputStart?: (options: ToolExecutionOptions) => void | PromiseLike<void>;
     /**
      * Optional function that is called when an argument streaming delta is available.
      * Only called when the tool is used in a streaming context.
      */
     onInputDelta?: (options: {
         inputTextDelta: string;
-    } & ToolCallOptions) => void | PromiseLike<void>;
+    } & ToolExecutionOptions) => void | PromiseLike<void>;
     /**
      * Optional function that is called when a tool call can be started,
      * even if the execute function is not provided.
      */
     onInputAvailable?: (options: {
         input: [INPUT] extends [never] ? unknown : INPUT;
-    } & ToolCallOptions) => void | PromiseLike<void>;
+    } & ToolExecutionOptions) => void | PromiseLike<void>;
 } & ToolOutputProperties<INPUT, OUTPUT> & {
     /**
 Optional conversion function that maps the tool result to an output that can be used by the language model.
@@ -1143,7 +1152,7 @@ declare function withoutTrailingSlash(url: string | undefined): string | undefin
 declare function executeTool<INPUT, OUTPUT>({ execute, input, options, }: {
     execute: ToolExecuteFunction<INPUT, OUTPUT>;
     input: INPUT;
-    options: ToolCallOptions;
+    options: ToolExecutionOptions;
 }): AsyncGenerator<{
     type: 'preliminary';
     output: OUTPUT;
@@ -1211,4 +1220,9 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-export { type AssistantContent, type AssistantModelMessage, type DataContent, DelayedPromise, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, tool, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+/**
+ * @deprecated Use ToolExecutionOptions instead.
+ */
+type ToolCallOptions = ToolExecutionOptions;
+
+export { type AssistantContent, type AssistantModelMessage, type DataContent, DelayedPromise, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, tool, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };

package/dist/index.js

@@ -378,7 +378,7 @@ function withUserAgentSuffix(headers, ...userAgentSuffixParts) {
 }
 
 // src/version.ts
-var VERSION = true ? "4.0.0-beta.41" : "0.0.0-test";
+var VERSION = true ? "4.0.0-beta.43" : "0.0.0-test";
 
 // src/get-from-api.ts
 var getOriginalFetch = () => globalThis.fetch;