openai 7.3.0 → 7.5.0

package/src/lib/jsonschema.ts

@@ -8,21 +8,15 @@
 // --------------------------------------------------------------------------------------------------
 
 /**
- * Primitive type
+ * A JSON value category accepted by a schema's `type` keyword.
  * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
  */
 export type JSONSchemaTypeName =
-  | ({} & string)
-  | 'string'
-  | 'number'
-  | 'integer'
-  | 'boolean'
-  | 'object'
-  | 'array'
-  | 'null';
+  // oxlint-disable-next-line typescript/ban-types -- The empty intersection preserves literal-union widening for arbitrary JSON Schema type names.
+  ({} & string) | 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
 
 /**
- * Primitive type
+ * Any JSON-serializable primitive, object, array, or `null` value.
  * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
  */
 export type JSONSchemaType =
@@ -33,14 +27,17 @@ export type JSONSchemaType =
   | JSONSchemaArray
   | null;
 
-// Workaround for infinite type recursion
+/** A JSON object whose property values may themselves be nested JSON values. */
 export interface JSONSchemaObject {
+  /** A JSON-serializable property value addressed by its object key. */
   [key: string]: JSONSchemaType;
 }
 
-// Workaround for infinite type recursion
-// https://github.com/Microsoft/TypeScript/issues/3496#issuecomment-128553540
-export interface JSONSchemaArray extends Array<JSONSchemaType> {}
+/** An array of JSON-serializable values, including nested arrays and objects. */
+export interface JSONSchemaArray extends Array<JSONSchemaType> {
+  /** The JSON-serializable value at a numeric array position. */
+  [index: number]: JSONSchemaType;
+}
 
 /**
  * Meta schema
@@ -60,116 +57,159 @@ export type JSONSchemaVersion = string;
  * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
  */
 export type JSONSchemaDefinition = JSONSchema | boolean;
