@fairyhunter13/ai-sdk 6.0.116-fork.1

package/docs/07-reference/02-ai-sdk-ui/02-use-completion.mdx

@@ -0,0 +1,185 @@
+---
+title: useCompletion
+description: API reference for the useCompletion hook.
+---
+
+# `useCompletion()`
+
+Allows you to create text completion based capabilities for your application. It enables the streaming of text completions from your AI provider, manages the state for chat input, and updates the UI automatically as new messages are received.
+
+## Import
+
+<Tabs items={['React', 'Svelte', 'Vue', 'Angular']}>
+  <Tab>
+    <Snippet
+      text="import { useCompletion } from '@ai-sdk/react'"
+      dark
+      prompt={false}
+    />
+  </Tab>
+  <Tab>
+    <Snippet
+      text="import { Completion } from '@ai-sdk/svelte'"
+      dark
+      prompt={false}
+    />
+  </Tab>
+  <Tab>
+    <Snippet
+      text="import { useCompletion } from '@ai-sdk/vue'"
+      dark
+      prompt={false}
+    />
+  </Tab>
+  <Tab>
+    <Snippet
+      text="import { Completion } from '@ai-sdk/angular'"
+      dark
+      prompt={false}
+    />
+  </Tab>
+</Tabs>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'api',
+      type: "string = '/api/completion'",
+      description:
+        'The API endpoint that is called to generate text. It can be a relative path (starting with `/`) or an absolute URL.',
+    },
+    {
+      name: 'id',
+      type: 'string',
+      description:
+        'A unique identifier for the completion. If not provided, a random one will be generated. When provided, the `useCompletion` hook with the same `id` will have shared states across components. This is useful when you have multiple components showing the same chat stream',
+    },
+    {
+      name: 'initialInput',
+      type: 'string',
+      description: 'An optional string for the initial prompt input.',
+    },
+    {
+      name: 'initialCompletion',
+      type: 'string',
+      description: 'An optional string for the initial completion result.',
+    },
+    {
+      name: 'onFinish',
+      type: '(prompt: string, completion: string) => void',
+      description:
+        'An optional callback function that is called when the completion stream ends.',
+    },
+    {
+      name: 'onError',
+      type: '(error: Error) => void',
+      description:
+        'An optional callback that will be called when the chat stream encounters an error.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string> | Headers',
+      description:
+        'An optional object of headers to be passed to the API endpoint.',
+    },
+    {
+      name: 'body',
+      type: 'object',
+      description:
+        'An optional, additional body object to be passed to the API endpoint.',
+    },
+    {
+      name: 'credentials',
+      type: "'omit' | 'same-origin' | 'include'",
+      description:
+        'An optional literal that sets the mode of credentials to be used on the request. Defaults to same-origin.',
+    },
+    {
+      name: 'streamProtocol',
+      type: "'text' | 'data'",
+      isOptional: true,
+      description:
+        'An optional literal that sets the type of stream to be used. Defaults to `data`. If set to `text`, the stream will be treated as a text stream.',
+    },
+    {
+      name: 'fetch',
+      type: 'FetchFunction',
+      isOptional: true,
+      description:
+        'Optional. A custom fetch function to be used for the API call. Defaults to the global fetch function.',
+    },
+    {
+      name: 'experimental_throttle',
+      type: 'number',
+      isOptional: true,
+      description:
+        'React only. Custom throttle wait time in milliseconds for the completion and data updates. When specified, throttles how often the UI updates during streaming. Default is undefined, which disables throttling.',
+    },
+
+]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'completion',
+      type: 'string',
+      description: 'The current text completion.',
+    },
+    {
+      name: 'complete',
+      type: '(prompt: string, options?: { headers?: Record<string, string> | Headers, body?: object }) => Promise<string | null | undefined>',
+      description:
+        'Function to execute text completion based on the provided prompt. Returns the completion result when finished.',
+    },
+    {
+      name: 'error',
+      type: 'undefined | Error',
+      description: 'The error thrown during the completion process, if any.',
+    },
+    {
+      name: 'setCompletion',
+      type: '(completion: string) => void',
+      description: 'Function to update the `completion` state.',
+    },
+    {
+      name: 'stop',
+      type: '() => void',
+      description: 'Function to abort the current API request.',
+    },
+    {
+      name: 'input',
+      type: 'string',
+      description: 'The current value of the input field.',
+    },
+    {
+      name: 'setInput',
+      type: 'React.Dispatch<React.SetStateAction<string>>',
+      description: 'Function to update the input value.',
+    },
+    {
+      name: 'handleInputChange',
+      type: '(event: any) => void',
+      description:
+        "Handler for the `onChange` event of the input field to control the input's value.",
+    },
+    {
+      name: 'handleSubmit',
+      type: '(event?: { preventDefault?: () => void }) => void',
+      description:
+        'Form submission handler that automatically resets the input field and appends a user message.',
+    },
+    {
+      name: 'isLoading',
+      type: 'boolean',
+      description:
+        'Boolean flag indicating whether a fetch operation is currently in progress.',
+    },
+  ]}
+/>

