openai 4.53.2 → 4.55.0

package/src/helpers/zod.ts

@@ -0,0 +1,102 @@
+import { ResponseFormatJSONSchema } from "../resources";
+import type z from 'zod';
+import {
+  AutoParseableResponseFormat,
+  AutoParseableTool,
+  makeParseableResponseFormat,
+  makeParseableTool,
+} from '../lib/parser';
+import { zodToJsonSchema as _zodToJsonSchema } from '../_vendor/zod-to-json-schema';
+
+function zodToJsonSchema(schema: z.ZodType): Record<string, unknown> {
+  return _zodToJsonSchema(schema, { openaiStrictMode: true });
+}
+
+/**
+ * Creates a chat completion `JSONSchema` response format object from
+ * the given Zod schema.
+ *
+ * If this is passed to the `.parse()`, `.stream()` or `.runTools()`
+ * chat completion methods then the response message will contain a
+ * `.parsed` property that is the result of parsing the content with
+ * the given Zod object.
+ *
+ * ```ts
+ * const completion = await client.beta.chat.completions.parse({
+ *    model: 'gpt-4o-2024-08-06',
+ *    messages: [
+ *      { role: 'system', content: 'You are a helpful math tutor.' },
+ *      { role: 'user', content: 'solve 8x + 31 = 2' },
+ *    ],
+ *    response_format: zodResponseFormat(
+ *      z.object({
+ *        steps: z.array(z.object({
+ *          explanation: z.string(),
+ *          answer: z.string(),
+ *        })),
+ *        final_answer: z.string(),
+ *      }),
+ *      'math_answer',
+ *    ),
+ *  });
+ *  const message = completion.choices[0]?.message;
+ *  if (message?.parsed) {
+ *    console.log(message.parsed);
+ *    console.log(message.parsed.final_answer);
+ * }
+ * ```
+ *
+ * This can be passed directly to the `.create()` method but will not
+ * result in any automatic parsing, you'll have to parse the response yourself.
+ */
+export function zodResponseFormat<ZodInput extends z.ZodType>(
+  zodObject: ZodInput,
+  name: string,
+  props?: Omit<ResponseFormatJSONSchema, 'schema' | 'strict' | 'name'>,
+): AutoParseableResponseFormat<z.infer<ZodInput>> {
+  return makeParseableResponseFormat(
+    {
+      type: 'json_schema',
+      json_schema: {
+        ...props,
+        name,
+        strict: true,
+        schema: zodToJsonSchema(zodObject),
+      },
+    },
+    (content) => zodObject.parse(JSON.parse(content)),
+  );
+}
+
+/**
+ * Creates a chat completion `function` tool that can be invoked
+ * automatically by the chat completion `.runTools()` method or automatically
+ * parsed by `.parse()` / `.stream()`.
+ */
+export function zodFunction<Parameters extends z.ZodType>(options: {
+  name: string;
+  parameters: Parameters;
+  function?: ((args: z.infer<Parameters>) => unknown | Promise<unknown>) | undefined;
+  description?: string | undefined;
+}): AutoParseableTool<{
+  arguments: Parameters;
+  name: string;
+  function: (args: z.infer<Parameters>) => unknown;
+}> {
+  // @ts-expect-error TODO
+  return makeParseableTool<any>(
+    {
+      type: 'function',
+      function: {
+        name: options.name,
+        parameters: zodToJsonSchema(options.parameters),
+        strict: true,
+        ...(options.description ? { description: options.description } : undefined),
+      },
+    },
+    {
+      callback: options.function,
+      parser: (args) => options.parameters.parse(JSON.parse(args)),
+    },
+  );
+}

package/src/index.ts

@@ -184,6 +184,7 @@ export class OpenAI extends Core.APIClient {
   }
 
   static OpenAI = this;
+  static DEFAULT_TIMEOUT = 600000; // 10 minutes
 
   static OpenAIError = Errors.OpenAIError;
   static APIError = Errors.APIError;
