Add new tool call streaming system

examples/tool-calls-beta-zod.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import OpenAI from 'openai';
+import { betaZodTool } from 'openai/helpers/beta/zod';
+import { z } from 'zod';
+
+const client = new OpenAI();
+
+async function main() {
+  const runner = client.beta.chat.completions.toolRunner({
+    messages: [
+      {
+        role: 'user',
+        content: `I'm planning a trip to San Francisco and I need some information. Can you help me with the weather, current time, and currency exchange rates (from EUR)? Please use parallel tool use.`,
+      },
+    ],
+    tools: [
+      betaZodTool({
+        name: 'getWeather',
+        description: 'Get the weather at a specific location',
+        inputSchema: z.object({
+          location: z.string().describe('The city and state, e.g. San Francisco, CA'),
+        }),
+        run: ({ location }) => {
+          return `The weather is sunny with a temperature of 20°C in ${location}.`;
+        },
+      }),
+      betaZodTool({
+        name: 'getTime',
+        description: 'Get the current time in a specific timezone',
+        inputSchema: z.object({
+          timezone: z.string().describe('The timezone, e.g. America/Los_Angeles'),
+        }),
+        run: ({ timezone }) => {
+          return `The current time in ${timezone} is 3:00 PM.`;
+        },
+      }),
+      betaZodTool({
+        name: 'getCurrencyExchangeRate',
+        description: 'Get the exchange rate between two currencies',
+        inputSchema: z.object({
+          from_currency: z.string().describe('The currency to convert from, e.g. USD'),
+          to_currency: z.string().describe('The currency to convert to, e.g. EUR'),
+        }),
+        run: ({ from_currency, to_currency }) => {
+          return `The exchange rate from ${from_currency} to ${to_currency} is 0.85.`;
+        },
+      }),
+    ],
+    model: 'gpt-4o',
+    max_tokens: 1024,
+    // This limits the conversation to at most 10 back and forth between the API.
+    max_iterations: 10,
+  });
+
+  console.log(`\n🚀 Running tools...\n`);
+
+  for await (const message of runner) {
+    if (!message) continue;
+
+    console.log(`┌─ Message ${message.id} `.padEnd(process.stdout.columns, '─'));
+    console.log();
+
+    const { choices } = message;
+    const firstChoice = choices.at(0)!;
+
+    // When we get a tool call request it's null
+    if (firstChoice.message.content !== null) {
+      console.log(`${firstChoice.message.content}\n`);
+    } else {
+      // each tool call (could be many)
+      for (const toolCall of firstChoice.message.tool_calls ?? []) {
+        if (toolCall.type === 'function') {
+          console.log(`${toolCall.function.name}(${JSON.stringify(toolCall.function.arguments, null, 2)})\n`);
+        }
+      }
+    }
+
+    console.log(`└─`.padEnd(process.stdout.columns, '─'));
+    console.log();
+    console.log();
+
+    const defaultResponse = await runner.generateToolResponse();
+    if (defaultResponse && Array.isArray(defaultResponse)) {
+      console.log(`┌─ Response `.padEnd(process.stdout.columns, '─'));
+      console.log();
+
+      for (const toolResponse of defaultResponse) {
+        if (toolResponse.role === 'tool') {
+          const toolCall = firstChoice.message.tool_calls?.find((tc) => tc.id === toolResponse.tool_call_id);
+          if (toolCall && toolCall.type === 'function') {
+            console.log(`${toolCall.function.name}(): ${toolResponse.content}`);
+          }
+        }
+      }
+
+      console.log();
+      console.log(`└─`.padEnd(process.stdout.columns, '─'));
+      console.log();
+      console.log();
+    }
+  }
+}
+
+main();

