@depup/openai 6.31.0-depup.0

package/src/lib/RunnableFunction.ts

@@ -0,0 +1,114 @@
+import { type ChatCompletionRunner } from './ChatCompletionRunner';
+import { type ChatCompletionStreamingRunner } from './ChatCompletionStreamingRunner';
+import { JSONSchema } from './jsonschema';
+
+type PromiseOrValue<T> = T | Promise<T>;
+
+export type RunnableFunctionWithParse<Args extends object> = {
+  /**
+   * @param args the return value from `parse`.
+   * @param runner the runner evaluating this callback.
+   * @returns a string to send back to OpenAI.
+   */
+  function: (
+    args: Args,
+    runner: ChatCompletionRunner<unknown> | ChatCompletionStreamingRunner<unknown>,
+  ) => PromiseOrValue<unknown>;
+  /**
+   * @param input the raw args from the OpenAI function call.
+   * @returns the parsed arguments to pass to `function`
+   */
+  parse: (input: string) => PromiseOrValue<Args>;
+  /**
+   * The parameters the function accepts, describes as a JSON Schema object.
+   */
+  parameters: JSONSchema;
+  /**
+   * A description of what the function does, used by the model to choose when and how to call the function.
+   */
+  description: string;
+  /**
+   * The name of the function to be called. Will default to function.name if omitted.
+   */
+  name?: string | undefined;
+  strict?: boolean | undefined;
+};
+
+export type RunnableFunctionWithoutParse = {
+  /**
+   * @param args the raw args from the OpenAI function call.
+   * @returns a string to send back to OpenAI
+   */
+  function: (
+    args: string,
+    runner: ChatCompletionRunner<unknown> | ChatCompletionStreamingRunner<unknown>,
+  ) => PromiseOrValue<unknown>;
+  /**
+   * The parameters the function accepts, describes as a JSON Schema object.
+   */
+  parameters: JSONSchema;
+  /**
+   * A description of what the function does, used by the model to choose when and how to call the function.
+   */
+  description: string;
+  /**
+   * The name of the function to be called. Will default to function.name if omitted.
+   */
+  name?: string | undefined;
+  strict?: boolean | undefined;
+};
+
+export type RunnableFunction<Args extends object | string> =
+  Args extends string ? RunnableFunctionWithoutParse
+  : Args extends object ? RunnableFunctionWithParse<Args>
+  : never;
+
+export type RunnableToolFunction<Args extends object | string> =
+  Args extends string ? RunnableToolFunctionWithoutParse
+  : Args extends object ? RunnableToolFunctionWithParse<Args>
+  : never;
+
+export type RunnableToolFunctionWithoutParse = {
+  type: 'function';
+  function: RunnableFunctionWithoutParse;
+};
+export type RunnableToolFunctionWithParse<Args extends object> = {
+  type: 'function';
+  function: RunnableFunctionWithParse<Args>;
+};
+
+export function isRunnableFunctionWithParse<Args extends object>(
+  fn: any,
+): fn is RunnableFunctionWithParse<Args> {
+  return typeof (fn as any).parse === 'function';
+}
+
+export type BaseFunctionsArgs = readonly (object | string)[];
+
+export type RunnableFunctions<FunctionsArgs extends BaseFunctionsArgs> =
+  [any[]] extends [FunctionsArgs] ? readonly RunnableFunction<any>[]
+  : {
+      [Index in keyof FunctionsArgs]: Index extends number ? RunnableFunction<FunctionsArgs[Index]>
+      : FunctionsArgs[Index];
+    };
+
+export type RunnableTools<FunctionsArgs extends BaseFunctionsArgs> =
+  [any[]] extends [FunctionsArgs] ? readonly RunnableToolFunction<any>[]
+  : {
+      [Index in keyof FunctionsArgs]: Index extends number ? RunnableToolFunction<FunctionsArgs[Index]>
+      : FunctionsArgs[Index];
+    };
+
+/**
+ * This is helper class for passing a `function` and `parse` where the `function`
+ * argument type matches the `parse` return type.
+ */
+export class ParsingToolFunction<Args extends object> {
+  type: 'function';
+  function: RunnableFunctionWithParse<Args>;
+
+  constructor(input: RunnableFunctionWithParse<Args>) {
+    this.type = 'function';
+    this.function = input;
+  }
+}

package/src/lib/Util.ts

@@ -0,0 +1,23 @@
+/**
+ * Like `Promise.allSettled()` but throws an error if any promises are rejected.
+ */
+export const allSettledWithThrow = async <R>(promises: Promise<R>[]): Promise<R[]> => {
+  const results = await Promise.allSettled(promises);
+  const rejected = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+  if (rejected.length) {
+    for (const result of rejected) {
+      console.error(result.reason);
+    }
+
+    throw new Error(`${rejected.length} promise(s) failed - see the above errors`);
+  }
+
+  // Note: TS was complaining about using `.filter().map()` here for some reason
+  const values: R[] = [];
+  for (const result of results) {
+    if (result.status === 'fulfilled') {
+      values.push(result.value);
+    }
+  }
+  return values;
+};