@@ -247,6 +248,7 @@ export namespace OpenAI {
   export import ChatCompletionChunk = API.ChatCompletionChunk;
   export import ChatCompletionContentPart = API.ChatCompletionContentPart;
   export import ChatCompletionContentPartImage = API.ChatCompletionContentPartImage;
+  export import ChatCompletionContentPartRefusal = API.ChatCompletionContentPartRefusal;
   export import ChatCompletionContentPartText = API.ChatCompletionContentPartText;
   export import ChatCompletionFunctionCallOption = API.ChatCompletionFunctionCallOption;
   export import ChatCompletionFunctionMessageParam = API.ChatCompletionFunctionMessageParam;
@@ -281,15 +283,18 @@ export namespace OpenAI {
 
   export import Images = API.Images;
   export import Image = API.Image;
+  export import ImageModel = API.ImageModel;
   export import ImagesResponse = API.ImagesResponse;
   export import ImageCreateVariationParams = API.ImageCreateVariationParams;
   export import ImageEditParams = API.ImageEditParams;
   export import ImageGenerateParams = API.ImageGenerateParams;
 
   export import Audio = API.Audio;
+  export import AudioModel = API.AudioModel;
 
   export import Moderations = API.Moderations;
   export import Moderation = API.Moderation;
+  export import ModerationModel = API.ModerationModel;
   export import ModerationCreateResponse = API.ModerationCreateResponse;
   export import ModerationCreateParams = API.ModerationCreateParams;
 
@@ -318,6 +323,9 @@ export namespace OpenAI {
   export import ErrorObject = API.ErrorObject;
   export import FunctionDefinition = API.FunctionDefinition;
   export import FunctionParameters = API.FunctionParameters;
+  export import ResponseFormatJSONObject = API.ResponseFormatJSONObject;
+  export import ResponseFormatJSONSchema = API.ResponseFormatJSONSchema;
+  export import ResponseFormatText = API.ResponseFormatText;
 }
 
 // ---------------------- Azure ----------------------

package/src/lib/AbstractChatCompletionRunner.ts

@@ -1,18 +1,18 @@
 import * as Core from "../core";
 import { type CompletionUsage } from "../resources/completions";
 import {
-  type Completions,
   type ChatCompletion,
   type ChatCompletionMessage,
   type ChatCompletionMessageParam,
   type ChatCompletionCreateParams,
   type ChatCompletionTool,
 } from "../resources/chat/completions";
-import { APIUserAbortError, OpenAIError } from "../error";
+import { OpenAIError } from "../error";
 import {
   type RunnableFunction,
   isRunnableFunctionWithParse,
   type BaseFunctionsArgs,
+  RunnableToolFunction,
 } from './RunnableFunction';
 import { ChatCompletionFunctionRunnerParams, ChatCompletionToolRunnerParams } from './ChatCompletionRunner';
 import {
@@ -20,6 +20,10 @@ import {
   ChatCompletionStreamingToolRunnerParams,
 } from './ChatCompletionStreamingRunner';
 import { isAssistantMessage, isFunctionMessage, isToolMessage } from './chatCompletionUtils';
+import { BaseEvents, EventStream } from './EventStream';
+import { ParsedChatCompletion } from '../resources/beta/chat/completions';
+import OpenAI from '../index';
+import { isAutoParsableTool, parseChatCompletion } from "./parser";
 
 const DEFAULT_MAX_CHAT_COMPLETIONS = 10;
 export interface RunnerOptions extends Core.RequestOptions {
@@ -27,60 +31,17 @@ export interface RunnerOptions extends Core.RequestOptions {
   maxChatCompletions?: number;
 }
 
-export abstract class AbstractChatCompletionRunner<
-  Events extends CustomEvents<any> = AbstractChatCompletionRunnerEvents,
-> {
-  controller: AbortController = new AbortController();
-
-  #connectedPromise: Promise<void>;
-  #resolveConnectedPromise: () => void = () => {};
-  #rejectConnectedPromise: (error: OpenAIError) => void = () => {};
-
-  #endPromise: Promise<void>;
-  #resolveEndPromise: () => void = () => {};
-  #rejectEndPromise: (error: OpenAIError) => void = () => {};
-
-  #listeners: { [Event in keyof Events]?: ListenersForEvent<Events, Event> } = {};
-
-  protected _chatCompletions: ChatCompletion[] = [];
+export class AbstractChatCompletionRunner<
+  EventTypes extends AbstractChatCompletionRunnerEvents,
+  ParsedT,
+> extends EventStream<EventTypes> {
+  protected _chatCompletions: ParsedChatCompletion<ParsedT>[] = [];
   messages: ChatCompletionMessageParam[] = [];
 
-  #ended = false;
-  #errored = false;
-  #aborted = false;
-  #catchingPromiseCreated = false;
-
-  constructor() {
-    this.#connectedPromise = new Promise<void>((resolve, reject) => {
-      this.#resolveConnectedPromise = resolve;
-      this.#rejectConnectedPromise = reject;
-    });
-
-    this.#endPromise = new Promise<void>((resolve, reject) => {
-      this.#resolveEndPromise = resolve;
-      this.#rejectEndPromise = reject;
-    });
-
-    // Don't let these promises cause unhandled rejection errors.
-    // we will manually cause an unhandled rejection error later
-    // if the user hasn't registered any error listener or called
-    // any promise-returning method.
-    this.#connectedPromise.catch(() => {});
-    this.#endPromise.catch(() => {});
-  }
-
-  protected _run(executor: () => Promise<any>) {
-    // Unfortunately if we call `executor()` immediately we get runtime errors about
-    // references to `this` before the `super()` constructor call returns.
-    setTimeout(() => {
-      executor().then(() => {
-        this._emitFinal();
-        this._emit('end');
-      }, this.#handleError);
-    }, 0);
-  }
-
-  protected _addChatCompletion(chatCompletion: ChatCompletion): ChatCompletion {
+  protected _addChatCompletion(
+    this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>,
+    chatCompletion: ParsedChatCompletion<ParsedT>,
+  ): ParsedChatCompletion<ParsedT> {
     this._chatCompletions.push(chatCompletion);
     this._emit('chatCompletion', chatCompletion);
     const message = chatCompletion.choices[0]?.message;
@@ -88,7 +49,11 @@ export abstract class AbstractChatCompletionRunner<
     return chatCompletion;
   }
 
-  protected _addMessage(message: ChatCompletionMessageParam, emit = true) {
+  protected _addMessage(
+    this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>,
+    message: ChatCompletionMessageParam,
+    emit = true,
+  ) {
     if (!('content' in message)) message.content = null;
 
     this.messages.push(message);
@@ -110,104 +75,11 @@ export abstract class AbstractChatCompletionRunner<
     }
   }
 
-  protected _connected() {
-    if (this.ended) return;
-    this.#resolveConnectedPromise();
-    this._emit('connect');
-  }
-
-  get ended(): boolean {
-    return this.#ended;
-  }
-
-  get errored(): boolean {
-    return this.#errored;
-  }
-
-  get aborted(): boolean {
-    return this.#aborted;
-  }
-
-  abort() {
-    this.controller.abort();
-  }
-
-  /**
-   * Adds the listener function to the end of the listeners array for the event.
-   * No checks are made to see if the listener has already been added. Multiple calls passing
-   * the same combination of event and listener will result in the listener being added, and
-   * called, multiple times.
-   * @returns this ChatCompletionStream, so that calls can be chained
-   */
-  on<Event extends keyof Events>(event: Event, listener: ListenerForEvent<Events, Event>): this {
-    const listeners: ListenersForEvent<Events, Event> =
-      this.#listeners[event] || (this.#listeners[event] = []);
-    listeners.push({ listener });
-    return this;
-  }
-
-  /**
-   * Removes the specified listener from the listener array for the event.
-   * off() will remove, at most, one instance of a listener from the listener array. If any single
-   * listener has been added multiple times to the listener array for the specified event, then
-   * off() must be called multiple times to remove each instance.
-   * @returns this ChatCompletionStream, so that calls can be chained
-   */
-  off<Event extends keyof Events>(event: Event, listener: ListenerForEvent<Events, Event>): this {
-    const listeners = this.#listeners[event];
-    if (!listeners) return this;
-    const index = listeners.findIndex((l) => l.listener === listener);
-    if (index >= 0) listeners.splice(index, 1);
-    return this;
-  }
-
-  /**
-   * Adds a one-time listener function for the event. The next time the event is triggered,
-   * this listener is removed and then invoked.
-   * @returns this ChatCompletionStream, so that calls can be chained
-   */
-  once<Event extends keyof Events>(event: Event, listener: ListenerForEvent<Events, Event>): this {
-    const listeners: ListenersForEvent<Events, Event> =
-      this.#listeners[event] || (this.#listeners[event] = []);
-    listeners.push({ listener, once: true });
-    return this;
-  }
-
-  /**
-   * 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).
-   *
-   * Example:
-   *
-   *   const message = await stream.emitted('message') // rejects if the stream errors
-   */
-  emitted<Event extends keyof Events>(
-    event: Event,
-  ): Promise<
-    EventParameters<Events, Event> extends [infer Param] ? Param
-    : EventParameters<Events, Event> extends [] ? void
-    : EventParameters<Events, Event>
-  > {
-    return new Promise((resolve, reject) => {
-      this.#catchingPromiseCreated = true;
-      if (event !== 'error') this.once('error', reject);
-      this.once(event, resolve as any);
-    });
-  }
-
-  async done(): Promise<void> {
-    this.#catchingPromiseCreated = true;
-    await this.#endPromise;
-  }
-
   /**
    * @returns a promise that resolves with the final ChatCompletion, or rejects
    * if an error occurred or the stream ended prematurely without producing a ChatCompletion.
    */
-  async finalChatCompletion(): Promise<ChatCompletion> {
+  async finalChatCompletion(): Promise<ParsedChatCompletion<ParsedT>> {
     await this.done();
     const completion = this._chatCompletions[this._chatCompletions.length - 1];
     if (!completion) throw new OpenAIError('stream ended without producing a ChatCompletion');
@@ -233,7 +105,11 @@ export abstract class AbstractChatCompletionRunner<
       const message = this.messages[i];
       if (isAssistantMessage(message)) {
         const { function_call, ...rest } = message;
-        const ret: ChatCompletionMessage = { ...rest, content: message.content ?? null };
+        const ret: ChatCompletionMessage = {
+          ...rest,
+          content: (message as ChatCompletionMessage).content ?? null,
+          refusal: (message as ChatCompletionMessage).refusal ?? null,
+        };
         if (function_call) {
           ret.function_call = function_call;
         }
@@ -284,6 +160,7 @@ export abstract class AbstractChatCompletionRunner<
       if (
         isToolMessage(message) &&
         message.content != null &&
+        typeof message.content === 'string' &&
         this.messages.some(
           (x) =>
             x.role === 'assistant' &&
@@ -327,75 +204,9 @@ export abstract class AbstractChatCompletionRunner<
     return [...this._chatCompletions];
   }
 
-  #handleError = (error: unknown) => {
-    this.#errored = true;
-    if (error instanceof Error && error.name === 'AbortError') {
-      error = new APIUserAbortError();
-    }
-    if (error instanceof APIUserAbortError) {
-      this.#aborted = true;
-      return this._emit('abort', error);
-    }
-    if (error instanceof OpenAIError) {
-      return this._emit('error', error);
-    }
-    if (error instanceof Error) {
-      const openAIError: OpenAIError = new OpenAIError(error.message);
-      // @ts-ignore
-      openAIError.cause = error;
-      return this._emit('error', openAIError);
-    }
-    return this._emit('error', new OpenAIError(String(error)));
-  };
-
-  protected _emit<Event extends keyof Events>(event: Event, ...args: EventParameters<Events, Event>) {
-    // make sure we don't emit any events after end
-    if (this.#ended) {
-      return;
-    }
-
-    if (event === 'end') {
-      this.#ended = true;
-      this.#resolveEndPromise();
-    }
-
-    const listeners: ListenersForEvent<Events, Event> | undefined = this.#listeners[event];
-    if (listeners) {
-      this.#listeners[event] = listeners.filter((l) => !l.once) as any;
-      listeners.forEach(({ listener }: any) => listener(...args));
-    }
-
-    if (event === 'abort') {
-      const error = args[0] as APIUserAbortError;
-      if (!this.#catchingPromiseCreated && !listeners?.length) {
-        Promise.reject(error);
-      }
-      this.#rejectConnectedPromise(error);
-      this.#rejectEndPromise(error);
-      this._emit('end');
-      return;
-    }
-
-    if (event === 'error') {
-      // NOTE: _emit('error', error) should only be called from #handleError().
-
-      const error = args[0] as OpenAIError;
-      if (!this.#catchingPromiseCreated && !listeners?.length) {
-        // Trigger an unhandled rejection if the user hasn't registered any error handlers.
-        // If you are seeing stack traces here, make sure to handle errors via either:
-        // - runner.on('error', () => ...)
-        // - await runner.done()
-        // - await runner.finalChatCompletion()
-        // - etc.
-        Promise.reject(error);
-      }
-      this.#rejectConnectedPromise(error);
-      this.#rejectEndPromise(error);
-      this._emit('end');
-    }
-  }
-
-  protected _emitFinal() {
+  protected override _emitFinal(
+    this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>,
+  ) {
     const completion = this._chatCompletions[this._chatCompletions.length - 1];
     if (completion) this._emit('finalChatCompletion', completion);
     const finalMessage = this.#getFinalMessage();
@@ -423,10 +234,10 @@ export abstract class AbstractChatCompletionRunner<
   }
 
   protected async _createChatCompletion(
-    completions: Completions,
+    client: OpenAI,
     params: ChatCompletionCreateParams,
     options?: Core.RequestOptions,
-  ): Promise<ChatCompletion> {
+  ): Promise<ParsedChatCompletion<ParsedT>> {
     const signal = options?.signal;
     if (signal) {
       if (signal.aborted) this.controller.abort();
@@ -434,27 +245,27 @@ export abstract class AbstractChatCompletionRunner<
     }
     this.#validateParams(params);
 
-    const chatCompletion = await completions.create(
+    const chatCompletion = await client.chat.completions.create(
       { ...params, stream: false },
       { ...options, signal: this.controller.signal },
     );
     this._connected();
-    return this._addChatCompletion(chatCompletion);
+    return this._addChatCompletion(parseChatCompletion(chatCompletion, params));
   }
 
   protected async _runChatCompletion(
-    completions: Completions,
+    client: OpenAI,
     params: ChatCompletionCreateParams,
     options?: Core.RequestOptions,
   ): Promise<ChatCompletion> {
     for (const message of params.messages) {
       this._addMessage(message, false);
     }
-    return await this._createChatCompletion(completions, params, options);
+    return await this._createChatCompletion(client, params, options);
   }
 
   protected async _runFunctions<FunctionsArgs extends BaseFunctionsArgs>(
-    completions: Completions,
+    client: OpenAI,
     params:
       | ChatCompletionFunctionRunnerParams<FunctionsArgs>
       | ChatCompletionStreamingFunctionRunnerParams<FunctionsArgs>,
@@ -484,7 +295,7 @@ export abstract class AbstractChatCompletionRunner<
 
     for (let i = 0; i < maxChatCompletions; ++i) {
       const chatCompletion: ChatCompletion = await this._createChatCompletion(
-        completions,
+        client,
         {
           ...restParams,
           function_call,
@@ -539,7 +350,7 @@ export abstract class AbstractChatCompletionRunner<
   }
 
   protected async _runTools<FunctionsArgs extends BaseFunctionsArgs>(
-    completions: Completions,
+    client: OpenAI,
     params:
       | ChatCompletionToolRunnerParams<FunctionsArgs>
       | ChatCompletionStreamingToolRunnerParams<FunctionsArgs>,
@@ -550,8 +361,31 @@ export abstract class AbstractChatCompletionRunner<
     const singleFunctionToCall = typeof tool_choice !== 'string' && tool_choice?.function?.name;
     const { maxChatCompletions = DEFAULT_MAX_CHAT_COMPLETIONS } = options || {};
 
+    // TODO(someday): clean this logic up
+    const inputTools = params.tools.map((tool): RunnableToolFunction<any> => {
+      if (isAutoParsableTool(tool)) {
+        if (!tool.$callback) {
+          throw new OpenAIError('Tool given to `.runTools()` that does not have an associated function');
+        }
+
+        return {
+          type: 'function',
+          function: {
+            function: tool.$callback,
+            name: tool.function.name,
+            description: tool.function.description || '',
+            parameters: tool.function.parameters as any,
+            parse: tool.$parseRaw,
+            strict: true,
+          },
+        };
+      }
+
+      return tool as any as RunnableToolFunction<any>;
+    });
+
     const functionsByName: Record<string, RunnableFunction<any>> = {};
-    for (const f of params.tools) {
+    for (const f of inputTools) {
       if (f.type === 'function') {
         functionsByName[f.function.name || f.function.function.name] = f.function;
       }
@@ -559,7 +393,7 @@ export abstract class AbstractChatCompletionRunner<
 
     const tools: ChatCompletionTool[] =
       'tools' in params ?
-        params.tools.map((t) =>
+        inputTools.map((t) =>
           t.type === 'function' ?
             {
               type: 'function',
@@ -567,6 +401,7 @@ export abstract class AbstractChatCompletionRunner<
                 name: t.function.name || t.function.function.name,
                 parameters: t.function.parameters as Record<string, unknown>,
                 description: t.function.description,
+                strict: t.function.strict,
               },
             }
           : (t as unknown as ChatCompletionTool),
@@ -579,7 +414,7 @@ export abstract class AbstractChatCompletionRunner<
 
     for (let i = 0; i < maxChatCompletions; ++i) {
       const chatCompletion: ChatCompletion = await this._createChatCompletion(
-        completions,
+        client,
         {
           ...restParams,
           tool_choice,
@@ -592,7 +427,7 @@ export abstract class AbstractChatCompletionRunner<
       if (!message) {
         throw new OpenAIError(`missing message in ChatCompletion response`);
       }
-      if (!message.tool_calls) {
+      if (!message.tool_calls?.length) {
         return;
       }
 
@@ -603,8 +438,10 @@ export abstract class AbstractChatCompletionRunner<
         const fn = functionsByName[name];
 
         if (!fn) {
-          const content = `Invalid tool_call: ${JSON.stringify(name)}. Available options are: ${tools
-            .map((f) => JSON.stringify(f.function.name))
+          const content = `Invalid tool_call: ${JSON.stringify(name)}. Available options are: ${Object.keys(
+            functionsByName,
+          )
+            .map((name) => JSON.stringify(name))
             .join(', ')}. Please try again`;
 
           this._addMessage({ role, tool_call_id, content });
@@ -650,27 +487,7 @@ export abstract class AbstractChatCompletionRunner<
   }
 }
 
-type CustomEvents<Event extends string> = {
-  [k in Event]: k extends keyof AbstractChatCompletionRunnerEvents ? AbstractChatCompletionRunnerEvents[k]
-  : (...args: any[]) => void;
-};
-
-type ListenerForEvent<Events extends CustomEvents<any>, Event extends keyof Events> = Event extends (
-  keyof AbstractChatCompletionRunnerEvents
-) ?
-  AbstractChatCompletionRunnerEvents[Event]
-: Events[Event];
-
-type ListenersForEvent<Events extends CustomEvents<any>, Event extends keyof Events> = Array<{
-  listener: ListenerForEvent<Events, Event>;
-  once?: boolean;
-}>;
-type EventParameters<Events extends CustomEvents<any>, Event extends keyof Events> = Parameters<
-  ListenerForEvent<Events, Event>
->;
-
-export interface AbstractChatCompletionRunnerEvents {
-  connect: () => void;
+export interface AbstractChatCompletionRunnerEvents extends BaseEvents {
   functionCall: (functionCall: ChatCompletionMessage.FunctionCall) => void;
   message: (message: ChatCompletionMessageParam) => void;
   chatCompletion: (completion: ChatCompletion) => void;
@@ -680,8 +497,5 @@ export interface AbstractChatCompletionRunnerEvents {
   finalFunctionCall: (functionCall: ChatCompletionMessage.FunctionCall) => void;
   functionCallResult: (content: string) => void;
   finalFunctionCallResult: (content: string) => void;
-  error: (error: OpenAIError) => void;
-  abort: (error: APIUserAbortError) => void;
-  end: () => void;
   totalUsage: (usage: CompletionUsage) => void;
 }