examples/tool-helpers-advanced-streaming.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import OpenAI from 'openai';
+import { betaZodTool } from 'openai/helpers/beta/zod';
+import { z } from 'zod';
+
+const client = new OpenAI();
+
+async function main() {
+  const runner = client.beta.chat.completions.toolRunner({
+    messages: [
+      {
+        role: 'user',
+        content: `I'm planning a trip to San Francisco and I need some information. Can you help me with the weather, current time, and currency exchange rates (from EUR)? Please use parallel tool use`,
+      },
+    ],
+    tools: [
+      betaZodTool({
+        name: 'getWeather',
+        description: 'Get the weather at a specific location',
+        inputSchema: z.object({
+          location: z.string().describe('The city and state, e.g. San Francisco, CA'),
+        }),
+        run: ({ location }) => {
+          return `The weather is sunny with a temperature of 20°C in ${location}.`;
+        },
+      }),
+      betaZodTool({
+        name: 'getTime',
+        description: 'Get the current time in a specific timezone',
+        inputSchema: z.object({
+          timezone: z.string().describe('The timezone, e.g. America/Los_Angeles'),
+        }),
+        run: ({ timezone }) => {
+          return `The current time in ${timezone} is 3:00 PM.`;
+        },
+      }),
+      betaZodTool({
+        name: 'getCurrencyExchangeRate',
+        description: 'Get the exchange rate between two currencies',
+        inputSchema: z.object({
+          from_currency: z.string().describe('The currency to convert from, e.g. USD'),
+          to_currency: z.string().describe('The currency to convert to, e.g. EUR'),
+        }),
+        run: ({ from_currency, to_currency }) => {
+          return `The exchange rate from ${from_currency} to ${to_currency} is 0.85.`;
+        },
+      }),
+    ],
+    model: 'gpt-4o',
+    max_tokens: 1024,
+    // This limits the conversation to at most 10 back and forth between the API.
+    max_iterations: 10,
+    stream: true,
+  });
+
+  console.log(`\n🚀 Running tools...\n`);
+
+  let prevMessageStarted = '';
+  let prevToolStarted = '';
+  let prevWasToolCall = false;
+
+  for await (const messageStream of runner) {
+    for await (const event of messageStream) {
+      const hadToolCalls = !!event.choices?.[0]?.delta?.tool_calls;
+
+      if (hadToolCalls) {
+        if (!prevMessageStarted) {
+          console.log(`┌─ Message ${event.id} `.padEnd(process.stdout.columns, '─'));
+          prevMessageStarted = event.id;
+        }
+
+        prevWasToolCall = true;
+        const toolCalls = event.choices[0]!.delta.tool_calls!;
+
+        for (const toolCall of toolCalls) {
+          if (toolCall.function?.name && prevToolStarted !== toolCall.function.name) {
+            process.stdout.write(`\n${toolCall.function.name}: `);
+            prevToolStarted = toolCall.function.name;
+          } else if (toolCall.function?.arguments) {
+            process.stdout.write(toolCall.function.arguments);
+          }
+        }
+      } else if (event.choices?.[0]?.delta?.content) {
+        if (prevWasToolCall) {
+          console.log();
+          console.log();
+          console.log(`└─`.padEnd(process.stdout.columns, '─'));
+          console.log();
+          prevWasToolCall = false;
+        }
+
+        if (prevMessageStarted !== event.id) {
+          console.log(`┌─ Message ${event.id} `.padEnd(process.stdout.columns, '─'));
+          console.log();
+          prevMessageStarted = event.id;
+        }
+
+        process.stdout.write(event.choices[0].delta.content);
+      }
+    }
+  }
+
+  console.log();
+  console.log();
+  console.log(`└─`.padEnd(process.stdout.columns, '─'));
+}
+
+main();

examples/tool-helpers-advanced.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import OpenAI from 'openai';
+import { betaZodTool } from 'openai/helpers/beta/zod';
+import { z } from 'zod';
+
+const client = new OpenAI();
+
+async function main() {
+  const message = await client.beta.chat.completions.toolRunner({
+    messages: [
+      {
+        role: 'user',
+        content: `What is the weather in SF?`,
+      },
+    ],
+    tools: [
+      betaZodTool({
+        name: 'getWeather',
+        description: 'Get the weather at a specific location',
+        inputSchema: z.object({
+          location: z.string().describe('The city and state, e.g. San Francisco, CA'),
+        }),
+        run: ({ location }) => {
+          return `The weather is foggy with a temperature of 20°C in ${location}.`;
+        },
+      }),
+    ],
+    model: 'gpt-4o',
+    max_tokens: 1024,
+    // the maximum number of iterations to run the tool
+    max_iterations: 10,
+  });
+
+  console.log('Final response:', message.content);
+}
+
+main();

