Remove experimental from useAssistant and AssistantResponse. (#1306)

Author: lgrammel

Diff for: .changeset/gentle-poets-check.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+Remove experimental from useAssistant and AssistantResponse.

Diff for: docs/pages/docs/api-reference/_meta.json

@@ -1,7 +1,7 @@
 {
   "generative-ui": "Generative UI",
   "providers": "Providers",
-  "use-assistant": "experimental_useAssistant",
+  "use-assistant": "useAssistant",
   "use-chat": "useChat",
   "use-completion": "useCompletion",
   "ai-stream": "AIStream",

Diff for: docs/pages/docs/api-reference/providers/_meta.json

@@ -9,5 +9,5 @@
   "mistral-stream": "MistralStream",
   "replicate-stream": "ReplicateStream",
   "inkeep-stream": "InkeepStream",
-  "assistant-response": "experimental_AssistantResponse"
+  "assistant-response": "AssistantResponse"
 }

Diff for: docs/pages/docs/api-reference/providers/assistant-response.mdx

@@ -1,30 +1,25 @@
 ---
-title: experimental_AssistantResponse
+title: AssistantResponse
 layout:
   toc: false
 ---
 
 import { Callout } from 'nextra-theme-docs';
 
-# `experimental_AssistantResponse`
+# `AssistantResponse`
 
-The `experimental_AssistantResponse` class allows you to send a stream of assistant update to `experimental_useAssistant`.
+The `AssistantResponse` allows you to send a stream of assistant update to `useAssistant`.
 
-<Callout>
-  The `experimental_` prefix indicates that the API is not yet stable and may
-  change in the future without a major version bump.
-</Callout>
+## `AssistantResponse(settings: AssistantResponseSettings, process: AssistantResponseCallback): Response` [#assistantresponse]
 
-## `experimental_AssistantResponse(settings: AssistantResponseSettings, process: AssistantResponseCallback): Response` [#assistantresponse]
-
-The `experimental_AssistantResponse` class is designed to facilitate streaming assistant responses to the `useAssistant` hook.
+The `AssistantResponse` is designed to facilitate streaming assistant responses to the `useAssistant` hook.
 It receives an assistant thread and a current message, and can send messages and data messages to the client.
 
 ## Parameters
 
 ### `settings: {threadId: string, messageId: string}`
 
-You can pass the thread and the latest message into the `experimental_AssistantResponse`. This establishes the context for the response.
+You can pass the thread and the latest message into the `AssistantResponse`. This establishes the context for the response.
 
 - `threadId: string`: The thread ID that the response is associated with.
 - `messageId: string`: The ID of the latest message that the response is associated with.
@@ -42,13 +37,13 @@ It gets invoked with the following functions that you can use to send messages a
 
 ### Server-Side Implementation
 
-This example highlights the usage of `experimental_AssistantResponse`
+This example highlights the usage of `AssistantResponse`
 for an OpenAI assistant within a Next.js environment.
 
 Server:
 
 ```tsx filename="app/api/assistant/route.ts"
-import { experimental_AssistantResponse } from 'ai';
+import { AssistantResponse } from 'ai';
 import OpenAI from 'openai';
 
 // Create an OpenAI API client (that's edge friendly!)
@@ -83,7 +78,7 @@ export async function POST(req: Request) {
     content: input.message,
   });
 
-  return experimental_AssistantResponse(
+  return AssistantResponse(
     { threadId, messageId: createdMessage.id },
     async ({ forwardStream, sendDataMessage }) => {
       // Run the assistant on the thread

Diff for: docs/pages/docs/api-reference/use-assistant.mdx

@@ -1,13 +1,13 @@
 ---
-title: experimental_useAssistant
+title: useAssistant
 ---
 
 import { OptionTable } from '@/components/table';
 import { FrameworkTabs, Tab } from '@/components/framework-tabs';
 
-# experimental_useAssistant
+# useAssistant
 
-## `experimental_useAssistant(options: UseAssistantOptions): UseAssistantHelpers` [#experimental_useAssistant]
+## `useAssistant(options: UseAssistantOptions): UseAssistantHelpers` [#useAssistant]
 
 `useAssistant` is a utility designed to handle the UI state of interacting with an OpenAI-compatible assistant API.
 This tool is useful when you need to integrate assistant capabilities into your application,
@@ -16,17 +16,13 @@ It works in conjunction with `AssistantResponse` in the backend.
 
 <FrameworkTabs>
   <Tab>
-To use `experimental_useAssistant` in React projects, you can import it from the `ai/react` subpath. 
-Here's an example demonstrating the use of `experimental_useAssistant` in a chat interface:
+To use `useAssistant` in React projects, you can import it from the `ai/react` subpath. 
+Here's an example demonstrating the use of `useAssistant` in a chat interface:
 
 ```tsx filename="app/assistant.tsx"
 'use client';
 
-import {
-  Message,
-  // import as useAssistant:
-  experimental_useAssistant as useAssistant,
-} from 'ai/react';
+import { Message, useAssistant } from 'ai/react';
 
 const roleToColorMap: Record<Message['role'], string> = {
   system: 'red',
@@ -124,7 +120,7 @@ export default function Chat() {
 
 ### `UseAssistantHelpers`
 
-The `experimental_useAssistant` hook returns an object with several helper methods and variables to manage the assistant state in the UI:
+The `useAssistant` hook returns an object with several helper methods and variables to manage the assistant state in the UI:
 
 <OptionTable
   options={[

Diff for: examples/next-openai/app/api/assistant/route.ts

@@ -1,4 +1,4 @@
-import { experimental_AssistantResponse } from 'ai';
+import { AssistantResponse } from 'ai';
 import OpenAI from 'openai';
 
 // Create an OpenAI API client (that's edge friendly!)
@@ -33,7 +33,7 @@ export async function POST(req: Request) {
     content: input.message,
   });
 
-  return experimental_AssistantResponse(
+  return AssistantResponse(
     { threadId, messageId: createdMessage.id },
     async ({ forwardStream, sendDataMessage }) => {
       // Run the assistant on the thread

Diff for: examples/next-openai/app/assistant/page.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { Message, experimental_useAssistant as useAssistant } from 'ai/react';
+import { Message, useAssistant as useAssistant } from 'ai/react';
 import { useEffect, useRef } from 'react';
 
 const roleToColorMap: Record<Message['role'], string> = {
@@ -29,7 +29,7 @@ export default function Chat() {
   return (
     <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch">
       {error != null && (
-        <div className="relative bg-red-500 text-white px-6 py-4 rounded-md">
+        <div className="relative px-6 py-4 text-white bg-red-500 rounded-md">
           <span className="block sm:inline">
             Error: {(error as any).toString()}
           </span>
@@ -59,7 +59,7 @@ export default function Chat() {
       ))}
 
       {status === 'in_progress' && (
-        <div className="h-8 w-full max-w-md p-2 mb-8 bg-gray-300 dark:bg-gray-600 rounded-lg animate-pulse" />
+        <div className="w-full h-8 max-w-md p-2 mb-8 bg-gray-300 rounded-lg dark:bg-gray-600 animate-pulse" />
       )}
 
       <form onSubmit={submitMessage}>

Diff for: packages/core/react/use-assistant.ts

@@ -100,7 +100,7 @@ export type UseAssistantOptions = {
   onError?: (error: Error) => void;
 };
 
-export function experimental_useAssistant({
+export function useAssistant({
   api,
   threadId: threadIdParam,
   credentials,
@@ -252,3 +252,8 @@ export function experimental_useAssistant({
     error,
   };
 }
+
+/**
+@deprecated Use `useAssistant` instead.
+ */
+export const experimental_useAssistant = useAssistant;

Diff for: packages/core/streams/assistant-response.ts

@@ -1,22 +1,59 @@
 import { AssistantStream } from 'openai/lib/AssistantStream';
+import { Run } from 'openai/resources/beta/threads/runs/runs';
 import { formatStreamPart } from '../shared/stream-parts';
 import { AssistantMessage, DataMessage } from '../shared/types';
-import { Run } from 'openai/resources/beta/threads/runs/runs';
 
+/**
+You can pass the thread and the latest message into the `AssistantResponse`. This establishes the context for the response.
+ */
 type AssistantResponseSettings = {
+  /**
+The thread ID that the response is associated with.
+   */
   threadId: string;
+
+  /**
+The ID of the latest message that the response is associated with.
+ */
   messageId: string;
 };
 
+/**
+The process parameter is a callback in which you can run the assistant on threads, and send messages and data messages to the client.
+ */
 type AssistantResponseCallback = (options: {
+  /**
+@deprecated use variable from outer scope instead.
+   */
   threadId: string;
+
+  /**
+@deprecated use variable from outer scope instead.
+   */
   messageId: string;
+
+  /**
+Forwards an assistant message (non-streaming) to the client.
+   */
   sendMessage: (message: AssistantMessage) => void;
+
+  /**
+Send a data message to the client. You can use this to provide information for rendering custom UIs while the assistant is processing the thread.
+ */
   sendDataMessage: (message: DataMessage) => void;
+
+  /**
+Forwards the assistant response stream to the client. Returns the `Run` object after it completes, or when it requires an action.
+   */
   forwardStream: (stream: AssistantStream) => Promise<Run | undefined>;
 }) => Promise<void>;
 
-export function experimental_AssistantResponse(
+/**
+The `AssistantResponse` allows you to send a stream of assistant update to `useAssistant`.
+It is designed to facilitate streaming assistant responses to the `useAssistant` hook.
+It receives an assistant thread and a current message, and can send messages and data messages to the client.
+ */
+export function AssistantResponse(
   { threadId, messageId }: AssistantResponseSettings,
   process: AssistantResponseCallback,
 ): Response {
@@ -120,3 +157,8 @@ export function experimental_AssistantResponse(
     },
   });
 }
+
+/**
+@deprecated Use `AssistantResponse` instead.
+ */
+export const experimental_AssistantResponse = AssistantResponse;