package/docs/07-reference/02-ai-sdk-ui/03-use-object.mdx

@@ -0,0 +1,196 @@
+---
+title: useObject
+description: API reference for the useObject hook.
+---
+
+# `experimental_useObject()`
+
+<Note>
+  `useObject` is an experimental feature and only available in React, Svelte,
+  and Vue.
+</Note>
+
+Allows you to consume text streams that represent a JSON object and parse them into a complete object based on a schema.
+You can use it together with [`streamText`](/docs/reference/ai-sdk-core/stream-text) and [`Output.object()`](/docs/reference/ai-sdk-core/output#output-object) in the backend.
+
+```tsx
+'use client';
+
+import { experimental_useObject as useObject } from '@ai-sdk/react';
+
+export default function Page() {
+  const { object, submit } = useObject({
+    api: '/api/use-object',
+    schema: z.object({ content: z.string() }),
+  });
+
+  return (
+    <div>
+      <button onClick={() => submit('example input')}>Generate</button>
+      {object?.content && <p>{object.content}</p>}
+    </div>
+  );
+}
+```
+
+## Import
+
+<Tabs items={['React', 'Svelte', 'Vue']}>
+  <Tab>
+    <Snippet
+      text="import { experimental_useObject as useObject } from '@ai-sdk/react'"
+      dark
+      prompt={false}
+    />
+  </Tab>
+  <Tab>
+    <Snippet
+      text="import { Experimental_StructuredObject } from '@ai-sdk/svelte'"
+      dark
+      prompt={false}
+    />
+  </Tab>
+  <Tab>
+    <Snippet
+      text="import { experimental_useObject } from '@ai-sdk/vue'"
+      dark
+      prompt={false}
+    />
+  </Tab>
+</Tabs>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'api',
+      type: 'string',
+      description:
+        'The API endpoint that is called to generate objects. It should stream JSON that matches the schema as chunked text. It can be a relative path (starting with `/`) or an absolute URL.',
+    },
+    {
+      name: 'schema',
+      type: 'Zod Schema | JSON Schema',
+      description:
+        'A schema that defines the shape of the complete object. You can either pass in a Zod schema or a JSON schema (using the `jsonSchema` function).',
+    },
+    {
+      name: 'id?',
+      type: 'string',
+      description:
+        'A unique identifier. If not provided, a random one will be generated. When provided, the `useObject` hook with the same `id` will have shared states across components.',
+    },
+    {
+      name: 'initialValue',
+      type: 'DeepPartial<RESULT> | undefined',
+      isOptional: true,
+      description: 'An value for the initial object. Optional.',
+    },
+    {
+      name: 'fetch',
+      type: 'FetchFunction',
+      isOptional: true,
+      description:
+        'A custom fetch function to be used for the API call. Defaults to the global fetch function. Optional.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string> | Headers',
+      isOptional: true,
+      description:
+        'A headers object to be passed to the API endpoint. Optional.',
+    },
+    {
+      name: 'credentials',
+      type: 'RequestCredentials',
+      isOptional: true,
+      description:
+        'The credentials mode to be used for the fetch request. Possible values are: "omit", "same-origin", "include". Optional.',
+    },
+    {
+      name: 'onError',
+      type: '(error: Error) => void',
+      isOptional: true,
+      description:
+        'Callback function to be called when an error is encountered. Optional.',
+    },
+    {
+      name: 'onFinish',
+      type: '(result: OnFinishResult) => void',
+      isOptional: true,
+      description: 'Called when the streaming response has finished.',
+      properties: [
+        {
+          type: 'OnFinishResult',
+          parameters: [
+            {
+              name: 'object',
+              type: 'T | undefined',
+              description:
+                'The generated object (typed according to the schema). Can be undefined if the final object does not match the schema.',
+            },
+            {
+              name: 'error',
+              type: 'Error | undefined',
+              description:
+                'Optional error object. This is e.g. a TypeValidationError when the final object does not match the schema.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'submit',
+      type: '(input: INPUT) => void',
+      description: 'Calls the API with the provided input as JSON body.',
+    },
+    {
+      name: 'object',
+      type: 'DeepPartial<RESULT> | undefined',
+      description:
+        'The current value for the generated object. Updated as the API streams JSON chunks.',
+    },
+    {
+      name: 'error',
+      type: 'Error | undefined',
+      description: 'The error object if the API call fails.',
+    },
+    {
+      name: 'isLoading',
+      type: 'boolean',
+      description:
+        'Boolean flag indicating whether a request is currently in progress.',
+    },
+    {
+      name: 'stop',
+      type: '() => void',
+      description: 'Function to abort the current API request.',
+    },
+    {
+      name: 'clear',
+      type: '() => void',
+      description: 'Function to clear the object state.',
+    },
+  ]}
+/>
+
+## Examples
+
+<ExampleLinks
+  examples={[
+    {
+      title: 'Streaming Object Generation with useObject',
+      link: '/examples/next-pages/basics/streaming-object-generation',
+    },
+  ]}
+/>

package/docs/07-reference/02-ai-sdk-ui/31-convert-to-model-messages.mdx

@@ -0,0 +1,231 @@
+---
+title: convertToModelMessages
+description: Convert useChat messages to ModelMessages for AI functions (API Reference)
+---
+
+# `convertToModelMessages()`
+
+The `convertToModelMessages` function is used to transform an array of UI messages from the `useChat` hook into an array of `ModelMessage` objects. These `ModelMessage` objects are compatible with AI core functions like `streamText`.
+
+```ts filename="app/api/chat/route.ts"
+import { convertToModelMessages, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Import
+
+<Snippet text={`import { convertToModelMessages } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'messages',
+      type: 'Message[]',
+      description:
+        'An array of UI messages from the useChat hook to be converted',
+    },
+    {
+      name: 'options',
+      type: '{ tools?: ToolSet, ignoreIncompleteToolCalls?: boolean, convertDataPart?: (part: DataUIPart) => TextPart | FilePart | undefined }',
+      description:
+        'Optional configuration object. Provide tools to enable multi-modal tool responses. Set ignoreIncompleteToolCalls to true to skip tool calls without results (default: false). Use convertDataPart to transform custom data parts into model-compatible content.',
+    },
+  ]}
+/>
+
+### Returns
+
+A Promise that resolves to an array of [`ModelMessage`](/docs/reference/ai-sdk-core/model-message) objects.
+
+<PropertiesTable
+  content={[
+    {
+      name: 'Promise<ModelMessage[]>',
+      type: 'Promise',
+      description:
+        'A Promise that resolves to an array of ModelMessage objects',
+    },
+  ]}
+/>
+
+## Multi-modal Tool Responses
+
+The `convertToModelMessages` function supports tools that can return multi-modal content. This is useful when tools need to return non-text content like images.
+
+```ts
+import { tool } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const screenshotTool = tool({
+  inputSchema: z.object({}),
+  execute: async () => 'imgbase64',
+  toModelOutput: ({ output }) => [{ type: 'image', data: output }],
+});
+
+const result = streamText({
+  model: __MODEL__,
+  messages: convertToModelMessages(messages, {
+    tools: {
+      screenshot: screenshotTool,
+    },
+  }),
+});
+```
+
+Tools can implement the optional `toModelOutput` method to transform their results into multi-modal content. The content is an array of content parts, where each part has a `type` (e.g., 'text', 'image') and corresponding data.
+
+## Custom Data Part Conversion
+
+The `convertToModelMessages` function supports converting custom data parts attached to user messages. This is useful when users need to include additional context (URLs, code files, JSON configs) with their messages.
+
+### Basic Usage
+
+By default, data parts in user messages are filtered out during conversion. To include them, provide a `convertDataPart` callback that transforms data parts into text or file parts that the model can understand:
+
+```ts filename="app/api/chat/route.ts"
+import { convertToModelMessages, streamText } from 'ai';
+
+type CustomUIMessage = UIMessage<
+  never,
+  {
+    url: { url: string; title: string; content: string };
+    'code-file': { filename: string; code: string; language: string };
+  }
+>;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: convertToModelMessages<CustomUIMessage>(messages, {
+      convertDataPart: part => {
+        // Convert URL attachments to text
+        if (part.type === 'data-url') {
+          return {
+            type: 'text',
+            text: `[Reference: ${part.data.title}](${part.data.url})\n\n${part.data.content}`,
+          };
+        }
+
+        // Convert code file attachments
+        if (part.type === 'data-code-file') {
+          return {
+            type: 'text',
+            text: `\`\`\`${part.data.language}\n// ${part.data.filename}\n${part.data.code}\n\`\`\``,
+          };
+        }
+
+        // Other data parts are ignored
+      },
+    }),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+### Use Cases
+
+**Attaching URL Content**
+Allow users to attach URLs to their messages, with the content fetched and formatted for the model:
+
+```ts
+// Client side
+sendMessage({
+  parts: [
+    { type: 'text', text: 'Analyze this article' },
+    {
+      type: 'data-url',
+      data: {
+        url: 'https://example.com/article',
+        title: 'Important Article',
+        content: '...',
+      },
+    },
+  ],
+});
+```
+
+**Including Code Files as Context**
+Let users reference code files in their conversations:
+
+```ts
+convertDataPart: part => {
+  if (part.type === 'data-code-file') {
+    return {
+      type: 'text',
+      text: `\`\`\`${part.data.language}\n${part.data.code}\n\`\`\``,
+    };
+  }
+};
+```
+
+**Selective Inclusion**
+Only data parts for which you return a text or file model message part are included,
+all other data parts are ignored.
+
+```ts
+const result = convertToModelMessages<
+  UIMessage<
+    unknown,
+    {
+      url: { url: string; title: string };
+      code: { code: string; language: string };
+      note: { text: string };
+    }
+  >
+>(messages, {
+  convertDataPart: part => {
+    if (part.type === 'data-url') {
+      return {
+        type: 'text',
+        text: `[${part.data.title}](${part.data.url})`,
+      };
+    }
+
+    // data-code and data-node are ignored
+  },
+});
+```
+
+### Type Safety
+
+The generic parameter ensures full type safety for your custom data parts:
+
+```ts
+type MyUIMessage = UIMessage<
+  unknown,
+  {
+    url: { url: string; content: string };
+    config: { key: string; value: string };
+  }
+>;
+
+// TypeScript knows the exact shape of part.data
+convertToModelMessages<MyUIMessage>(messages, {
+  convertDataPart: part => {
+    if (part.type === 'data-url') {
+      // part.data is typed as { url: string; content: string }
+      return { type: 'text', text: part.data.url };
+    }
+    // Return undefined to skip this part
+  },
+});
+```