examples/tool-helpers-json-schema.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import OpenAI from 'openai';
+import { betaTool } from 'openai/helpers/beta/json-schema';
+
+const client = new OpenAI();
+
+async function main() {
+  const message = await client.beta.chat.completions.toolRunner({
+    messages: [
+      {
+        role: 'user',
+        content: `What is the weather in SF?`,
+      },
+    ],
+    tools: [
+      betaTool({
+        name: 'getWeather',
+        description: 'Get the weather at a specific location',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            location: {
+              type: 'string',
+              description: 'The city and state, e.g. San Francisco, CA',
+            },
+          },
+          required: ['location'],
+        },
+        run: ({ location }) => {
+          return `The weather is foggy with a temperature of 20°C in ${location}.`;
+        },
+      }),
+    ],
+    model: 'gpt-4o',
+    max_tokens: 1024,
+    // the maximum number of iterations to run the tool
+    max_iterations: 10,
+  });
+
+  console.log('Final response:', message.content);
+}
+
+main();

package.json

@@ -26,25 +26,28 @@
     "lint": "./scripts/lint",
     "fix": "./scripts/format"
   },
-  "dependencies": {},
+  "dependencies": {
+    "json-schema-to-ts": "^3.1.1"
+  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.0",
     "@swc/core": "^1.3.102",
     "@swc/jest": "^0.2.29",
     "@types/jest": "^29.4.0",
-    "@types/ws": "^8.5.13",
     "@types/node": "^20.17.6",
+    "@types/ws": "^8.5.13",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
-    "deep-object-diff": "^1.1.9",
     "@typescript-eslint/typescript-estree": "8.31.1",
+    "deep-object-diff": "^1.1.9",
     "eslint": "^9.20.1",
     "eslint-plugin-prettier": "^5.4.1",
     "eslint-plugin-unused-imports": "^4.1.4",
     "execa": "^5.1.1",
     "fast-check": "^3.22.0",
     "iconv-lite": "^0.6.3",
     "jest": "^29.4.0",
+    "nock": "^14.0.10",
     "prettier": "^3.0.0",
     "publint": "^0.2.12",
     "ts-jest": "^29.1.0",
@@ -53,9 +56,9 @@
     "tsconfig-paths": "^4.0.0",
     "tslib": "^2.8.1",
     "typescript": "5.8.3",
+    "typescript-eslint": "8.31.1",
     "ws": "^8.18.0",
-    "zod": "^3.25 || ^4.0",
-    "typescript-eslint": "8.31.1"
+    "zod": "^3.25 || ^4.0"
   },
   "bin": {
     "openai": "bin/cli"

src/helpers/beta/json-schema.ts

@@ -0,0 +1,35 @@
+import type { FromSchema, JSONSchema } from 'json-schema-to-ts';
+import type { BetaRunnableTool, Promisable } from '../../lib/beta/BetaRunnableTool';
+import type { FunctionTool } from '../../resources/beta';
+import { OpenAIError } from '../../error';
+
+type NoInfer<T> = T extends infer R ? R : never;
+
+/**
+ * Creates a Tool with a provided JSON schema that can be passed
+ * to the `.toolRunner()` method. The schema is used to automatically validate
+ * the input arguments for the tool.
+ */
+export function betaTool<const Schema extends Exclude<JSONSchema, boolean> & { type: 'object' }>(options: {
+  name: string;
+  inputSchema: Schema;
+  description: string;
+  run: (args: NoInfer<FromSchema<Schema>>) => Promisable<string | Array<FunctionTool>>;
+}): BetaRunnableTool<NoInfer<FromSchema<Schema>>> {
+  if (options.inputSchema.type !== 'object') {
+    throw new OpenAIError(
+      `JSON schema for tool "${options.name}" must be an object, but got ${options.inputSchema.type}`,
+    );
+  }
+
+  return {
+    type: 'function',
+    function: {
+      name: options.name,
+      parameters: options.inputSchema,
+      description: options.description,
+    },
+    run: options.run,
+    parse: (content: unknown) => content as FromSchema<Schema>,
+  } as any; // For some reason this causes infinite inference so we cast to any to not crash lsp
+}