+/** A JSON Schema document or subschema accepted by SDK function and structured-output helpers. */
 export interface JSONSchema {
+  /** URI identifying the JSON Schema dialect used by this document. */
   $schema?: JSONSchemaVersion | undefined;
+  /** URI identifying this schema resource and establishing its reference base. */
   $id?: string | undefined;
+  /** Implementation-facing comment that does not affect instance validation. */
   $comment?: string | undefined;
 
   /**
+   * JSON value category, or categories, accepted by this schema.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1
    */
   type?: JSONSchemaTypeName | JSONSchemaTypeName[] | undefined;
+  /** The complete set of literal values accepted by this schema. */
   enum?: JSONSchemaType[] | undefined;
+  /** The single literal value accepted by this schema. */
   const?: JSONSchemaType | undefined;
 
   /**
+   * Requires a numeric instance to be an exact multiple of this value.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.2
    */
   multipleOf?: number | undefined;
+  /** The greatest numeric value accepted, including the boundary. */
   maximum?: number | undefined;
+  /** The upper numeric boundary, which the instance must be strictly less than. */
   exclusiveMaximum?: number | undefined;
+  /** The smallest numeric value accepted, including the boundary. */
   minimum?: number | undefined;
+  /** The lower numeric boundary, which the instance must be strictly greater than. */
   exclusiveMinimum?: number | undefined;
 
   /**
+   * The maximum number of Unicode characters accepted in a string.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.3
    */
   maxLength?: number | undefined;
+  /** The minimum number of Unicode characters required in a string. */
   minLength?: number | undefined;
+  /** A regular expression that matching string instances must satisfy. */
   pattern?: string | undefined;
+  /** Encoding used by a string that represents non-text content, such as `base64`. */
   contentEncoding?: string | undefined;
+  /** Media type describing content represented by a string instance. */
   contentMediaType?: string | undefined;
 
   /**
+   * A schema shared by array items, or position-specific schemas for tuple items.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.4
    */
   items?: JSONSchemaDefinition | JSONSchemaDefinition[] | undefined;
+  /** Schema applied to array items beyond the explicitly defined tuple positions. */
   additionalItems?: JSONSchemaDefinition | undefined;
+  /** The maximum number of items accepted in an array. */
   maxItems?: number | undefined;
+  /** The minimum number of items required in an array. */
   minItems?: number | undefined;
+  /** Whether every array item must be distinct from every other item. */
   uniqueItems?: boolean | undefined;
+  /** A schema that at least one array item must satisfy. */
   contains?: JSONSchemaDefinition | undefined;
 
   /**
+   * The maximum number of properties accepted in an object.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.5
    */
   maxProperties?: number | undefined;
+  /** The minimum number of properties required in an object. */
   minProperties?: number | undefined;
+  /** Property names that must be present in a valid object. */
   required?: string[] | undefined;
-  properties?:
-    | {
-        [key: string]: JSONSchemaDefinition;
-      }
-    | undefined;
-  patternProperties?:
-    | {
-        [key: string]: JSONSchemaDefinition;
-      }
-    | undefined;
+  /** Schemas associated with explicitly named object properties. */
+  properties?: Record<string, JSONSchemaDefinition> | undefined;
+  /** Schemas applied to properties whose names match each regular-expression key. */
+  patternProperties?: Record<string, JSONSchemaDefinition> | undefined;
+  /** Schema for properties not covered by `properties` or `patternProperties`. */
   additionalProperties?: JSONSchemaDefinition | undefined;
+  /** Schema that every property name in an object must satisfy. */
   propertyNames?: JSONSchemaDefinition | undefined;
 
   /**
+   * Condition that selects the `then` or `else` validation schema.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.6
    */
   if?: JSONSchemaDefinition | undefined;
+  /** Schema applied when the instance satisfies the `if` condition. */
   then?: JSONSchemaDefinition | undefined;
+  /** Schema applied when the instance does not satisfy the `if` condition. */
   else?: JSONSchemaDefinition | undefined;
 
   /**
+   * Subschemas that the instance must all satisfy.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.7
    */
   allOf?: JSONSchemaDefinition[] | undefined;
+  /** Alternative subschemas, at least one of which the instance must satisfy. */
   anyOf?: JSONSchemaDefinition[] | undefined;
+  /** Alternative subschemas, exactly one of which the instance must satisfy. */
   oneOf?: JSONSchemaDefinition[] | undefined;
+  /** A subschema that the instance must not satisfy. */
   not?: JSONSchemaDefinition | undefined;
 
   /**
+   * Reusable subschemas that can be targeted by local `$ref` pointers.
+   *
    * @see https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.4
    */
-  $defs?:
-    | {
-        [key: string]: JSONSchemaDefinition;
-      }
-    | undefined;
+  $defs?: Record<string, JSONSchemaDefinition> | undefined;
 
   /**
+   * Legacy reusable subschemas that can be targeted by local `$ref` pointers.
+   *
    * @deprecated Use $defs instead (draft 2019-09+)
    * @see https://tools.ietf.org/doc/html/draft-handrews-json-schema-validation-01#page-22
    */
-  definitions?:
-    | {
-        [key: string]: JSONSchemaDefinition;
-      }
-    | undefined;
+  definitions?: Record<string, JSONSchemaDefinition> | undefined;
 
   /**
+   * URI reference identifying another schema to apply at this position.
+   *
    * @see https://json-schema.org/draft/2020-12/json-schema-core#ref
    */
   $ref?: string | undefined;
 
   /**
+   * Semantic format annotation, such as `date-time`, `email`, or `uri`.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7
    */
   format?: string | undefined;
 
   /**
+   * A short, human-readable title describing the schema.
+   *
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-10
    */
   title?: string | undefined;
+  /** Human-readable explanation of the value accepted by the schema. */
   description?: string | undefined;
+  /** Suggested value to use when an instance value is not provided. */
   default?: JSONSchemaType | undefined;
+  /** Whether this value should be treated as read-only by consumers. */
   readOnly?: boolean | undefined;
+  /** Whether this value should be treated as write-only by consumers. */
   writeOnly?: boolean | undefined;
+  /** Representative example value or values illustrating this schema. */
   examples?: JSONSchemaType | undefined;
 }

package/src/lib/parser.ts

@@ -1,23 +1,25 @@
 import { ContentFilterFinishReasonError, LengthFinishReasonError, OpenAIError } from '../error';
