ima2-gen 3.20.0 → 3.21.0

package/node_modules/ai/docs/07-reference/01-ai-sdk-core/13-generate-video.mdx

@@ -1,264 +0,0 @@
----
-title: experimental_generateVideo
-description: API Reference for experimental_generateVideo.
----
-
-# `experimental_generateVideo()`
-
-<Note>
-  Video generation is an experimental feature. The API may change in future
-  versions.
-</Note>
-
-Generates videos based on a given prompt using a video model.
-
-It is ideal for use cases where you need to generate videos programmatically,
-such as creating visual content, animations, or generating videos from images.
-
-```ts
-import { experimental_generateVideo as generateVideo } from 'ai';
-
-const { videos } = await generateVideo({
-  model: fal.video('luma-dream-machine/ray-2'),
-  prompt: 'A cat walking on a treadmill',
-  aspectRatio: '16:9',
-});
-
-console.log(videos);
-```
-
-## Import
-
-<Snippet
-  text={`import { experimental_generateVideo } from "ai"`}
-  prompt={false}
-/>
-
-## API Signature
-
-### Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: 'model',
-      type: 'VideoModelV3',
-      description: 'The video model to use.',
-    },
-    {
-      name: 'prompt',
-      type: 'string | GenerateVideoPrompt',
-      description: 'The input prompt to generate the video from.',
-      properties: [
-        {
-          type: 'GenerateVideoPrompt',
-          type: 'object',
-          description:
-            'A prompt object for video generation with optional input image',
-          parameters: [
-            {
-              name: 'image',
-              type: 'DataContent',
-              description:
-                'Input image for image-to-video generation. Can be a URL string, base64-encoded string, a `Uint8Array`, an `ArrayBuffer`, or a `Buffer`.',
-            },
-            {
-              name: 'text',
-              type: 'string',
-              description: 'The text prompt.',
-            },
-          ],
-        },
-      ],
-    },
-    {
-      name: 'n',
-      type: 'number',
-      isOptional: true,
-      description: 'Number of videos to generate. Default: 1.',
-    },
-    {
-      name: 'aspectRatio',
-      type: 'string',
-      isOptional: true,
-      description:
-        'Aspect ratio of the videos to generate. Format: `{width}:{height}`.',
-    },
-    {
-      name: 'resolution',
-      type: 'string',
-      isOptional: true,
-      description:
-        'Resolution of the videos to generate. Format: `{width}x{height}`.',
-    },
-    {
-      name: 'duration',
-      type: 'number',
-      isOptional: true,
-      description: 'Duration of the video in seconds.',
-    },
-    {
-      name: 'fps',
-      type: 'number',
-      isOptional: true,
-      description: 'Frames per second for the video.',
-    },
-    {
-      name: 'seed',
-      type: 'number',
-      isOptional: true,
-      description: 'Seed for the video generation.',
-    },
-    {
-      name: 'providerOptions',
-      type: 'ProviderOptions',
-      isOptional: true,
-      description: 'Additional provider-specific options.',
-    },
-    {
-      name: 'maxVideosPerCall',
-      type: 'number',
-      isOptional: true,
-      description:
-        'Maximum number of videos to generate per API call. When n exceeds this value, multiple API calls will be made.',
-    },
-    {
-      name: 'maxRetries',
-      type: 'number',
-      isOptional: true,
-      description: 'Maximum number of retries. Default: 2.',
-    },
-    {
-      name: 'abortSignal',
-      type: 'AbortSignal',
-      isOptional: true,
-      description: 'An optional abort signal to cancel the call.',
-    },
-    {
-      name: 'headers',
-      type: 'Record<string, string>',
-      isOptional: true,
-      description: 'Additional HTTP headers for the request.',
-    },
-    {
-      name: 'download',
-      type: '(options: { url: URL; abortSignal?: AbortSignal }) => Promise<{ data: Uint8Array; mediaType: string | undefined }>',
-      isOptional: true,
-      description:
-        'Custom download function for fetching videos from URLs. Use `createDownload()` from `ai` to create a download function with custom size limits, e.g. `createDownload({ maxBytes: 50 * 1024 * 1024 })`. Default: built-in download with 2 GiB limit.',
-    },
-  ]}
-/>
-
-### Returns
-
-<PropertiesTable
-  content={[
-    {
-      name: 'video',
-      type: 'GeneratedFile',
-      description: 'The first video that was generated.',
-      properties: [
-        {
-          type: 'GeneratedFile',
-          parameters: [
-            {
-              name: 'base64',
-              type: 'string',
-              description: 'Video as a base64 encoded string.',
-            },
-            {
-              name: 'uint8Array',
-              type: 'Uint8Array',
-              description: 'Video as a Uint8Array.',
-            },
-            {
-              name: 'mediaType',
-              type: 'string',
-              description:
-                'The IANA media type of the video (e.g., video/mp4).',
-            },
-          ],
-        },
-      ],
-    },
-    {
-      name: 'videos',
-      type: 'Array<GeneratedFile>',
-      description: 'All videos that were generated.',
-      properties: [
-        {
-          type: 'GeneratedFile',
-          parameters: [
-            {
-              name: 'base64',
-              type: 'string',
-              description: 'Video as a base64 encoded string.',
-            },
-            {
-              name: 'uint8Array',
-              type: 'Uint8Array',
-              description: 'Video as a Uint8Array.',
-            },
-            {
-              name: 'mediaType',
-              type: 'string',
-              description:
-                'The IANA media type of the video (e.g., video/mp4).',
-            },
-          ],
-        },
-      ],
-    },
-    {
-      name: 'warnings',
-      type: 'Warning[]',
-      description:
-        'Warnings from the model provider (e.g. unsupported settings).',
-    },
-    {
-      name: 'providerMetadata',
-      type: 'VideoModelProviderMetadata',
-      isOptional: true,
-      description:
-        'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. A `videos` key is typically present in the metadata and is an array with the same length as the top level `videos` key. Details depend on the provider.',
-    },
-    {
-      name: 'responses',
-      type: 'Array<VideoModelResponseMetadata>',
-      description:
-        'Response metadata from the provider. There may be multiple responses if we made multiple calls to the model.',
-      properties: [
-        {
-          type: 'VideoModelResponseMetadata',
-          parameters: [
-            {
-              name: 'timestamp',
-              type: 'Date',
-              description: 'Timestamp for the start of the generated response.',
-            },
-            {
-              name: 'modelId',
-              type: 'string',
-              description:
-                'The ID of the response model that was used to generate the response.',
-            },
-            {
-              name: 'headers',
-              type: 'Record<string, string>',
-              isOptional: true,
-              description: 'Response headers.',
-            },
-            {
-              name: 'providerMetadata',
-              type: 'VideoModelProviderMetadata',
-              isOptional: true,
-              description:
-                'Provider-specific metadata for this individual API call. Useful for accessing per-call metadata when multiple calls are made.',
-            },
-          ],
-        },
-      ],
-    },
-  ]}
-/>