package/src/lib/chatCompletionUtils.ts

@@ -0,0 +1,21 @@
+import {
+  type ChatCompletionAssistantMessageParam,
+  type ChatCompletionMessageParam,
+  type ChatCompletionToolMessageParam,
+} from '../resources';
+
+export const isAssistantMessage = (
+  message: ChatCompletionMessageParam | null | undefined,
+): message is ChatCompletionAssistantMessageParam => {
+  return message?.role === 'assistant';
+};
+
+export const isToolMessage = (
+  message: ChatCompletionMessageParam | null | undefined,
+): message is ChatCompletionToolMessageParam => {
+  return message?.role === 'tool';
+};
+
+export function isPresent<T>(obj: T | null | undefined): obj is T {
+  return obj != null;
+}

package/src/lib/jsonschema.ts

@@ -0,0 +1,172 @@
+// File mostly copied from @types/json-schema, but stripped down a bit for brevity
+// https://github.com/DefinitelyTyped/DefinitelyTyped/blob/817274f3280152ba2929a6067c93df8b34c4c9aa/types/json-schema/index.d.ts
+//
+// ==================================================================================================
+// JSON Schema Draft 07
+// ==================================================================================================
+// https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+// --------------------------------------------------------------------------------------------------
+
+/**
+ * Primitive type
+ * @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';
+
+/**
+ * Primitive type
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ */
+export type JSONSchemaType =
+  | string //
+  | number
+  | boolean
+  | JSONSchemaObject
+  | JSONSchemaArray
+  | null;
+
+// Workaround for infinite type recursion
+export interface JSONSchemaObject {
+  [key: string]: JSONSchemaType;
+}
+
+// Workaround for infinite type recursion
+// https://github.com/Microsoft/TypeScript/issues/3496#issuecomment-128553540
+export interface JSONSchemaArray extends Array<JSONSchemaType> {}
+
+/**
+ * Meta schema
+ *
+ * Recommended values:
+ * - 'http://json-schema.org/schema#'
+ * - 'http://json-schema.org/hyper-schema#'
+ * - 'http://json-schema.org/draft-07/schema#'
+ * - 'http://json-schema.org/draft-07/hyper-schema#'
+ *
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-5
+ */
+export type JSONSchemaVersion = string;
+
+/**
+ * JSON Schema v7
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+ */
+export type JSONSchemaDefinition = JSONSchema | boolean;
+export interface JSONSchema {
+  $id?: string | undefined;
+  $comment?: string | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1
+   */
+  type?: JSONSchemaTypeName | JSONSchemaTypeName[] | undefined;
+  enum?: JSONSchemaType[] | undefined;
+  const?: JSONSchemaType | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.2
+   */
+  multipleOf?: number | undefined;
+  maximum?: number | undefined;
+  exclusiveMaximum?: number | undefined;
+  minimum?: number | undefined;
+  exclusiveMinimum?: number | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.3
+   */
+  maxLength?: number | undefined;
+  minLength?: number | undefined;
+  pattern?: string | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.4
+   */
+  items?: JSONSchemaDefinition | JSONSchemaDefinition[] | undefined;
+  additionalItems?: JSONSchemaDefinition | undefined;
+  maxItems?: number | undefined;
+  minItems?: number | undefined;
+  uniqueItems?: boolean | undefined;
+  contains?: JSONSchemaDefinition | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.5
+   */
+  maxProperties?: number | undefined;
+  minProperties?: number | undefined;
+  required?: string[] | undefined;
+  properties?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+  patternProperties?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+  additionalProperties?: JSONSchemaDefinition | undefined;
+  propertyNames?: JSONSchemaDefinition | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.6
+   */
+  if?: JSONSchemaDefinition | undefined;
+  then?: JSONSchemaDefinition | undefined;
+  else?: JSONSchemaDefinition | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.7
+   */
+  allOf?: JSONSchemaDefinition[] | undefined;
+  anyOf?: JSONSchemaDefinition[] | undefined;
+  oneOf?: JSONSchemaDefinition[] | undefined;
+  not?: JSONSchemaDefinition | undefined;
+
+  /**
+   * @see https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.4
+   */
+  $defs?:
+    | {
+        [key: string]: JSONSchemaDefinition;
+      }
+    | undefined;
+
+  /**
+   * @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;
+
+  /**
+   * @see https://json-schema.org/draft/2020-12/json-schema-core#ref
+   */
+  $ref?: string | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7
+   */
+  format?: string | undefined;
+
+  /**
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-10
+   */
+  title?: string | undefined;
+  description?: string | undefined;
+  default?: JSONSchemaType | undefined;
+  readOnly?: boolean | undefined;
+  writeOnly?: boolean | undefined;
+  examples?: JSONSchemaType | undefined;
+}