-import {
+import type {
   ChatCompletion,
   ChatCompletionCreateParams,
   ChatCompletionCreateParamsBase,
   ChatCompletionFunctionTool,
   ChatCompletionMessage,
   ChatCompletionMessageFunctionToolCall,
+  ChatCompletionMessageToolCall,
   ChatCompletionStreamingToolRunnerParams,
   ChatCompletionStreamingToolRunnerParamsWithContext,
   ChatCompletionStreamParams,
   ChatCompletionToolRunnerParams,
   ChatCompletionToolRunnerParamsWithContext,
   ParsedChatCompletion,
+  ParsedChatCompletionMessageToolCall,
   ParsedChoice,
-  ParsedFunctionToolCall,
 } from '../resources/chat/completions';
-import { type ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
-import { ResponseFormatJSONSchema } from '../resources/shared';
+import type { ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
+import type { ResponseFormatJSONSchema } from '../resources/shared';
 
+/** Chat completion creation, parsing, streaming, or tool-runner request parameters. */
 type AnyChatCompletionCreateParams =
   | ChatCompletionCreateParams
   | ChatCompletionToolRunnerParams<any>
@@ -26,24 +28,49 @@ type AnyChatCompletionCreateParams =
   | ChatCompletionStreamingToolRunnerParamsWithContext<any, any>
   | ChatCompletionStreamParams;
 
+/** Extracts the element type from an array while preserving non-array values. */
 type Unpacked<T> = T extends (infer U)[] ? U : T;
 
+/** One optional tool definition accepted by a chat completion request. */
 type ToolCall = Unpacked<ChatCompletionCreateParamsBase['tools']>;
 
+/** Returns whether an optional chat completion tool contains a function-tool definition. */
 export function isChatCompletionFunctionTool(tool: ToolCall): tool is ChatCompletionFunctionTool {
   return tool !== undefined && 'function' in tool && tool.function !== undefined;
 }
 
+/** Infers parsed output for each member of a possibly optional response-format union. */
+type ParsedResponseFormat<Format> = [Format] extends [never]
+  ? null
+  : Format extends AutoParseableResponseFormat<infer ParsedT>
+    ? ParsedT
+    : Format extends ResponseFormatJSONSchema
+      ? unknown
+      : null;
+
+/**
+ * Resolves the type of `message.parsed` / `content[].parsed` for the given params.
+ *
+ * This must stay in sync with {@link isParseableResponseFormat} and
+ * {@link parseResponseFormatContent}: formats built by an SDK helper carry their
+ * parsed type in the brand, while a raw `{ type: 'json_schema' }` format is parsed
+ * with `JSON.parse()` and so can only be described as `unknown`.
+ */
 export type ExtractParsedContentFromParams<Params extends AnyChatCompletionCreateParams> =
-  Params['response_format'] extends AutoParseableResponseFormat<infer P> ? P : null;
+  ParsedResponseFormat<Params['response_format']>;
 
+/** A Chat Completions JSON Schema response format with an attached structured-output parser. */
 export type AutoParseableResponseFormat<ParsedT> = ResponseFormatJSONSchema & {
+  /** Type-only marker used to infer the parser's output; this property does not exist at runtime. */
   __output: ParsedT; // type-level only
 
+  /** Non-enumerable SDK marker identifying a response format with an attached parser. */
   $brand: 'auto-parseable-response-format';
+  /** Parses the completed raw assistant text into the response format's output type. */
   $parseRaw(content: string): ParsedT;
 };
 
+/** Copies a JSON Schema response format and attaches a non-enumerable structured-output parser. */
 export function makeParseableResponseFormat<ParsedT>(
   response_format: ResponseFormatJSONSchema,
   parser: (content: string) => ParsedT,
@@ -64,13 +91,18 @@ export function makeParseableResponseFormat<ParsedT>(
   return obj as AutoParseableResponseFormat<ParsedT>;
 }
 
+/** A Responses API JSON Schema text format with an attached structured-output parser. */
 export type AutoParseableTextFormat<ParsedT> = ResponseFormatTextJSONSchemaConfig & {
+  /** Type-only marker used to infer the parser's output; this property does not exist at runtime. */
   __output: ParsedT; // type-level only
 
+  /** Non-enumerable SDK marker identifying a text format with an attached parser. */
   $brand: 'auto-parseable-response-format';
+  /** Parses completed output text into the text format's structured output type. */
   $parseRaw(content: string): ParsedT;
 };
 
+/** Copies a Responses API text format and attaches a non-enumerable structured-output parser. */
 export function makeParseableTextFormat<ParsedT>(
   response_format: ResponseFormatTextJSONSchemaConfig,
   parser: (content: string) => ParsedT,
@@ -91,38 +123,95 @@ export function makeParseableTextFormat<ParsedT>(
   return obj as AutoParseableTextFormat<ParsedT>;
 }
 
+/**
+ * Whether the given format was built by an SDK helper (e.g. `zodResponseFormat()`)
+ * and therefore carries its own `$parseRaw` callback.
+ *
+ * Prefer {@link isParseableResponseFormat} when deciding whether output should be
+ * parsed at all; raw `{ type: 'json_schema' }` formats are parsed too, but are not
+ * branded.
+ */
 export function isAutoParsableResponseFormat<ParsedT>(
   response_format: any,
 ): response_format is AutoParseableResponseFormat<ParsedT> {
   return response_format?.['$brand'] === 'auto-parseable-response-format';
 }
 
+/**
+ * The canonical definition of an auto-parseable response format, covering both the
+ * Chat Completions `response_format` and the Responses `text.format` shapes.
+ *
+ * Every gate that decides whether output should be parsed must go through this
+ * predicate so the runtime, the streaming events and
+ * {@link ExtractParsedContentFromParams} cannot drift apart.
+ */
+export function isParseableResponseFormat(format: unknown): boolean {
+  return isAutoParsableResponseFormat(format) || (format as { type?: string } | null)?.type === 'json_schema';
+}
+
+/**
+ * The canonical parser for auto-parseable response formats. This is the only place
+ * that chooses between an existing `$parseRaw` callback and generic `JSON.parse()`.
+ *
+ * Returns `null` for formats that are not auto-parseable.
+ */
+export function parseResponseFormatContent<ParsedT>(format: unknown, content: string): ParsedT | null {
+  if (!isParseableResponseFormat(format)) {
+    return null;
+  }
+
+  if (
+    typeof format === 'object' &&
+    format !== null &&
+    '$parseRaw' in format &&
+    typeof format.$parseRaw === 'function'
+  ) {
+    return format.$parseRaw(content) as ParsedT;
+  }
+
+  return JSON.parse(content) as ParsedT;
+}
+
+/** Type-level details used to infer a chat function tool's parser and execution callback. */
 type ToolOptions = {
+  /** Model-visible function name used to match generated tool calls. */
   name: string;
+  /** Parsed argument value accepted by the optional execution callback. */
   arguments: any;
+  /** Optional callback invoked by chat completion tool-running helpers. */
   function?: ((args: any) => any) | undefined;
 };
 
+/** A Chat Completions function tool with an argument parser and optional executable callback. */
 export type AutoParseableTool<
   OptionsT extends ToolOptions,
-  HasFunction = OptionsT['function'] extends Function ? true : false,
+  HasFunction = OptionsT['function'] extends (...args: never[]) => unknown ? true : false,
 > = ChatCompletionFunctionTool & {
+  /** Type-only marker for parsed tool arguments; this property does not exist at runtime. */
   __arguments: OptionsT['arguments']; // type-level only
+  /** Type-only marker for the tool name; this property does not exist at runtime. */
   __name: OptionsT['name']; // type-level only
+  /** Type-only marker indicating whether a runnable callback was supplied. */
   __hasFunction: HasFunction; // type-level only
 
+  /** Non-enumerable SDK marker identifying a tool with an attached argument parser. */
   $brand: 'auto-parseable-tool';
+  /** Optional runnable callback used by `.runTools()` after arguments are parsed. */
   $callback: ((args: OptionsT['arguments']) => any) | undefined;
+  /** Parses the raw JSON argument string into the callback's typed argument value. */
   $parseRaw(args: string): OptionsT['arguments'];
 };
 
+/** Copies a function tool and attaches non-enumerable parsing and callback metadata. */
 export function makeParseableTool<OptionsT extends ToolOptions>(
   tool: ChatCompletionFunctionTool,
   {
     parser,
     callback,
   }: {
+    /** Converts the raw JSON argument string into the tool's typed argument value. */
     parser: (content: string) => OptionsT['arguments'];
+    /** Optional callback invoked by a chat completion tool runner. */
     callback: ((args: any) => any) | undefined;
   },
 ): AutoParseableTool<OptionsT['arguments']> {
@@ -146,10 +235,15 @@ export function makeParseableTool<OptionsT extends ToolOptions>(
   return obj as AutoParseableTool<OptionsT['arguments']>;
 }
 
+/** Returns whether a Chat Completions tool carries the SDK's argument-parser marker. */
 export function isAutoParsableTool(tool: any): tool is AutoParseableTool<any> {
   return tool?.['$brand'] === 'auto-parseable-tool';
 }
 
+/**
+ * Adds parsed-content fields to a chat completion, invoking parsers only when the
+ * request includes an auto-parseable response format or a strict function tool.
+ */
 export function maybeParseChatCompletion<
   Params extends ChatCompletionCreateParams | null,
   ParsedT = Params extends null ? null : ExtractParsedContentFromParams<NonNullable<Params>>,
@@ -157,33 +251,36 @@ export function maybeParseChatCompletion<
   if (!params || !hasAutoParseableInput(params)) {
     return {
       ...completion,
-      choices: completion.choices.map((choice) => {
-        assertToolCallsAreChatCompletionFunctionToolCalls(choice.message.tool_calls);
-
-        return {
-          ...choice,
-          message: {
-            ...choice.message,
-            parsed: null,
-            ...(choice.message.tool_calls ?
-              {
+      choices: completion.choices.map((choice) => ({
+        ...choice,
+        message: {
+          ...choice.message,
+          parsed: null,
+          ...(choice.message.tool_calls
+            ? {
                 tool_calls: choice.message.tool_calls,
               }
             : undefined),
-          },
-        };
-      }),
-    } as ParsedChatCompletion<ParsedT>;
+        },
+      })),
+    };
   }
 
   return parseChatCompletion(completion, params);
 }
 
+/**
+ * Parses structured assistant content and strict function-tool arguments.
+ *
+ * @throws {LengthFinishReasonError} If generation stopped at its token limit.
+ * @throws {ContentFilterFinishReasonError} If generation stopped because of content filtering.
+ * @throws {OpenAIError} If the completion contains an unsupported tool-call type.
+ */
 export function parseChatCompletion<
   Params extends ChatCompletionCreateParams,
   ParsedT = ExtractParsedContentFromParams<Params>,
 >(completion: ChatCompletion, params: Params): ParsedChatCompletion<ParsedT> {
-  const choices: Array<ParsedChoice<ParsedT>> = completion.choices.map((choice): ParsedChoice<ParsedT> => {
+  const choices: ParsedChoice<ParsedT>[] = completion.choices.map((choice): ParsedChoice<ParsedT> => {
     if (choice.finish_reason === 'length') {
       throw new LengthFinishReasonError();
     }
@@ -192,24 +289,26 @@ export function parseChatCompletion<
       throw new ContentFilterFinishReasonError();
     }
 
-    assertToolCallsAreChatCompletionFunctionToolCalls(choice.message.tool_calls);
-
     return {
       ...choice,
       message: {
         ...choice.message,
-        ...(choice.message.tool_calls ?
-          {
-            tool_calls:
-              choice.message.tool_calls?.map((toolCall) => parseToolCall(params, toolCall)) ?? undefined,
-          }
-        : undefined),
+        ...(choice.message.tool_calls
+          ? {
+              tool_calls:
+                choice.message.tool_calls?.map((toolCall) => parseToolCall(params, toolCall)) ?? undefined,
+            }
+          : undefined),
         parsed:
-          choice.message.content && !choice.message.refusal ?
-            parseResponseFormat(params, choice.message.content)
-          : null,
+          choice.message.content !== null &&
+          choice.message.content !== undefined &&
+          !choice.message.refusal &&
+          (choice.message.content !== '' ||
+            (!choice.message.tool_calls?.length && !choice.message.function_call))
+            ? parseResponseFormat(params, choice.message.content)
+            : null,
       },
-    } as ParsedChoice<ParsedT>;
+    };
   });
 
   return { ...completion, choices };
@@ -219,54 +318,60 @@ function parseResponseFormat<
   Params extends ChatCompletionCreateParams,
   ParsedT = ExtractParsedContentFromParams<Params>,
 >(params: Params, content: string): ParsedT | null {
-  if (params.response_format?.type !== 'json_schema') {
-    return null;
-  }
-
-  if (params.response_format?.type === 'json_schema') {
-    if ('$parseRaw' in params.response_format) {
-      const response_format = params.response_format as AutoParseableResponseFormat<ParsedT>;
-
-      return response_format.$parseRaw(content);
-    }
-
-    return JSON.parse(content);
-  }
-
-  return null;
+  return parseResponseFormatContent<ParsedT>(params.response_format, content);
 }
 
 function parseToolCall<Params extends ChatCompletionCreateParams>(
   params: Params,
-  toolCall: ChatCompletionMessageFunctionToolCall,
-): ParsedFunctionToolCall {
+  toolCall: ChatCompletionMessageToolCall,
+): ParsedChatCompletionMessageToolCall {
+  if (toolCall.type === 'custom') {
+    return toolCall;
+  }
+
+  if (toolCall.type !== 'function') {
+    const unsupportedType = (toolCall as { type: string }).type;
+    throw new OpenAIError(
+      `Currently only \`function\` and \`custom\` tool calls are supported; Received \`${unsupportedType}\``,
+    );
+  }
+
   const inputTool = params.tools?.find(
     (inputTool) =>
       isChatCompletionFunctionTool(inputTool) && inputTool.function?.name === toolCall.function.name,
   ) as ChatCompletionFunctionTool | undefined; // TS doesn't narrow based on isChatCompletionTool
+  let parsedArguments: unknown = null;
+  if (isAutoParsableTool(inputTool)) {
+    parsedArguments = inputTool.$parseRaw(toolCall.function.arguments);
+  } else if (inputTool?.function.strict) {
+    parsedArguments = JSON.parse(toolCall.function.arguments);
+  }
+
   return {
     ...toolCall,
     function: {
       ...toolCall.function,
-      parsed_arguments:
-        isAutoParsableTool(inputTool) ? inputTool.$parseRaw(toolCall.function.arguments)
-        : inputTool?.function.strict ? JSON.parse(toolCall.function.arguments)
-        : null,
+      parsed_arguments: parsedArguments,
     },
   };
 }
 
+/** Returns whether a tool call matches a strict or auto-parseable function in the request. */
 export function shouldParseToolCall(
   params: ChatCompletionCreateParams | null | undefined,
-  toolCall: ChatCompletionMessageFunctionToolCall,
+  // accepts partially accumulated tool calls so streaming snapshots can be checked as they build up
+  toolCall: {
+    type?: ChatCompletionMessageToolCall['type'];
+    function?: { name?: string };
+  },
 ): boolean {
-  if (!params || !('tools' in params) || !params.tools) {
+  if (!params || !('tools' in params) || !params.tools || toolCall.type !== 'function') {
     return false;
   }
 
   const inputTool = params.tools?.find(
     (inputTool) =>
-      isChatCompletionFunctionTool(inputTool) && inputTool.function?.name === toolCall.function.name,
+      isChatCompletionFunctionTool(inputTool) && inputTool.function?.name === toolCall.function?.name,
   );
   return (
     isChatCompletionFunctionTool(inputTool) &&
@@ -274,8 +379,9 @@ export function shouldParseToolCall(
   );
 }
 
+/** Returns whether the request contains an auto-parseable response format or strict function tool. */
 export function hasAutoParseableInput(params: AnyChatCompletionCreateParams): boolean {
-  if (isAutoParsableResponseFormat(params.response_format)) {
+  if (isParseableResponseFormat(params.response_format)) {
     return true;
   }
 
@@ -286,6 +392,11 @@ export function hasAutoParseableInput(params: AnyChatCompletionCreateParams): bo
   );
 }
 
+/**
+ * Narrows completion tool calls to function calls supported by parsing helpers.
+ *
+ * @throws {OpenAIError} If any tool call has a non-function type.
+ */
 export function assertToolCallsAreChatCompletionFunctionToolCalls(
   toolCalls: ChatCompletionMessage['tool_calls'],
 ): asserts toolCalls is ChatCompletionMessageFunctionToolCall[] {
@@ -298,11 +409,21 @@ export function assertToolCallsAreChatCompletionFunctionToolCalls(
   }
 }
 
+/**
+ * Validates strict function tools while preserving supported custom tools.
+ *
+ * @throws {OpenAIError} If a tool is unsupported or a function is missing `strict: true`.
+ */
 export function validateInputTools(tools: ChatCompletionCreateParamsBase['tools']) {
   for (const tool of tools ?? []) {
+    if (tool.type === 'custom') {
+      continue;
+    }
+
     if (tool.type !== 'function') {
+      const unsupportedType = (tool as { type: string }).type;
       throw new OpenAIError(
-        `Currently only \`function\` tool types support auto-parsing; Received \`${tool.type}\``,
+        `Currently only \`function\` and \`custom\` tool types are supported; Received \`${unsupportedType}\``,
       );
     }