package/node_modules/ai/docs/07-reference/01-ai-sdk-core/15-agent.mdx

@@ -1,235 +0,0 @@
----
-title: Agent (Interface)
-description: API Reference for the Agent interface.
----
-
-# `Agent` (interface)
-
-The `Agent` interface defines a contract for agents that can generate or stream AI-generated responses in response to prompts. Agents may encapsulate advanced logic such as tool usage, multi-step workflows, or prompt handling, enabling both simple and autonomous AI agents.
-
-Implementations of the `Agent` interface—such as `ToolLoopAgent`—fulfill the same contract and integrate seamlessly with all SDK APIs and utilities that expect an agent. This design allows users to supply custom agent classes or wrappers for third-party chains, while maximizing compatibility with AI SDK features.
-
-## Interface Definition
-
-```ts
-import { ModelMessage } from '@ai-sdk/provider-utils';
-import { ToolSet } from '../generate-text/tool-set';
-import { Output } from '../generate-text/output';
-import { GenerateTextResult } from '../generate-text/generate-text-result';
-import { StreamTextResult } from '../generate-text/stream-text-result';
-
-export type AgentCallParameters<CALL_OPTIONS, TOOLS extends ToolSet = {}> = ([
-  CALL_OPTIONS,
-] extends [never]
-  ? { options?: never }
-  : { options: CALL_OPTIONS }) &
-  (
-    | {
-        /**
-         * A prompt. It can be either a text prompt or a list of messages.
-         *
-         * You can either use `prompt` or `messages` but not both.
-         */
-        prompt: string | Array<ModelMessage>;
-
-        /**
-         * A list of messages.
-         *
-         * You can either use `prompt` or `messages` but not both.
-         */
-        messages?: never;
-      }
-    | {
-        /**
-         * A list of messages.
-         *
-         * You can either use `prompt` or `messages` but not both.
-         */
-        messages: Array<ModelMessage>;
-
-        /**
-         * A prompt. It can be either a text prompt or a list of messages.
-         *
-         * You can either use `prompt` or `messages` but not both.
-         */
-        prompt?: never;
-      }
-  ) & {
-    /**
-     * Abort signal.
-     */
-    abortSignal?: AbortSignal;
-    /**
-     * Timeout in milliseconds. Can be specified as a number or as an object with a totalMs property.
-     * The call will be aborted if it takes longer than the specified timeout.
-     * Can be used alongside abortSignal.
-     */
-    timeout?: number | { totalMs?: number };
-    /**
-     * Callback that is called when the agent operation begins, before any LLM calls.
-     */
-    experimental_onStart?: ToolLoopAgentOnStartCallback<TOOLS>;
-    /**
-     * Callback that is called when a step (LLM call) begins, before the provider is called.
-     */
-    experimental_onStepStart?: ToolLoopAgentOnStepStartCallback<TOOLS>;
-    /**
-     * Callback that is called before each tool execution begins.
-     */
-    experimental_onToolCallStart?: ToolLoopAgentOnToolCallStartCallback<TOOLS>;
-    /**
-     * Callback that is called after each tool execution completes.
-     */
-    experimental_onToolCallFinish?: ToolLoopAgentOnToolCallFinishCallback<TOOLS>;
-    /**
-     * Callback that is called when each step (LLM call) is finished, including intermediate steps.
-     */
-    onStepFinish?: ToolLoopAgentOnStepFinishCallback<TOOLS>;
-    /**
-     * Callback that is called when all steps are finished and the response is complete.
-     */
-    onFinish?: ToolLoopAgentOnFinishCallback<TOOLS>;
-  };
-
-/**
- * An Agent receives a prompt (text or messages) and generates or streams an output
- * that consists of steps, tool calls, data parts, etc.
- *
- * You can implement your own Agent by implementing the `Agent` interface,
- * or use the `ToolLoopAgent` class.
- */
-export interface Agent<
-  CALL_OPTIONS = never,
-  TOOLS extends ToolSet = {},
-  OUTPUT extends Output = never,
-> {
-  /**
-   * The specification version of the agent interface. This will enable
-   * us to evolve the agent interface and retain backwards compatibility.
-   */
-  readonly version: 'agent-v1';
-
-  /**
-   * The id of the agent.
-   */
-  readonly id: string | undefined;
-
-  /**
-   * The tools that the agent can use.
-   */
-  readonly tools: TOOLS;
-
-  /**
-   * Generates an output from the agent (non-streaming).
-   */
-  generate(
-    options: AgentCallParameters<CALL_OPTIONS, TOOLS>,
-  ): PromiseLike<GenerateTextResult<TOOLS, OUTPUT>>;
-
-  /**
-   * Streams an output from the agent (streaming).
-   */
-  stream(
-    options: AgentStreamParameters<CALL_OPTIONS, TOOLS>,
-  ): PromiseLike<StreamTextResult<TOOLS, OUTPUT>>;
-}
-```
-
-## Core Properties & Methods
-
-| Name         | Type                                             | Description                                                         |
-| ------------ | ------------------------------------------------ | ------------------------------------------------------------------- |
-| `version`    | `'agent-v1'`                                     | Interface version for compatibility.                                |
-| `id`         | `string \| undefined`                            | Optional agent identifier.                                          |
-| `tools`      | `ToolSet`                                        | The set of tools available to this agent.                           |
-| `generate()` | `PromiseLike<GenerateTextResult<TOOLS, OUTPUT>>` | Generates full, non-streaming output for a text prompt or messages. |
-| `stream()`   | `PromiseLike<StreamTextResult<TOOLS, OUTPUT>>`   | Streams output (chunks or steps) for a text prompt or messages.     |
-
-## Generic Parameters
-
-| Parameter      | Default | Description                                                                |
-| -------------- | ------- | -------------------------------------------------------------------------- |
-| `CALL_OPTIONS` | `never` | Optional type for additional call options that can be passed to the agent. |
-| `TOOLS`        | `{}`    | The type of the tool set available to this agent.                          |
-| `OUTPUT`       | `never` | The type of additional output data that the agent can produce.             |
-
-## Method Parameters
-
-Both `generate()` and `stream()` accept an `AgentCallParameters<CALL_OPTIONS, TOOLS>` object with:
-
-- `prompt` (optional): A string prompt or array of `ModelMessage` objects
-- `messages` (optional): An array of `ModelMessage` objects (mutually exclusive with `prompt`)
-- `options` (optional): Additional call options when `CALL_OPTIONS` is not `never`
-- `abortSignal` (optional): An `AbortSignal` to cancel the operation
-- `timeout` (optional): A timeout in milliseconds. Can be specified as a number or as an object with a `totalMs` property. The call will be aborted if it takes longer than the specified timeout. Can be used alongside `abortSignal`.
-- `experimental_onStart` (optional): Callback invoked when the agent operation begins, before any LLM calls. Experimental.
-- `experimental_onStepStart` (optional): Callback invoked when a step (LLM call) begins, before the provider is called. Experimental.
-- `experimental_onToolCallStart` (optional): Callback invoked right before a tool's execute function runs. Experimental.
-- `experimental_onToolCallFinish` (optional): Callback invoked right after a tool's execute function completes or errors. Experimental.
-- `onStepFinish` (optional): A callback invoked after each agent step (LLM/tool call) completes. Useful for tracking token usage or logging.
-- `onFinish` (optional): A callback invoked when all steps are finished and the response is complete.
-
-## Example: Custom Agent Implementation
-
-Here's how you might implement your own Agent:
-
-```ts
-import { Agent, GenerateTextResult, StreamTextResult } from 'ai';
-import type { ModelMessage } from '@ai-sdk/provider-utils';
-
-class MyEchoAgent implements Agent {
-  version = 'agent-v1' as const;
-  id = 'echo';
-  tools = {};
-
-  async generate({ prompt, messages, abortSignal }) {
-    const text = prompt ?? JSON.stringify(messages);
-    return { text, steps: [] };
-  }
-
-  async stream({ prompt, messages, abortSignal }) {
-    const text = prompt ?? JSON.stringify(messages);
-    return {
-      textStream: (async function* () {
-        yield text;
-      })(),
-    };
-  }
-}
-```
-
-## Usage: Interacting with Agents
-
-All SDK utilities that accept an agent—including [`createAgentUIStream`](/docs/reference/ai-sdk-core/create-agent-ui-stream), [`createAgentUIStreamResponse`](/docs/reference/ai-sdk-core/create-agent-ui-stream-response), and [`pipeAgentUIStreamToResponse`](/docs/reference/ai-sdk-core/pipe-agent-ui-stream-to-response)—expect an object adhering to the `Agent` interface.
-
-You can use the official [`ToolLoopAgent`](/docs/reference/ai-sdk-core/tool-loop-agent) (recommended for multi-step AI workflows with tool use), or supply your own implementation:
-
-```ts
-import { ToolLoopAgent, createAgentUIStream } from "ai";
-
-const agent = new ToolLoopAgent({ ... });
-
-const stream = await createAgentUIStream({
-  agent,
-  messages: [{ role: "user", content: "What is the weather in NYC?" }]
-});
-
-for await (const chunk of stream) {
-  console.log(chunk);
-}
-```
-
-## See Also
-
-- [`ToolLoopAgent`](/docs/reference/ai-sdk-core/tool-loop-agent) &mdash; Official multi-step agent implementation
-- [`createAgentUIStream`](/docs/reference/ai-sdk-core/create-agent-ui-stream)
-- [`GenerateTextResult`](/docs/reference/ai-sdk-core/generate-text)
-- [`StreamTextResult`](/docs/reference/ai-sdk-core/stream-text)
-
-## Notes
-
-- Agents should define their `tools` property, even if empty (`{}`), for compatibility with SDK utilities.
-- The interface accepts both plain prompts and message arrays as input, but only one at a time.
-- The `CALL_OPTIONS` generic parameter allows agents to accept additional call-specific options when needed.
-- The `abortSignal` parameter enables cancellation of agent operations.
-- This design is extensible for both complex autonomous agents and simple LLM wrappers.