package/src/lib/parser.ts

@@ -0,0 +1,311 @@
+import { ContentFilterFinishReasonError, LengthFinishReasonError, OpenAIError } from '../error';
+import {
+  ChatCompletion,
+  ChatCompletionCreateParams,
+  ChatCompletionCreateParamsBase,
+  ChatCompletionFunctionTool,
+  ChatCompletionMessage,
+  ChatCompletionMessageFunctionToolCall,
+  ChatCompletionStreamingToolRunnerParams,
+  ChatCompletionStreamParams,
+  ChatCompletionToolRunnerParams,
+  ParsedChatCompletion,
+  ParsedChoice,
+  ParsedFunctionToolCall,
+} from '../resources/chat/completions';
+import { type ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
+import { ResponseFormatJSONSchema } from '../resources/shared';
+
+type AnyChatCompletionCreateParams =
+  | ChatCompletionCreateParams
+  | ChatCompletionToolRunnerParams<any>
+  | ChatCompletionStreamingToolRunnerParams<any>
+  | ChatCompletionStreamParams;
+
+type Unpacked<T> = T extends (infer U)[] ? U : T;
+
+type ToolCall = Unpacked<ChatCompletionCreateParamsBase['tools']>;
+
+export function isChatCompletionFunctionTool(tool: ToolCall): tool is ChatCompletionFunctionTool {
+  return tool !== undefined && 'function' in tool && tool.function !== undefined;
+}
+
+export type ExtractParsedContentFromParams<Params extends AnyChatCompletionCreateParams> =
+  Params['response_format'] extends AutoParseableResponseFormat<infer P> ? P : null;
+
+export type AutoParseableResponseFormat<ParsedT> = ResponseFormatJSONSchema & {
+  __output: ParsedT; // type-level only
+
+  $brand: 'auto-parseable-response-format';
+  $parseRaw(content: string): ParsedT;
+};
+
+export function makeParseableResponseFormat<ParsedT>(
+  response_format: ResponseFormatJSONSchema,
+  parser: (content: string) => ParsedT,
+): AutoParseableResponseFormat<ParsedT> {
+  const obj = { ...response_format };
+
+  Object.defineProperties(obj, {
+    $brand: {
+      value: 'auto-parseable-response-format',
+      enumerable: false,
+    },
+    $parseRaw: {
+      value: parser,
+      enumerable: false,
+    },
+  });
+
+  return obj as AutoParseableResponseFormat<ParsedT>;
+}
+
+export type AutoParseableTextFormat<ParsedT> = ResponseFormatTextJSONSchemaConfig & {
+  __output: ParsedT; // type-level only
+
+  $brand: 'auto-parseable-response-format';
+  $parseRaw(content: string): ParsedT;
+};
+
+export function makeParseableTextFormat<ParsedT>(
+  response_format: ResponseFormatTextJSONSchemaConfig,
+  parser: (content: string) => ParsedT,
+): AutoParseableTextFormat<ParsedT> {
+  const obj = { ...response_format };
+
+  Object.defineProperties(obj, {
+    $brand: {
+      value: 'auto-parseable-response-format',
+      enumerable: false,
+    },
+    $parseRaw: {
+      value: parser,
+      enumerable: false,
+    },
+  });
+
+  return obj as AutoParseableTextFormat<ParsedT>;
+}
+
+export function isAutoParsableResponseFormat<ParsedT>(
+  response_format: any,
+): response_format is AutoParseableResponseFormat<ParsedT> {
+  return response_format?.['$brand'] === 'auto-parseable-response-format';
+}
+
+type ToolOptions = {
+  name: string;
+  arguments: any;
+  function?: ((args: any) => any) | undefined;
+};
+
+export type AutoParseableTool<
+  OptionsT extends ToolOptions,
+  HasFunction = OptionsT['function'] extends Function ? true : false,
+> = ChatCompletionFunctionTool & {
+  __arguments: OptionsT['arguments']; // type-level only
+  __name: OptionsT['name']; // type-level only
+  __hasFunction: HasFunction; // type-level only
+
+  $brand: 'auto-parseable-tool';
+  $callback: ((args: OptionsT['arguments']) => any) | undefined;
+  $parseRaw(args: string): OptionsT['arguments'];
+};
+
+export function makeParseableTool<OptionsT extends ToolOptions>(
+  tool: ChatCompletionFunctionTool,
+  {
+    parser,
+    callback,
+  }: {
+    parser: (content: string) => OptionsT['arguments'];
+    callback: ((args: any) => any) | undefined;
+  },
+): AutoParseableTool<OptionsT['arguments']> {
+  const obj = { ...tool };
+
+  Object.defineProperties(obj, {
+    $brand: {
+      value: 'auto-parseable-tool',
+      enumerable: false,
+    },
+    $parseRaw: {
+      value: parser,
+      enumerable: false,
+    },
+    $callback: {
+      value: callback,
+      enumerable: false,
+    },
+  });
+
+  return obj as AutoParseableTool<OptionsT['arguments']>;
+}
+
+export function isAutoParsableTool(tool: any): tool is AutoParseableTool<any> {
+  return tool?.['$brand'] === 'auto-parseable-tool';
+}
+
+export function maybeParseChatCompletion<
+  Params extends ChatCompletionCreateParams | null,
+  ParsedT = Params extends null ? null : ExtractParsedContentFromParams<NonNullable<Params>>,
+>(completion: ChatCompletion, params: Params): ParsedChatCompletion<ParsedT> {
+  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 ?
+              {
+                tool_calls: choice.message.tool_calls,
+              }
+            : undefined),
+          },
+        };
+      }),
+    } as ParsedChatCompletion<ParsedT>;
+  }
+
+  return parseChatCompletion(completion, params);
+}
+
+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> => {
+    if (choice.finish_reason === 'length') {
+      throw new LengthFinishReasonError();
+    }
+
+    if (choice.finish_reason === 'content_filter') {
+      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),
+        parsed:
+          choice.message.content && !choice.message.refusal ?
+            parseResponseFormat(params, choice.message.content)
+          : null,
+      },
+    } as ParsedChoice<ParsedT>;
+  });
+
+  return { ...completion, choices };
+}
+
+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;
+}
+
+function parseToolCall<Params extends ChatCompletionCreateParams>(
+  params: Params,
+  toolCall: ChatCompletionMessageFunctionToolCall,
+): ParsedFunctionToolCall {
+  const inputTool = params.tools?.find(
+    (inputTool) =>
+      isChatCompletionFunctionTool(inputTool) && inputTool.function?.name === toolCall.function.name,
+  ) as ChatCompletionFunctionTool | undefined; // TS doesn't narrow based on isChatCompletionTool
+  return {
+    ...toolCall,
+    function: {
+      ...toolCall.function,
+      parsed_arguments:
+        isAutoParsableTool(inputTool) ? inputTool.$parseRaw(toolCall.function.arguments)
+        : inputTool?.function.strict ? JSON.parse(toolCall.function.arguments)
+        : null,
+    },
+  };
+}
+
+export function shouldParseToolCall(
+  params: ChatCompletionCreateParams | null | undefined,
+  toolCall: ChatCompletionMessageFunctionToolCall,
+): boolean {
+  if (!params || !('tools' in params) || !params.tools) {
+    return false;
+  }
+
+  const inputTool = params.tools?.find(
+    (inputTool) =>
+      isChatCompletionFunctionTool(inputTool) && inputTool.function?.name === toolCall.function.name,
+  );
+  return (
+    isChatCompletionFunctionTool(inputTool) &&
+    (isAutoParsableTool(inputTool) || inputTool?.function.strict || false)
+  );
+}
+
+export function hasAutoParseableInput(params: AnyChatCompletionCreateParams): boolean {
+  if (isAutoParsableResponseFormat(params.response_format)) {
+    return true;
+  }
+
+  return (
+    params.tools?.some(
+      (t) => isAutoParsableTool(t) || (t.type === 'function' && t.function.strict === true),
+    ) ?? false
+  );
+}
+
+export function assertToolCallsAreChatCompletionFunctionToolCalls(
+  toolCalls: ChatCompletionMessage['tool_calls'],
+): asserts toolCalls is ChatCompletionMessageFunctionToolCall[] {
+  for (const toolCall of toolCalls || []) {
+    if (toolCall.type !== 'function') {
+      throw new OpenAIError(
+        `Currently only \`function\` tool calls are supported; Received \`${toolCall.type}\``,
+      );
+    }
+  }
+}
+
+export function validateInputTools(tools: ChatCompletionCreateParamsBase['tools']) {
+  for (const tool of tools ?? []) {
+    if (tool.type !== 'function') {
+      throw new OpenAIError(
+        `Currently only \`function\` tool types support auto-parsing; Received \`${tool.type}\``,
+      );
+    }
+
+    if (tool.function.strict !== true) {
+      throw new OpenAIError(
+        `The \`${tool.function.name}\` tool is not marked with \`strict: true\`. Only strict function tools can be auto-parsed`,
+      );
+    }
+  }
+}