openai 7.4.0 → 7.5.0

package/src/lib/ChatCompletionStreamingRunner.ts

@@ -1,28 +1,28 @@
-import {
-  type ChatCompletionChunk,
-  type ChatCompletionCreateParamsStreaming,
-  type ChatCompletionMessageParam,
+import type {
+  ChatCompletionChunk,
+  ChatCompletionCreateParamsStreaming,
+  ChatCompletionMessageParam,
 } from '../resources/chat/completions';
-import { RunnerOptions, type AbstractChatCompletionRunnerEvents } from './AbstractChatCompletionRunner';
-import { type ReadableStream } from '../internal/shim-types';
-import { RunnableTools, type BaseFunctionsArgs } from './RunnableFunction';
-import {
-  type ChatCompletionReadableStreamItem,
-  ChatCompletionSnapshot,
-  ChatCompletionStream,
-  makeChatCompletionReadableStreamMessageChunk,
-} from './ChatCompletionStream';
+import type { AbstractChatCompletionRunnerEvents, RunnerOptions } from './AbstractChatCompletionRunner';
+import type { ReadableStream } from '../internal/shim-types';
+import type { BaseFunctionsArgs, RunnableTools } from './RunnableFunction';
+import { ChatCompletionStream, makeChatCompletionReadableStreamMessageChunk } from './ChatCompletionStream';
+import type { ChatCompletionReadableStreamItem, ChatCompletionSnapshot } from './ChatCompletionStream';
 import { OpenAIError } from '../error';
-import OpenAI from '../index';
-import { AutoParseableTool } from '../lib/parser';
+import type OpenAI from '../index';
+import type { AutoParseableTool } from '../lib/parser';
 import { Stream } from '../streaming';
 import { isAssistantMessage, isToolMessage } from './chatCompletionUtils';
 
+/** Conversation and chunk events emitted by a streaming chat completion tool runner. */
 export interface ChatCompletionStreamEvents extends AbstractChatCompletionRunnerEvents {
+  /** Called with each assistant-text fragment and the text accumulated so far. */
   content: (contentDelta: string, contentSnapshot: string) => void;
+  /** Called with each raw API chunk and its accumulated completion snapshot. */
   chunk: (chunk: ChatCompletionChunk, snapshot: ChatCompletionSnapshot) => void;
 }
 
+/** Streaming chat completion request fields shared by all tool-runner overloads. */
 type ChatCompletionStreamingToolRunnerParamsBase = Omit<ChatCompletionCreateParamsStreaming, 'tools'>;
 
 /**
@@ -30,7 +30,9 @@ type ChatCompletionStreamingToolRunnerParamsBase = Omit<ChatCompletionCreatePara
  */
 export type ChatCompletionStreamingToolRunnerParamsWithoutContext<FunctionsArgs extends BaseFunctionsArgs> =
   ChatCompletionStreamingToolRunnerParamsBase & {
+    /** Runnable function tools or auto-parseable tools with an attached callback. */
     tools: RunnableTools<FunctionsArgs> | AutoParseableTool<any, true>[];
+    /** Context is unavailable for the no-context runner overload. */
     toolContext?: never;
   };
 
@@ -41,6 +43,7 @@ export type ChatCompletionStreamingToolRunnerParamsWithContext<
   FunctionsArgs extends BaseFunctionsArgs,
   ToolContext,
 > = ChatCompletionStreamingToolRunnerParamsBase & {
+  /** Runnable function tools or auto-parseable tools that receive `toolContext`. */
   tools: RunnableTools<FunctionsArgs, ToolContext> | AutoParseableTool<any, true>[];
   /**
    * Context to pass to each tool callback during this run.
@@ -55,117 +58,74 @@ export type ChatCompletionStreamingToolRunnerParamsWithContext<
 export type ChatCompletionStreamingToolRunnerParams<
   FunctionsArgs extends BaseFunctionsArgs,
   ToolContext = never,
-> = [ToolContext] extends [never] ? ChatCompletionStreamingToolRunnerParamsWithoutContext<FunctionsArgs>
-: ChatCompletionStreamingToolRunnerParamsWithContext<FunctionsArgs, ToolContext>;
+> = [ToolContext] extends [never]
+  ? ChatCompletionStreamingToolRunnerParamsWithoutContext<FunctionsArgs>
+  : ChatCompletionStreamingToolRunnerParamsWithContext<FunctionsArgs, ToolContext>;
 
+/** Executes function tools while streaming every intermediate chat completion. */
 export class ChatCompletionStreamingRunner<ParsedT = null>
   extends ChatCompletionStream<ParsedT>
   implements AsyncIterable<ChatCompletionChunk>
 {
+  /** Restores a serialized tool run, including intermediate completions and tool-result messages. */
   static override fromReadableStream(stream: ReadableStream): ChatCompletionStreamingRunner<null> {
     const runner = new ChatCompletionStreamingRunner(null);
     runner._run(() => runner._fromReadableStream(stream));
     return runner;
   }
 
+  /** Serializes completion chunks and tool-result messages for replay in another runtime. */
   override toReadableStream(): ReadableStream {
-    const pushQueue: ChatCompletionReadableStreamItem[] = [];
-    const readQueue: {
-      resolve: (event: ChatCompletionReadableStreamItem | undefined) => void;
-      reject: (err: unknown) => void;
-    }[] = [];
-    let done = false;
     let lastChunk: ChatCompletionChunk | undefined;
     let toolCallIds: string[] | undefined;
 
-    const pushEvent = (event: ChatCompletionReadableStreamItem) => {
-      const reader = readQueue.shift();
-      if (reader) {
-        reader.resolve(event);
-      } else {
-        pushQueue.push(event);
-      }
-    };
-
-    this.on('chunk', (chunk) => {
-      lastChunk = chunk;
-      pushEvent(chunk);
-    });
-    this.on('message', (message: ChatCompletionMessageParam) => {
-      if (isAssistantMessage(message)) {
-        toolCallIds = message.tool_calls?.map((toolCall) => toolCall.id);
-        return;
-      }
-
-      if (isToolMessage(message)) {
-        if (!lastChunk) {
-          throw new OpenAIError('cannot serialize a tool message before receiving any chunks');
-        }
-        pushEvent(makeChatCompletionReadableStreamMessageChunk(lastChunk, message, toolCallIds));
-      }
-    });
-
-    this.on('end', () => {
-      done = true;
-      for (const reader of readQueue) {
-        reader.resolve(undefined);
-      }
-      readQueue.length = 0;
-    });
-
-    this.on('abort', (err) => {
-      done = true;
-      for (const reader of readQueue) {
-        reader.reject(err);
-      }
-      readQueue.length = 0;
-    });
-
-    this.on('error', (err) => {
-      done = true;
-      for (const reader of readQueue) {
-        reader.reject(err);
-      }
-      readQueue.length = 0;
-    });
+    const iterator = this._createIterator<ChatCompletionReadableStreamItem>(
+      (push) => {
+        const onChunk = (chunk: ChatCompletionChunk) => {
+          lastChunk = chunk;
+          push(chunk);
+        };
+        const onMessage = (message: ChatCompletionMessageParam) => {
+          if (isAssistantMessage(message)) {
+            toolCallIds = message.tool_calls?.map((toolCall) => toolCall.id);
+            return;
+          }
 
-    const iterator = (): AsyncIterator<ChatCompletionReadableStreamItem> => ({
-      next: async (): Promise<IteratorResult<ChatCompletionReadableStreamItem>> => {
-        if (!pushQueue.length) {
-          if (done) {
-            return { value: undefined, done: true };
+          if (isToolMessage(message)) {
+            if (!lastChunk) {
+              throw new OpenAIError('cannot serialize a tool message before receiving any chunks');
+            }
+            push(makeChatCompletionReadableStreamMessageChunk(lastChunk, message, toolCallIds));
           }
-          return new Promise<ChatCompletionReadableStreamItem | undefined>((resolve, reject) =>
-            readQueue.push({ resolve, reject }),
-          ).then((event) => (event ? { value: event, done: false } : { value: undefined, done: true }));
-        }
-        const event = pushQueue.shift();
-        if (!event) {
-          return { value: undefined, done: true };
-        }
-        return { value: event, done: false };
+        };
+        this.on('chunk', onChunk);
+        this.on('message', onMessage);
+        return () => {
+          this.off('chunk', onChunk);
+          this.off('message', onMessage);
+        };
       },
-      return: async () => {
-        this.abort();
-        return { value: undefined, done: true };
-      },
-    });
+      { onReturn: () => this.abort() },
+    );
 
-    const stream = new Stream(iterator, this.controller);
+    const stream = new Stream(() => iterator, this.controller);
     return stream.toReadableStream();
   }
 
+  /** Runs streaming function tools, passing the supplied context to each callback. */
   static runTools<T extends (string | object)[], ParsedT = null, ToolContext = unknown>(
     client: OpenAI,
     params: ChatCompletionStreamingToolRunnerParamsWithContext<T, ToolContext>,
     options?: RunnerOptions,
   ): ChatCompletionStreamingRunner<ParsedT>;
 
+  /** Runs streaming function tools until the model produces a final assistant message. */
   static runTools<T extends (string | object)[], ParsedT = null>(
     client: OpenAI,
     params: ChatCompletionStreamingToolRunnerParamsWithoutContext<T>,
     options?: RunnerOptions,
   ): ChatCompletionStreamingRunner<ParsedT>;
+  /** Starts a streaming tool loop and returns its event-driven conversation runner. */
   static runTools<T extends (string | object)[], ParsedT = null, ToolContext = unknown>(
     client: OpenAI,
     params:
@@ -179,7 +139,7 @@ export class ChatCompletionStreamingRunner<ParsedT = null>
     );
     const opts = {
       ...options,
-      headers: { ...options?.headers, 'X-Stainless-Helper-Method': 'runTools' },
+      __metadata: { ...options?.__metadata, helperMethod: 'runTools' },
     };
     runner._run(() => runner._runTools(client, params, runner, opts));
     return runner;

package/src/lib/EventEmitter.ts

@@ -1,18 +1,22 @@
+/** The listener callback associated with one event name in an event map. */
 type EventListener<Events, EventType extends keyof Events> = Events[EventType];
 
-type EventListeners<Events, EventType extends keyof Events> = Array<{
+type EventListeners<Events, EventType extends keyof Events> = {
   listener: EventListener<Events, EventType>;
   once?: boolean;
-}>;
+}[];
 
-export type EventParameters<Events, EventType extends keyof Events> = {
-  [Event in EventType]: EventListener<Events, EventType> extends (...args: infer P) => any ? P : never;
-}[EventType];
+/** The positional listener arguments associated with a named event. */
+export type EventParameters<Events, EventType extends keyof Events> = Record<
+  EventType,
+  EventListener<Events, EventType> extends (...args: infer P) => any ? P : never
+>[EventType];
 
+/** A lightweight event emitter with type-safe listeners and promise-based event waiting. */
 export class EventEmitter<EventTypes extends Record<string, (...args: any) => any>> {
   #listeners: {
     [Event in keyof EventTypes]?: EventListeners<EventTypes, Event>;
-  } = {};
+  } = Object.create(null);
 
   /**
    * Adds the listener function to the end of the listeners array for the event.
@@ -22,8 +26,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
    * @returns this, so that calls can be chained
    */
   on<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
-    const listeners: EventListeners<EventTypes, Event> =
-      this.#listeners[event] || (this.#listeners[event] = []);
+    const listeners: EventListeners<EventTypes, Event> = (this.#listeners[event] ||= []);
     listeners.push({ listener });
     return this;
   }
@@ -37,9 +40,13 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
    */
   off<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
     const listeners = this.#listeners[event];
-    if (!listeners) return this;
+    if (!listeners) {
+      return this;
+    }
     const index = listeners.findIndex((l) => l.listener === listener);
-    if (index >= 0) listeners.splice(index, 1);
+    if (index !== -1) {
+      listeners.splice(index, 1);
+    }
     return this;
   }
 
@@ -49,8 +56,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
    * @returns this, so that calls can be chained
    */
   once<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
-    const listeners: EventListeners<EventTypes, Event> =
-      this.#listeners[event] || (this.#listeners[event] = []);
+    const listeners: EventListeners<EventTypes, Event> = (this.#listeners[event] ||= []);
     listeners.push({ listener, once: true });
     return this;
   }
@@ -58,9 +64,11 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
   /**
    * This is similar to `.once()`, but returns a Promise that resolves the next time
    * the event is triggered, instead of calling a listener callback.
-   * @returns a Promise that resolves the next time given event is triggered,
-   * or rejects if an error is emitted.  (If you request the 'error' event,
-   * returns a promise that resolves with the error).
+   * Events without arguments resolve to `undefined`, single-argument events resolve
+   * to that argument, and events with multiple arguments resolve to an argument tuple.
+   *
+   * @returns A promise for the next event, or a rejection if an error occurs first.
+   * Requesting the `error` event resolves with the emitted error instead.
    *
    * Example:
    *
@@ -69,21 +77,27 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
   emitted<Event extends keyof EventTypes>(
     event: Event,
   ): Promise<
-    EventParameters<EventTypes, Event> extends [infer Param] ? Param
-    : EventParameters<EventTypes, Event> extends [] ? void
-    : EventParameters<EventTypes, Event>
+    EventParameters<EventTypes, Event> extends [infer Param]
+      ? Param
+      : EventParameters<EventTypes, Event> extends []
+        ? void
+        : EventParameters<EventTypes, Event>
   > {
     return new Promise((resolve, reject) => {
       const onError = (error: unknown) => {
         this.off(event, onEvent as any);
         reject(error);
       };
-      const onEvent = (value: unknown) => {
-        if (event !== 'error') this.off('error', onError as any);
-        resolve(value as any);
+      const onEvent = (...values: unknown[]) => {
+        if (event !== 'error') {
+          this.off('error', onError as any);
+        }
+        resolve((values.length > 1 ? values : values[0]) as any);
       };
 
-      if (event !== 'error') this.once('error', onError as any);
+      if (event !== 'error') {
+        this.once('error', onError as any);
+      }
       this.once(event, onEvent as any);
     });
   }
@@ -96,7 +110,9 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
     const listeners: EventListeners<EventTypes, Event> | undefined = this.#listeners[event];
     if (listeners) {
       this.#listeners[event] = listeners.filter((l) => !l.once) as any;
-      listeners.forEach(({ listener }: any) => listener(...(args as any)));
+      for (const { listener } of listeners as any) {
+        listener(...(args as any));
+      }
     }
   }