ai 2.2.0 → 2.2.2

package/dist/index.d.ts

@@ -2,94 +2,6 @@ import { ChatCompletionMessage, CompletionCreateParams, CreateChatCompletionRequ
 import { ServerResponse } from 'node:http';
 import { Prediction } from 'replicate';
 
-interface FunctionCallPayload {
-    name: string;
-    arguments: Record<string, unknown>;
-}
-/**
- * Helper callback methods for AIStream stream lifecycle events
- * @interface
- */
-interface AIStreamCallbacks {
-    onStart?: () => Promise<void> | void;
-    onCompletion?: (completion: string) => Promise<void> | void;
-    onToken?: (token: string) => Promise<void> | void;
-}
-/**
- * Custom parser for AIStream data.
- * @interface
- */
-interface AIStreamParser {
-    (data: string): string | void;
-}
-/**
- * Creates a TransformStream that parses events from an EventSource stream using a custom parser.
- * @param {AIStreamParser} customParser - Function to handle event data.
- * @returns {TransformStream<Uint8Array, string>} TransformStream parsing events.
- */
-declare function createEventStreamTransformer(customParser?: AIStreamParser): TransformStream<Uint8Array, string>;
-/**
- * Creates a transform stream that encodes input messages and invokes optional callback functions.
- * The transform stream uses the provided callbacks to execute custom logic at different stages of the stream's lifecycle.
- * - `onStart`: Called once when the stream is initialized.
- * - `onToken`: Called for each tokenized message.
- * - `onCompletion`: Called once when the stream is flushed, with the aggregated messages.
- *
- * This function is useful when you want to process a stream of messages and perform specific actions during the stream's lifecycle.
- *
- * @param {AIStreamCallbacks} [callbacks] - An object containing the callback functions.
- * @return {TransformStream<string, Uint8Array>} A transform stream that encodes input messages as Uint8Array and allows the execution of custom logic through callbacks.
- *
- * @example
- * const callbacks = {
- *   onStart: async () => console.log('Stream started'),
- *   onToken: async (token) => console.log(`Token: ${token}`),
- *   onCompletion: async (completion) => console.log(`Completion: ${completion}`)
- * };
- * const transformer = createCallbacksTransformer(callbacks);
- */
-declare function createCallbacksTransformer(callbacks: AIStreamCallbacks | undefined): TransformStream<string, Uint8Array>;
-/**
- * Returns a stateful function that, when invoked, trims leading whitespace
- * from the input text. The trimming only occurs on the first invocation, ensuring that
- * subsequent calls do not alter the input text. This is particularly useful in scenarios
- * where a text stream is being processed and only the initial whitespace should be removed.
- *
- * @return {function(string): string} A function that takes a string as input and returns a string
- * with leading whitespace removed if it is the first invocation; otherwise, it returns the input unchanged.
- *
- * @example
- * const trimStart = trimStartOfStreamHelper();
- * const output1 = trimStart("   text"); // "text"
- * const output2 = trimStart("   text"); // "   text"
- *
- */
-declare function trimStartOfStreamHelper(): (text: string) => string;
-/**
- * Returns a ReadableStream created from the response, parsed and handled with custom logic.
- * The stream goes through two transformation stages, first parsing the events and then
- * invoking the provided callbacks.
- *
- * For 2xx HTTP responses:
- * - The function continues with standard stream processing.
- *
- * For non-2xx HTTP responses:
- * - If the response body is defined, it asynchronously extracts and decodes the response body.
- * - It then creates a custom ReadableStream to propagate a detailed error message.
- *
- * @param {Response} response - The response.
- * @param {AIStreamParser} customParser - The custom parser function.
- * @param {AIStreamCallbacks} callbacks - The callbacks.
- * @return {ReadableStream} The AIStream.
- * @throws Will throw an error if the response is not OK.
- */
-declare function AIStream(response: Response, customParser?: AIStreamParser, callbacks?: AIStreamCallbacks): ReadableStream<Uint8Array>;
-/**
- * Implements ReadableStream.from(asyncIterable), which isn't documented in MDN and isn't implemented in node.
- * https://github.com/whatwg/streams/commit/8d7a0bf26eb2cc23e884ddbaac7c1da4b91cf2bc
- */
-declare function readableFromAsyncIterable<T>(iterable: AsyncIterable<T>): ReadableStream<T>;
-
 /**
  * Shared types between the API and UI packages.
  */
@@ -253,11 +165,11 @@ type UseCompletionOptions = {
      */
     body?: object;
 };
-
 type JSONValue = null | string | number | boolean | {
     [x: string]: JSONValue;
 } | Array<JSONValue>;
-type OpenAIStreamCallbacks = AIStreamCallbacks & {
+
+type OpenAIStreamCallbacks = AIStreamCallbacksAndOptions & {
     /**
      * @example
      * ```js
@@ -285,7 +197,7 @@ type OpenAIStreamCallbacks = AIStreamCallbacks & {
      * })
      * ```
      */
-    experimental_onFunctionCall?: (functionCallPayload: FunctionCallPayload, createFunctionCallMessages: (functionCallResult: JSONValue) => CreateMessage[]) => Promise<Response | undefined | void | string>;
+    experimental_onFunctionCall?: (functionCallPayload: FunctionCallPayload, createFunctionCallMessages: (functionCallResult: JSONValue) => CreateMessage[]) => Promise<Response | undefined | void | string | AsyncIterable<ChatCompletionChunk>>;
 };
 interface ChatCompletionChunk {
     id: string;
@@ -329,11 +241,134 @@ interface FunctionCall {
 }
 declare function OpenAIStream(res: Response | AsyncIterable<ChatCompletionChunk>, callbacks?: OpenAIStreamCallbacks): ReadableStream;
 
+interface FunctionCallPayload {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * Configuration options and helper callback methods for AIStream stream lifecycle events.
+ * @interface
+ */
+interface AIStreamCallbacksAndOptions {
+    /** `onStart`: Called once when the stream is initialized. */
+    onStart?: () => Promise<void> | void;
+    /** `onCompletion`: Called for each tokenized message. */
+    onCompletion?: (completion: string) => Promise<void> | void;
+    /** `onFinal`: Called once when the stream is closed with the final completion message. */
+    onFinal?: (completion: string) => Promise<void> | void;
+    /** `onToken`: Called for each tokenized message. */
+    onToken?: (token: string) => Promise<void> | void;
+    /**
+     * A flag for enabling the experimental_StreamData class and the new protocol.
+     * @see https://github.com/vercel-labs/ai/pull/425
+     *
+     * When StreamData is rolled out, this will be removed and the new protocol will be used by default.
+     */
+    experimental_streamData?: boolean;
+}
+/**
+ * Custom parser for AIStream data.
+ * @interface
+ */
+interface AIStreamParser {
+    (data: string): string | void;
+}
+/**
+ * Creates a TransformStream that parses events from an EventSource stream using a custom parser.
+ * @param {AIStreamParser} customParser - Function to handle event data.
+ * @returns {TransformStream<Uint8Array, string>} TransformStream parsing events.
+ */
+declare function createEventStreamTransformer(customParser?: AIStreamParser): TransformStream<Uint8Array, string>;
+/**
+ * Creates a transform stream that encodes input messages and invokes optional callback functions.
+ * The transform stream uses the provided callbacks to execute custom logic at different stages of the stream's lifecycle.
+ * - `onStart`: Called once when the stream is initialized.
+ * - `onToken`: Called for each tokenized message.
+ * - `onCompletion`: Called every time an AIStream completion message is received. This can occur multiple times when using e.g. OpenAI functions
+ * - `onFinal`: Called once when the stream is closed with the final completion message.
+ *
+ * This function is useful when you want to process a stream of messages and perform specific actions during the stream's lifecycle.
+ *
+ * @param {AIStreamCallbacksAndOptions} [callbacks] - An object containing the callback functions.
+ * @return {TransformStream<string, Uint8Array>} A transform stream that encodes input messages as Uint8Array and allows the execution of custom logic through callbacks.
+ *
+ * @example
+ * const callbacks = {
+ *   onStart: async () => console.log('Stream started'),
+ *   onToken: async (token) => console.log(`Token: ${token}`),
+ *   onCompletion: async (completion) => console.log(`Completion: ${completion}`)
+ *   onFinal: async () => data.close()
+ * };
+ * const transformer = createCallbacksTransformer(callbacks);
+ */
+declare function createCallbacksTransformer(cb: AIStreamCallbacksAndOptions | OpenAIStreamCallbacks | undefined): TransformStream<string, Uint8Array>;
+/**
+ * Returns a stateful function that, when invoked, trims leading whitespace
+ * from the input text. The trimming only occurs on the first invocation, ensuring that
+ * subsequent calls do not alter the input text. This is particularly useful in scenarios
+ * where a text stream is being processed and only the initial whitespace should be removed.
+ *
+ * @return {function(string): string} A function that takes a string as input and returns a string
+ * with leading whitespace removed if it is the first invocation; otherwise, it returns the input unchanged.
+ *
+ * @example
+ * const trimStart = trimStartOfStreamHelper();
+ * const output1 = trimStart("   text"); // "text"
+ * const output2 = trimStart("   text"); // "   text"
+ *
+ */
+declare function trimStartOfStreamHelper(): (text: string) => string;
+/**
+ * Returns a ReadableStream created from the response, parsed and handled with custom logic.
+ * The stream goes through two transformation stages, first parsing the events and then
+ * invoking the provided callbacks.
+ *
+ * For 2xx HTTP responses:
+ * - The function continues with standard stream processing.
+ *
+ * For non-2xx HTTP responses:
+ * - If the response body is defined, it asynchronously extracts and decodes the response body.
+ * - It then creates a custom ReadableStream to propagate a detailed error message.
+ *
+ * @param {Response} response - The response.
+ * @param {AIStreamParser} customParser - The custom parser function.
+ * @param {AIStreamCallbacksAndOptions} callbacks - The callbacks.
+ * @return {ReadableStream} The AIStream.
+ * @throws Will throw an error if the response is not OK.
+ */
+declare function AIStream(response: Response, customParser?: AIStreamParser, callbacks?: AIStreamCallbacksAndOptions): ReadableStream<Uint8Array>;
+/**
+ * Implements ReadableStream.from(asyncIterable), which isn't documented in MDN and isn't implemented in node.
+ * https://github.com/whatwg/streams/commit/8d7a0bf26eb2cc23e884ddbaac7c1da4b91cf2bc
+ */
+declare function readableFromAsyncIterable<T>(iterable: AsyncIterable<T>): ReadableStream<T>;
+
+/**
+ * A stream wrapper to send custom JSON-encoded data back to the client.
+ */
+declare class experimental_StreamData {
+    private encoder;
+    private controller;
+    stream: TransformStream<Uint8Array, Uint8Array>;
+    private isClosedPromise;
+    private isClosedPromiseResolver;
+    private isClosed;
+    private data;
+    constructor();
+    close(): Promise<void>;
+    append(value: JSONValue): void;
+}
+/**
+ * A TransformStream for LLMs that do not have their own transform stream handlers managing encoding (e.g. OpenAIStream has one for function call handling).
+ * This assumes every chunk is a 'text' chunk.
+ */
+declare function createStreamDataTransformer(experimental_streamData: boolean | undefined): TransformStream<any, any>;
+
 /**
  * A utility class for streaming text responses.
  */
 declare class StreamingTextResponse extends Response {
-    constructor(res: ReadableStream, init?: ResponseInit);
+    constructor(res: ReadableStream, init?: ResponseInit, data?: experimental_StreamData);
 }
 /**
  * A utility function to stream a ReadableStream to a Node.js response-like object.
@@ -343,9 +378,9 @@ declare function streamToResponse(res: ReadableStream, response: ServerResponse,
     status?: number;
 }): void;
 
-declare function HuggingFaceStream(res: AsyncGenerator<any>, callbacks?: AIStreamCallbacks): ReadableStream;
+declare function HuggingFaceStream(res: AsyncGenerator<any>, callbacks?: AIStreamCallbacksAndOptions): ReadableStream;
 
-declare function CohereStream(reader: Response, callbacks?: AIStreamCallbacks): ReadableStream;
+declare function CohereStream(reader: Response, callbacks?: AIStreamCallbacksAndOptions): ReadableStream;
 
 interface CompletionChunk {
     /**
@@ -372,10 +407,10 @@ interface CompletionChunk {
  * or the return value of `await client.completions.create({ stream: true })`
  * from the `@anthropic-ai/sdk` package.
  */
-declare function AnthropicStream(res: Response | AsyncIterable<CompletionChunk>, cb?: AIStreamCallbacks): ReadableStream;
+declare function AnthropicStream(res: Response | AsyncIterable<CompletionChunk>, cb?: AIStreamCallbacksAndOptions): ReadableStream;
 
-declare function LangChainStream(callbacks?: AIStreamCallbacks): {
-    stream: ReadableStream<Uint8Array>;
+declare function LangChainStream(callbacks?: AIStreamCallbacksAndOptions): {
+    stream: ReadableStream<any>;
     handlers: {
         handleLLMNewToken: (token: string) => Promise<void>;
         handleLLMStart: (_llm: any, _prompts: string[], runId: string) => Promise<void>;
@@ -409,9 +444,49 @@ declare function LangChainStream(callbacks?: AIStreamCallbacks): {
  * return new StreamingTextResponse(stream)
  *
  */
-declare function ReplicateStream(res: Prediction, cb?: AIStreamCallbacks): Promise<ReadableStream>;
+declare function ReplicateStream(res: Prediction, cb?: AIStreamCallbacksAndOptions): Promise<ReadableStream>;
 
 declare const nanoid: (size?: number | undefined) => string;
-declare function createChunkDecoder(): (chunk: Uint8Array | undefined) => string;
+declare function createChunkDecoder(complex?: boolean): (chunk: Uint8Array | undefined) => any;
+
+/**
+ * The map of prefixes for data in the stream
+ *
+ * - 0: Text from the LLM response
+ * - 1: (OpenAI) function_call responses
+ * - 2: custom JSON added by the user using `Data`
+ *
+ * Example:
+ * ```
+ * 0:Vercel
+ * 0:'s
+ * 0: AI
+ * 0: AI
+ * 0: SDK
+ * 0: is great
+ * 0:!
+ * 2: { "someJson": "value" }
+ * 1: {"function_call": {"name": "get_current_weather", "arguments": "{\\n\\"location\\": \\"Charlottesville, Virginia\\",\\n\\"format\\": \\"celsius\\"\\n}"}}
+ *```
+ */
+declare const StreamStringPrefixes: {
+    readonly text: 0;
+    readonly function_call: 1;
+    readonly data: 2;
+};
+declare const isStreamStringEqualToType: (type: keyof typeof StreamStringPrefixes, value: string) => value is `0:${string}\n` | `1:${string}\n` | `2:${string}\n`;
+/**
+ * Prepends a string with a prefix from the `StreamChunkPrefixes`, JSON-ifies it, and appends a new line.
+ */
+declare const getStreamString: (type: keyof typeof StreamStringPrefixes, value: JSONValue) => StreamString;
+type StreamString = `${(typeof StreamStringPrefixes)[keyof typeof StreamStringPrefixes]}:${string}\n`;
+declare const getStreamStringTypeAndValue: (line: string) => {
+    type: keyof typeof StreamStringPrefixes;
+    value: string;
+};
+/**
+ * A header sent to the client so it knows how to handle parsing the stream (as a deprecated text response or using the new prefixed protocol)
+ */
+declare const COMPLEX_HEADER = "X-Experimental-Stream-Data";
 
-export { AIStream, AIStreamCallbacks, AIStreamParser, AnthropicStream, ChatRequest, ChatRequestOptions, CohereStream, CreateMessage, FunctionCallHandler, FunctionCallPayload, HuggingFaceStream, LangChainStream, Message, OpenAIStream, OpenAIStreamCallbacks, ReplicateStream, RequestOptions, StreamingTextResponse, UseChatOptions, UseCompletionOptions, createCallbacksTransformer, createChunkDecoder, createEventStreamTransformer, nanoid, readableFromAsyncIterable, streamToResponse, trimStartOfStreamHelper };
+export { AIStream, AIStreamCallbacksAndOptions, AIStreamParser, AnthropicStream, COMPLEX_HEADER, ChatRequest, ChatRequestOptions, CohereStream, CreateMessage, FunctionCallHandler, FunctionCallPayload, HuggingFaceStream, JSONValue, LangChainStream, Message, OpenAIStream, OpenAIStreamCallbacks, ReplicateStream, RequestOptions, StreamString, StreamStringPrefixes, StreamingTextResponse, UseChatOptions, UseCompletionOptions, createCallbacksTransformer, createChunkDecoder, createEventStreamTransformer, createStreamDataTransformer, experimental_StreamData, getStreamString, getStreamStringTypeAndValue, isStreamStringEqualToType, nanoid, readableFromAsyncIterable, streamToResponse, trimStartOfStreamHelper };