From 2a43456b2e085f79ff3ebebdfa55c65f68dfbe56 Mon Sep 17 00:00:00 2001 From: Minh Anh Date: Wed, 5 Feb 2025 11:29:45 -0800 Subject: [PATCH 1/8] Fix Azure OpenAI client import --- src/beta/realtime/websocket.ts | 2 +- src/beta/realtime/ws.ts | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/beta/realtime/websocket.ts b/src/beta/realtime/websocket.ts index 349cf5760..e8143fdbf 100644 --- a/src/beta/realtime/websocket.ts +++ b/src/beta/realtime/websocket.ts @@ -95,7 +95,7 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter { } static async azure( - client: AzureOpenAI, + client: Pick, options: { deploymentName?: string; dangerouslyAllowBrowser?: boolean } = {}, ): Promise { const token = await client._getAzureADToken(); diff --git a/src/beta/realtime/ws.ts b/src/beta/realtime/ws.ts index 51339089c..3f51dfc4b 100644 --- a/src/beta/realtime/ws.ts +++ b/src/beta/realtime/ws.ts @@ -52,7 +52,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter { } static async azure( - client: AzureOpenAI, + client: Pick, options: { deploymentName?: string; options?: WS.ClientOptions | undefined } = {}, ): Promise { const deploymentName = options.deploymentName ?? client.deploymentName; @@ -82,7 +82,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter { } } -async function getAzureHeaders(client: AzureOpenAI) { +async function getAzureHeaders(client: Pick) { if (client.apiKey !== '') { return { 'api-key': client.apiKey }; } else { From 27d354a363d3c8dc5056bd28f8f1073757046f48 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 5 Feb 2025 21:25:41 +0000 Subject: [PATCH 2/8] fix(api): add missing reasoning effort + model enums (#1302) --- .stats.yml | 2 +- src/resources/beta/assistants.ts | 51 ++++++++++++++++++- src/resources/beta/threads/runs/runs.ts | 10 ++++ src/resources/chat/completions.ts | 8 +-- tests/api-resources/beta/assistants.test.ts | 1 + .../beta/threads/runs/runs.test.ts | 1 + 6 files changed, 67 insertions(+), 6 deletions(-) diff --git a/.stats.yml b/.stats.yml index df7877dfd..8a5d2c06b 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 69 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-fc5dbc19505b0035f9e7f88868619f4fb519b048bde011f6154f3132d4be71fb.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-7c699d4503077d06a4a44f52c0c1f902d19a87c766b8be75b97c8dfd484ad4aa.yml diff --git a/src/resources/beta/assistants.ts b/src/resources/beta/assistants.ts index 69a5db520..0cc63d691 100644 --- a/src/resources/beta/assistants.ts +++ b/src/resources/beta/assistants.ts @@ -1133,6 +1133,16 @@ export interface AssistantCreateParams { */ name?: string | null; + /** + * **o1 and o3-mini models only** + * + * Constrains effort on reasoning for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + * supported values are `low`, `medium`, and `high`. Reducing reasoning effort can + * result in faster responses and fewer tokens used on reasoning in a response. + */ + reasoning_effort?: 'low' | 'medium' | 'high' | null; + /** * Specifies the format that the model must output. Compatible with * [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), @@ -1288,13 +1298,52 @@ export interface AssistantUpdateParams { * [Model overview](https://platform.openai.com/docs/models) for descriptions of * them. */ - model?: string; + model?: + | (string & {}) + | 'o3-mini' + | 'o3-mini-2025-01-31' + | 'o1' + | 'o1-2024-12-17' + | 'gpt-4o' + | 'gpt-4o-2024-11-20' + | 'gpt-4o-2024-08-06' + | 'gpt-4o-2024-05-13' + | 'gpt-4o-mini' + | 'gpt-4o-mini-2024-07-18' + | 'gpt-4-turbo' + | 'gpt-4-turbo-2024-04-09' + | 'gpt-4-0125-preview' + | 'gpt-4-turbo-preview' + | 'gpt-4-1106-preview' + | 'gpt-4-vision-preview' + | 'gpt-4' + | 'gpt-4-0314' + | 'gpt-4-0613' + | 'gpt-4-32k' + | 'gpt-4-32k-0314' + | 'gpt-4-32k-0613' + | 'gpt-3.5-turbo' + | 'gpt-3.5-turbo-16k' + | 'gpt-3.5-turbo-0613' + | 'gpt-3.5-turbo-1106' + | 'gpt-3.5-turbo-0125' + | 'gpt-3.5-turbo-16k-0613'; /** * The name of the assistant. The maximum length is 256 characters. */ name?: string | null; + /** + * **o1 and o3-mini models only** + * + * Constrains effort on reasoning for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + * supported values are `low`, `medium`, and `high`. Reducing reasoning effort can + * result in faster responses and fewer tokens used on reasoning in a response. + */ + reasoning_effort?: 'low' | 'medium' | 'high' | null; + /** * Specifies the format that the model must output. Compatible with * [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), diff --git a/src/resources/beta/threads/runs/runs.ts b/src/resources/beta/threads/runs/runs.ts index 84ba7b63c..8ab94cc99 100644 --- a/src/resources/beta/threads/runs/runs.ts +++ b/src/resources/beta/threads/runs/runs.ts @@ -731,6 +731,16 @@ export interface RunCreateParamsBase { */ parallel_tool_calls?: boolean; + /** + * Body param: **o1 and o3-mini models only** + * + * Constrains effort on reasoning for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + * supported values are `low`, `medium`, and `high`. Reducing reasoning effort can + * result in faster responses and fewer tokens used on reasoning in a response. + */ + reasoning_effort?: 'low' | 'medium' | 'high' | null; + /** * Body param: Specifies the format that the model must output. Compatible with * [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), diff --git a/src/resources/chat/completions.ts b/src/resources/chat/completions.ts index 55b008cf0..2586845c3 100644 --- a/src/resources/chat/completions.ts +++ b/src/resources/chat/completions.ts @@ -744,14 +744,14 @@ export interface ChatCompletionPredictionContent { } /** - * **o1 models only** + * **o1 and o3-mini models only** * * Constrains effort on reasoning for * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently * supported values are `low`, `medium`, and `high`. Reducing reasoning effort can * result in faster responses and fewer tokens used on reasoning in a response. */ -export type ChatCompletionReasoningEffort = 'low' | 'medium' | 'high'; +export type ChatCompletionReasoningEffort = 'low' | 'medium' | 'high' | null; /** * The role of the author of a message @@ -1063,14 +1063,14 @@ export interface ChatCompletionCreateParamsBase { presence_penalty?: number | null; /** - * **o1 models only** + * **o1 and o3-mini models only** * * Constrains effort on reasoning for * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently * supported values are `low`, `medium`, and `high`. Reducing reasoning effort can * result in faster responses and fewer tokens used on reasoning in a response. */ - reasoning_effort?: ChatCompletionReasoningEffort; + reasoning_effort?: ChatCompletionReasoningEffort | null; /** * An object specifying the format that the model must output. diff --git a/tests/api-resources/beta/assistants.test.ts b/tests/api-resources/beta/assistants.test.ts index 88a10ba8f..16bc9f942 100644 --- a/tests/api-resources/beta/assistants.test.ts +++ b/tests/api-resources/beta/assistants.test.ts @@ -27,6 +27,7 @@ describe('resource assistants', () => { instructions: 'instructions', metadata: { foo: 'string' }, name: 'name', + reasoning_effort: 'low', response_format: 'auto', temperature: 1, tool_resources: { diff --git a/tests/api-resources/beta/threads/runs/runs.test.ts b/tests/api-resources/beta/threads/runs/runs.test.ts index 9b728403f..13ae89a00 100644 --- a/tests/api-resources/beta/threads/runs/runs.test.ts +++ b/tests/api-resources/beta/threads/runs/runs.test.ts @@ -39,6 +39,7 @@ describe('resource runs', () => { metadata: { foo: 'string' }, model: 'gpt-4o', parallel_tool_calls: true, + reasoning_effort: 'low', response_format: 'auto', stream: false, temperature: 1, From f44641236e9f90758c535cc948d5734ae20fd5a5 Mon Sep 17 00:00:00 2001 From: Robert Craigie Date: Wed, 5 Feb 2025 20:33:57 +0000 Subject: [PATCH 3/8] docs(readme): cleanup into multiple files --- README.md | 421 +++++++++++----------------------------------------- azure.md | 49 ++++++ helpers.md | 122 ++++++++++----- realtime.md | 87 +++++++++++ 4 files changed, 313 insertions(+), 366 deletions(-) create mode 100644 azure.md create mode 100644 realtime.md diff --git a/README.md b/README.md index a1f4bf760..166e35e22 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ import OpenAI from 'jsr:@openai/openai'; The full API of this library can be found in [api.md file](api.md) along with many [code examples](https://github.com/openai/openai-node/tree/master/examples). The code below shows how to get started using the chat completions API. -```js +```ts import OpenAI from 'openai'; const client = new OpenAI({ @@ -80,189 +80,11 @@ async function main() { main(); ``` -If you need to cancel a stream, you can `break` from the loop -or call `stream.controller.abort()`. - -## Realtime API beta - -The Realtime API enables you to build low-latency, multi-modal conversational experiences. It currently supports text and audio as both input and output, as well as [function calling](https://platform.openai.com/docs/guides/function-calling) through a `WebSocket` connection. - -The Realtime API works through a combination of client-sent events and server-sent events. Clients can send events to do things like update session configuration or send text and audio inputs. Server events confirm when audio responses have completed, or when a text response from the model has been received. A full event reference can be found [here](https://platform.openai.com/docs/api-reference/realtime-client-events) and a guide can be found [here](https://platform.openai.com/docs/guides/realtime). - -This SDK supports accessing the Realtime API through the [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) or with [ws](https://github.com/websockets/ws). - -Basic text based example with `ws`: - -```ts -// requires `yarn add ws @types/ws` -import { OpenAIRealtimeWS } from 'openai/beta/realtime/ws'; - -const rt = new OpenAIRealtimeWS({ model: 'gpt-4o-realtime-preview-2024-12-17' }); - -// access the underlying `ws.WebSocket` instance -rt.socket.on('open', () => { - console.log('Connection opened!'); - rt.send({ - type: 'session.update', - session: { - modalities: ['text'], - model: 'gpt-4o-realtime-preview', - }, - }); - - rt.send({ - type: 'conversation.item.create', - item: { - type: 'message', - role: 'user', - content: [{ type: 'input_text', text: 'Say a couple paragraphs!' }], - }, - }); - - rt.send({ type: 'response.create' }); -}); - -rt.on('error', (err) => { - // in a real world scenario this should be logged somewhere as you - // likely want to continue procesing events regardless of any errors - throw err; -}); - -rt.on('session.created', (event) => { - console.log('session created!', event.session); - console.log(); -}); - -rt.on('response.text.delta', (event) => process.stdout.write(event.delta)); -rt.on('response.text.done', () => console.log()); - -rt.on('response.done', () => rt.close()); - -rt.socket.on('close', () => console.log('\nConnection closed!')); -``` - -To use the web API `WebSocket` implementation, replace `OpenAIRealtimeWS` with `OpenAIRealtimeWebSocket` and adjust any `rt.socket` access: - -```ts -import { OpenAIRealtimeWebSocket } from 'openai/beta/realtime/websocket'; - -const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-4o-realtime-preview-2024-12-17' }); -// ... -rt.socket.addEventListener('open', () => { - // ... -}); -``` - -A full example can be found [here](https://github.com/openai/openai-node/blob/master/examples/realtime/websocket.ts). - -### Realtime error handling - -When an error is encountered, either on the client side or returned from the server through the [`error` event](https://platform.openai.com/docs/guides/realtime-model-capabilities#error-handling), the `error` event listener will be fired. However, if you haven't registered an `error` event listener then an `unhandled Promise rejection` error will be thrown. - -It is **highly recommended** that you register an `error` event listener and handle errors approriately as typically the underlying connection is still usable. - -```ts -const rt = new OpenAIRealtimeWS({ model: 'gpt-4o-realtime-preview-2024-12-17' }); -rt.on('error', (err) => { - // in a real world scenario this should be logged somewhere as you - // likely want to continue procesing events regardless of any errors - throw err; -}); -``` - -### Request & Response types - -This library includes TypeScript definitions for all request params and response fields. You may import and use them like so: - - -```ts -import OpenAI from 'openai'; - -const client = new OpenAI({ - apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted -}); - -async function main() { - const params: OpenAI.Chat.ChatCompletionCreateParams = { - messages: [{ role: 'user', content: 'Say this is a test' }], - model: 'gpt-4o', - }; - const chatCompletion: OpenAI.Chat.ChatCompletion = await client.chat.completions.create(params); -} - -main(); -``` - -Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors. - -> [!IMPORTANT] -> Previous versions of this SDK used a `Configuration` class. See the [v3 to v4 migration guide](https://github.com/openai/openai-node/discussions/217). - -### Polling Helpers - -When interacting with the API some actions such as starting a Run and adding files to vector stores are asynchronous and take time to complete. The SDK includes -helper functions which will poll the status until it reaches a terminal state and then return the resulting object. -If an API method results in an action which could benefit from polling there will be a corresponding version of the -method ending in 'AndPoll'. - -For instance to create a Run and poll until it reaches a terminal state you can run: - -```ts -const run = await openai.beta.threads.runs.createAndPoll(thread.id, { - assistant_id: assistantId, -}); -``` - -More information on the lifecycle of a Run can be found in the [Run Lifecycle Documentation](https://platform.openai.com/docs/assistants/deep-dive/run-lifecycle) - -### Bulk Upload Helpers - -When creating and interacting with vector stores, you can use the polling helpers to monitor the status of operations. -For convenience, we also provide a bulk upload helper to allow you to simultaneously upload several files at once. - -```ts -const fileList = [ - createReadStream('/home/data/example.pdf'), - ... -]; - -const batch = await openai.vectorStores.fileBatches.uploadAndPoll(vectorStore.id, {files: fileList}); -``` - -### Streaming Helpers - -The SDK also includes helpers to process streams and handle the incoming events. - -```ts -const run = openai.beta.threads.runs - .stream(thread.id, { - assistant_id: assistant.id, - }) - .on('textCreated', (text) => process.stdout.write('\nassistant > ')) - .on('textDelta', (textDelta, snapshot) => process.stdout.write(textDelta.value)) - .on('toolCallCreated', (toolCall) => process.stdout.write(`\nassistant > ${toolCall.type}\n\n`)) - .on('toolCallDelta', (toolCallDelta, snapshot) => { - if (toolCallDelta.type === 'code_interpreter') { - if (toolCallDelta.code_interpreter.input) { - process.stdout.write(toolCallDelta.code_interpreter.input); - } - if (toolCallDelta.code_interpreter.outputs) { - process.stdout.write('\noutput >\n'); - toolCallDelta.code_interpreter.outputs.forEach((output) => { - if (output.type === 'logs') { - process.stdout.write(`\n${output.logs}\n`); - } - }); - } - } - }); -``` - -More information on streaming helpers can be found in the dedicated documentation: [helpers.md](helpers.md) +If you need to cancel a stream, you can `break` from the loop or call `stream.controller.abort()`. -### Streaming responses +### Chat Completion streaming helpers -This library provides several conveniences for streaming chat completions, for example: +This library also provides several conveniences for streaming chat completions, for example: ```ts import OpenAI from 'openai'; @@ -292,98 +114,32 @@ async function main() { main(); ``` -Streaming with `openai.beta.chat.completions.stream({…})` exposes -[various helpers for your convenience](helpers.md#chat-events) including event handlers and promises. - -Alternatively, you can use `openai.chat.completions.create({ stream: true, … })` -which only returns an async iterable of the chunks in the stream and thus uses less memory -(it does not build up a final chat completion object for you). - -If you need to cancel a stream, you can `break` from a `for await` loop or call `stream.abort()`. - -### Automated function calls +See [helpers.md](helpers.md#chat-events) for more details. -We provide the `openai.beta.chat.completions.runTools({…})` -convenience helper for using function tool calls with the `/chat/completions` endpoint -which automatically call the JavaScript functions you provide -and sends their results back to the `/chat/completions` endpoint, -looping as long as the model requests tool calls. - -If you pass a `parse` function, it will automatically parse the `arguments` for you -and returns any parsing errors to the model to attempt auto-recovery. -Otherwise, the args will be passed to the function you provide as a string. +### Request & Response types -If you pass `tool_choice: {function: {name: …}}` instead of `auto`, -it returns immediately after calling that function (and only loops to auto-recover parsing errors). +This library includes TypeScript definitions for all request params and response fields. You may import and use them like so: + ```ts import OpenAI from 'openai'; -const client = new OpenAI(); +const client = new OpenAI({ + apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted +}); async function main() { - const runner = client.beta.chat.completions - .runTools({ - model: 'gpt-4o', - messages: [{ role: 'user', content: 'How is the weather this week?' }], - tools: [ - { - type: 'function', - function: { - function: getCurrentLocation, - parameters: { type: 'object', properties: {} }, - }, - }, - { - type: 'function', - function: { - function: getWeather, - parse: JSON.parse, // or use a validation library like zod for typesafe parsing. - parameters: { - type: 'object', - properties: { - location: { type: 'string' }, - }, - }, - }, - }, - ], - }) - .on('message', (message) => console.log(message)); - - const finalContent = await runner.finalContent(); - console.log(); - console.log('Final content:', finalContent); -} - -async function getCurrentLocation() { - return 'Boston'; // Simulate lookup -} - -async function getWeather(args: { location: string }) { - const { location } = args; - // … do lookup … - return { temperature, precipitation }; + const params: OpenAI.Chat.ChatCompletionCreateParams = { + messages: [{ role: 'user', content: 'Say this is a test' }], + model: 'gpt-4o', + }; + const chatCompletion: OpenAI.Chat.ChatCompletion = await client.chat.completions.create(params); } main(); - -// {role: "user", content: "How's the weather this week?"} -// {role: "assistant", tool_calls: [{type: "function", function: {name: "getCurrentLocation", arguments: "{}"}, id: "123"} -// {role: "tool", name: "getCurrentLocation", content: "Boston", tool_call_id: "123"} -// {role: "assistant", tool_calls: [{type: "function", function: {name: "getWeather", arguments: '{"location": "Boston"}'}, id: "1234"}]} -// {role: "tool", name: "getWeather", content: '{"temperature": "50degF", "preciptation": "high"}', tool_call_id: "1234"} -// {role: "assistant", content: "It's looking cold and rainy - you might want to wear a jacket!"} -// -// Final content: "It's looking cold and rainy - you might want to wear a jacket!" ``` -Like with `.stream()`, we provide a variety of [helpers and events](helpers.md#chat-events). - -Note that `runFunctions` was previously available as well, but has been deprecated in favor of `runTools`. - -Read more about various examples such as with integrating with [zod](helpers.md#integrate-with-zod), -[next.js](helpers.md#integrate-with-nextjs), and [proxying a stream to the browser](helpers.md#proxy-streaming-to-a-browser). +Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors. ## File uploads @@ -434,6 +190,7 @@ async function main() { .create({ model: 'gpt-4o', training_file: 'file-abc123' }) .catch(async (err) => { if (err instanceof OpenAI.APIError) { + console.log(err.request_id); console.log(err.status); // 400 console.log(err.name); // BadRequestError console.log(err.headers); // {server: 'nginx', ...} @@ -459,76 +216,6 @@ Error codes are as followed: | >=500 | `InternalServerError` | | N/A | `APIConnectionError` | -## Request IDs - -> For more information on debugging requests, see [these docs](https://platform.openai.com/docs/api-reference/debugging-requests) - -All object responses in the SDK provide a `_request_id` property which is added from the `x-request-id` response header so that you can quickly log failing requests and report them back to OpenAI. - -```ts -const completion = await client.chat.completions.create({ messages: [{ role: 'user', content: 'Say this is a test' }], model: 'gpt-4o' }); -console.log(completion._request_id) // req_123 -``` - -You can also access the Request ID using the `.withResponse()` method: - -```ts -const { data: stream, request_id } = await openai.chat.completions - .create({ - model: 'gpt-4', - messages: [{ role: 'user', content: 'Say this is a test' }], - stream: true, - }) - .withResponse(); -``` - -## Microsoft Azure OpenAI - -To use this library with [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/overview), use the `AzureOpenAI` -class instead of the `OpenAI` class. - -> [!IMPORTANT] -> The Azure API shape slightly differs from the core API shape which means that the static types for responses / params -> won't always be correct. - -```ts -import { AzureOpenAI } from 'openai'; -import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity'; - -const credential = new DefaultAzureCredential(); -const scope = 'https://cognitiveservices.azure.com/.default'; -const azureADTokenProvider = getBearerTokenProvider(credential, scope); - -const openai = new AzureOpenAI({ azureADTokenProvider, apiVersion: "" }); - -const result = await openai.chat.completions.create({ - model: 'gpt-4o', - messages: [{ role: 'user', content: 'Say hello!' }], -}); - -console.log(result.choices[0]!.message?.content); -``` - -### Realtime API -This SDK provides real-time streaming capabilities for Azure OpenAI through the `OpenAIRealtimeWS` and `OpenAIRealtimeWebSocket` clients described previously. - -To utilize the real-time features, begin by creating a fully configured `AzureOpenAI` client and passing it into either `OpenAIRealtimeWS.azure` or `OpenAIRealtimeWebSocket.azure`. For example: - -```ts -const cred = new DefaultAzureCredential(); -const scope = 'https://cognitiveservices.azure.com/.default'; -const deploymentName = 'gpt-4o-realtime-preview-1001'; -const azureADTokenProvider = getBearerTokenProvider(cred, scope); -const client = new AzureOpenAI({ - azureADTokenProvider, - apiVersion: '2024-10-01-preview', - deployment: deploymentName, -}); -const rt = await OpenAIRealtimeWS.azure(client); -``` - -Once the instance has been created, you can then begin sending requests and receiving streaming responses in real time. - ### Retries Certain errors will be automatically retried 2 times by default, with a short exponential backoff. @@ -571,6 +258,29 @@ On timeout, an `APIConnectionTimeoutError` is thrown. Note that requests which time out will be [retried twice by default](#retries). +## Request IDs + +> For more information on debugging requests, see [these docs](https://platform.openai.com/docs/api-reference/debugging-requests) + +All object responses in the SDK provide a `_request_id` property which is added from the `x-request-id` response header so that you can quickly log failing requests and report them back to OpenAI. + +```ts +const completion = await client.chat.completions.create({ messages: [{ role: 'user', content: 'Say this is a test' }], model: 'gpt-4o' }); +console.log(completion._request_id) // req_123 +``` + +You can also access the Request ID using the `.withResponse()` method: + +```ts +const { data: stream, request_id } = await openai.chat.completions + .create({ + model: 'gpt-4', + messages: [{ role: 'user', content: 'Say this is a test' }], + stream: true, + }) + .withResponse(); +``` + ## Auto-pagination List methods in the OpenAI API are paginated. @@ -602,6 +312,55 @@ while (page.hasNextPage()) { } ``` +## Realtime API Beta + +The Realtime API enables you to build low-latency, multi-modal conversational experiences. It currently supports text and audio as both input and output, as well as [function calling](https://platform.openai.com/docs/guides/function-calling) through a `WebSocket` connection. + +```ts +import { OpenAIRealtimeWebSocket } from 'openai/beta/realtime/websocket'; + +const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-4o-realtime-preview-2024-12-17' }); + +rt.on('response.text.delta', (event) => process.stdout.write(event.delta)); +``` + +For more information see [realtime.md](realtime.md). + +## Microsoft Azure OpenAI + +To use this library with [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/overview), use the `AzureOpenAI` +class instead of the `OpenAI` class. + +> [!IMPORTANT] +> The Azure API shape slightly differs from the core API shape which means that the static types for responses / params +> won't always be correct. + +```ts +import { AzureOpenAI } from 'openai'; +import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity'; + +const credential = new DefaultAzureCredential(); +const scope = 'https://cognitiveservices.azure.com/.default'; +const azureADTokenProvider = getBearerTokenProvider(credential, scope); + +const openai = new AzureOpenAI({ azureADTokenProvider, apiVersion: "" }); + +const result = await openai.chat.completions.create({ + model: 'gpt-4o', + messages: [{ role: 'user', content: 'Say hello!' }], +}); + +console.log(result.choices[0]!.message?.content); +``` + +For more information on support for the Azure API, see [azure.md](azure.md). + +## Automated function calls + +We provide the `openai.beta.chat.completions.runTools({…})` convenience helper for using function tool calls with the `/chat/completions` endpoint which automatically call the JavaScript functions you provide and sends their results back to the `/chat/completions` endpoint, looping as long as the model requests tool calls. + +For more information see [helpers.md](helpers.md#automated-function-calls). + ## Advanced Usage ### Accessing raw Response data (e.g., headers) diff --git a/azure.md b/azure.md new file mode 100644 index 000000000..df06c2985 --- /dev/null +++ b/azure.md @@ -0,0 +1,49 @@ +# Microsoft Azure OpenAI + +To use this library with [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/overview), use the `AzureOpenAI` +class instead of the `OpenAI` class. + +> [!IMPORTANT] +> The Azure API shape slightly differs from the core API shape which means that the static types for responses / params +> won't always be correct. + +```ts +import { AzureOpenAI } from 'openai'; +import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity'; + +const credential = new DefaultAzureCredential(); +const scope = 'https://cognitiveservices.azure.com/.default'; +const azureADTokenProvider = getBearerTokenProvider(credential, scope); + +const openai = new AzureOpenAI({ azureADTokenProvider, apiVersion: "" }); + +const result = await openai.chat.completions.create({ + model: 'gpt-4o', + messages: [{ role: 'user', content: 'Say hello!' }], +}); + +console.log(result.choices[0]!.message?.content); +``` + +For more information on support for the Azure API, see [azure.md](azure.md). + +## Realtime API + +This SDK provides real-time streaming capabilities for Azure OpenAI through the `OpenAIRealtimeWS` and `OpenAIRealtimeWebSocket` clients described previously. + +To utilize the real-time features, begin by creating a fully configured `AzureOpenAI` client and passing it into either `OpenAIRealtimeWS.azure` or `OpenAIRealtimeWebSocket.azure`. For example: + +```ts +const cred = new DefaultAzureCredential(); +const scope = 'https://cognitiveservices.azure.com/.default'; +const deploymentName = 'gpt-4o-realtime-preview-1001'; +const azureADTokenProvider = getBearerTokenProvider(cred, scope); +const client = new AzureOpenAI({ + azureADTokenProvider, + apiVersion: '2024-10-01-preview', + deployment: deploymentName, +}); +const rt = await OpenAIRealtimeWS.azure(client); +``` + +Once the instance has been created, you can then begin sending requests and receiving streaming responses in real time. diff --git a/helpers.md b/helpers.md index 16bc1f277..41b352e5e 100644 --- a/helpers.md +++ b/helpers.md @@ -142,9 +142,7 @@ More information can be found in the documentation: [Assistant Streaming](https: ```ts const run = openai.beta.threads.runs - .stream(thread.id, { - assistant_id: assistant.id, - }) + .stream(thread.id, { assistant_id: assistant.id }) .on('textCreated', (text) => process.stdout.write('\nassistant > ')) .on('textDelta', (textDelta, snapshot) => process.stdout.write(textDelta.value)) .on('toolCallCreated', (toolCall) => process.stdout.write(`\nassistant > ${toolCall.type}\n\n`)) @@ -304,47 +302,87 @@ If you need to cancel a stream, you can `break` from a `for await` loop or call See an example of streaming helpers in action in [`examples/stream.ts`](examples/stream.ts). -### Automated Function Calls +### Automated function calls -```ts -openai.chat.completions.runTools({ stream: false, … }, options?): ChatCompletionRunner -openai.chat.completions.runTools({ stream: true, … }, options?): ChatCompletionStreamingRunner -``` +We provide the `openai.beta.chat.completions.runTools({…})` +convenience helper for using function tool calls with the `/chat/completions` endpoint +which automatically call the JavaScript functions you provide +and sends their results back to the `/chat/completions` endpoint, +looping as long as the model requests tool calls. -`openai.chat.completions.runTools()` returns a Runner -for automating function calls with chat completions. -The runner automatically calls the JavaScript functions you provide and sends their results back -to the API, looping as long as the model requests function calls. +If you pass a `parse` function, it will automatically parse the `arguments` for you +and returns any parsing errors to the model to attempt auto-recovery. +Otherwise, the args will be passed to the function you provide as a string. -If you pass a `parse` function, it will automatically parse the `arguments` for you and returns any parsing -errors to the model to attempt auto-recovery. Otherwise, the args will be passed to the function you provide -as a string. +If you pass `tool_choice: {function: {name: …}}` instead of `auto`, +it returns immediately after calling that function (and only loops to auto-recover parsing errors). ```ts -client.chat.completions.runTools({ - model: 'gpt-3.5-turbo', - messages: [{ role: 'user', content: 'How is the weather this week?' }], - tools: [ - { - type: 'function', - function: { - function: getWeather as (args: { location: string; time: Date }) => any, - parse: parseFunction as (args: strings) => { location: string; time: Date }, - parameters: { - type: 'object', - properties: { - location: { type: 'string' }, - time: { type: 'string', format: 'date-time' }, +import OpenAI from 'openai'; + +const client = new OpenAI(); + +async function main() { + const runner = client.beta.chat.completions + .runTools({ + model: 'gpt-4o', + messages: [{ role: 'user', content: 'How is the weather this week?' }], + tools: [ + { + type: 'function', + function: { + function: getCurrentLocation, + parameters: { type: 'object', properties: {} }, }, }, - }, - }, - ], -}); + { + type: 'function', + function: { + function: getWeather, + parse: JSON.parse, // or use a validation library like zod for typesafe parsing. + parameters: { + type: 'object', + properties: { + location: { type: 'string' }, + }, + }, + }, + }, + ], + }) + .on('message', (message) => console.log(message)); + + const finalContent = await runner.finalContent(); + console.log(); + console.log('Final content:', finalContent); +} + +async function getCurrentLocation() { + return 'Boston'; // Simulate lookup +} + +async function getWeather(args: { location: string }) { + const { location } = args; + // … do lookup … + return { temperature, precipitation }; +} + +main(); + +// {role: "user", content: "How's the weather this week?"} +// {role: "assistant", tool_calls: [{type: "function", function: {name: "getCurrentLocation", arguments: "{}"}, id: "123"} +// {role: "tool", name: "getCurrentLocation", content: "Boston", tool_call_id: "123"} +// {role: "assistant", tool_calls: [{type: "function", function: {name: "getWeather", arguments: '{"location": "Boston"}'}, id: "1234"}]} +// {role: "tool", name: "getWeather", content: '{"temperature": "50degF", "preciptation": "high"}', tool_call_id: "1234"} +// {role: "assistant", content: "It's looking cold and rainy - you might want to wear a jacket!"} +// +// Final content: "It's looking cold and rainy - you might want to wear a jacket!" ``` -If you pass `function_call: {name: …}` instead of `auto`, it returns immediately after calling that -function (and only loops to auto-recover parsing errors). +Like with `.stream()`, we provide a variety of [helpers and events](helpers.md#chat-events). + +Read more about various examples such as with integrating with [zod](#integrate-with-zod), +[next.js](#integrate-with-nextjs), and [proxying a stream to the browser](#proxy-streaming-to-a-browser). By default, we run the loop up to 10 chat completions from the API. You can change this behavior by adjusting `maxChatCompletions` in the request options object. Note that `max_tokens` is the limit per @@ -662,3 +700,17 @@ client.beta.vectorStores.files.createAndPoll((...) client.beta.vectorStores.fileBatches.createAndPoll((...) client.beta.vectorStores.fileBatches.uploadAndPoll((...) ``` + +# Bulk Upload Helpers + +When creating and interacting with vector stores, you can use the polling helpers to monitor the status of operations. +For convenience, we also provide a bulk upload helper to allow you to simultaneously upload several files at once. + +```ts +const fileList = [ + createReadStream('/home/data/example.pdf'), + ... +]; + +const batch = await openai.vectorStores.fileBatches.uploadAndPoll(vectorStore.id, {files: fileList}); +``` diff --git a/realtime.md b/realtime.md new file mode 100644 index 000000000..2fcd17e9e --- /dev/null +++ b/realtime.md @@ -0,0 +1,87 @@ +## Realtime API beta + +The Realtime API enables you to build low-latency, multi-modal conversational experiences. It currently supports text and audio as both input and output, as well as [function calling](https://platform.openai.com/docs/guides/function-calling) through a `WebSocket` connection. + +The Realtime API works through a combination of client-sent events and server-sent events. Clients can send events to do things like update session configuration or send text and audio inputs. Server events confirm when audio responses have completed, or when a text response from the model has been received. A full event reference can be found [here](https://platform.openai.com/docs/api-reference/realtime-client-events) and a guide can be found [here](https://platform.openai.com/docs/guides/realtime). + +This SDK supports accessing the Realtime API through the [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) or with [ws](https://github.com/websockets/ws). + +Basic text based example with `ws`: + +```ts +// requires `yarn add ws @types/ws` +import { OpenAIRealtimeWS } from 'openai/beta/realtime/ws'; + +const rt = new OpenAIRealtimeWS({ model: 'gpt-4o-realtime-preview-2024-12-17' }); + +// access the underlying `ws.WebSocket` instance +rt.socket.on('open', () => { + console.log('Connection opened!'); + rt.send({ + type: 'session.update', + session: { + modalities: ['text'], + model: 'gpt-4o-realtime-preview', + }, + }); + + rt.send({ + type: 'conversation.item.create', + item: { + type: 'message', + role: 'user', + content: [{ type: 'input_text', text: 'Say a couple paragraphs!' }], + }, + }); + + rt.send({ type: 'response.create' }); +}); + +rt.on('error', (err) => { + // in a real world scenario this should be logged somewhere as you + // likely want to continue procesing events regardless of any errors + throw err; +}); + +rt.on('session.created', (event) => { + console.log('session created!', event.session); + console.log(); +}); + +rt.on('response.text.delta', (event) => process.stdout.write(event.delta)); +rt.on('response.text.done', () => console.log()); + +rt.on('response.done', () => rt.close()); + +rt.socket.on('close', () => console.log('\nConnection closed!')); +``` + +To use the web API `WebSocket` implementation, replace `OpenAIRealtimeWS` with `OpenAIRealtimeWebSocket` and adjust any `rt.socket` access: + +```ts +import { OpenAIRealtimeWebSocket } from 'openai/beta/realtime/websocket'; + +const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-4o-realtime-preview-2024-12-17' }); +// ... +rt.socket.addEventListener('open', () => { + // ... +}); +``` + +A full example can be found [here](https://github.com/openai/openai-node/blob/master/examples/realtime/websocket.ts). + +### Realtime error handling + +When an error is encountered, either on the client side or returned from the server through the [`error` event](https://platform.openai.com/docs/guides/realtime-model-capabilities#error-handling), the `error` event listener will be fired. However, if you haven't registered an `error` event listener then an `unhandled Promise rejection` error will be thrown. + +It is **highly recommended** that you register an `error` event listener and handle errors approriately as typically the underlying connection is still usable. + +```ts +const rt = new OpenAIRealtimeWS({ model: 'gpt-4o-realtime-preview-2024-12-17' }); +rt.on('error', (err) => { + // in a real world scenario this should be logged somewhere as you + // likely want to continue procesing events regardless of any errors + throw err; +}); +``` + From 23c194b4b927e50d0f5a78272e9ac50b181c53eb Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 6 Feb 2025 15:16:31 +0000 Subject: [PATCH 4/8] feat(pagination): avoid fetching when has_more: false (#1305) --- .stats.yml | 2 +- src/pagination.ts | 13 +++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 8a5d2c06b..d59a86d22 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 69 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-7c699d4503077d06a4a44f52c0c1f902d19a87c766b8be75b97c8dfd484ad4aa.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-dfb00c627f58e5180af7a9b29ed2f2aa0764a3b9daa6a32a1cc45bc8e48dfe15.yml diff --git a/src/pagination.ts b/src/pagination.ts index 63644e333..ad90a3a74 100644 --- a/src/pagination.ts +++ b/src/pagination.ts @@ -43,6 +43,8 @@ export class Page extends AbstractPage implements PageResponse export interface CursorPageResponse { data: Array; + + has_more: boolean; } export interface CursorPageParams { @@ -57,6 +59,8 @@ export class CursorPage { data: Array; + has_more: boolean; + constructor( client: APIClient, response: Response, @@ -66,12 +70,21 @@ export class CursorPage super(client, response, body, options); this.data = body.data || []; + this.has_more = body.has_more || false; } getPaginatedItems(): Item[] { return this.data ?? []; } + override hasNextPage() { + if (this.has_more === false) { + return false; + } + + return super.hasNextPage(); + } + // @deprecated Please use `nextPageInfo()` instead nextPageParams(): Partial | null { const info = this.nextPageInfo(); From 2d071dfd9e507e3a37177d1f96a5438ba9ac1268 Mon Sep 17 00:00:00 2001 From: Robert Craigie Date: Mon, 10 Feb 2025 12:12:44 +0000 Subject: [PATCH 5/8] chore(internal): remove segfault-handler dependency --- ecosystem-tests/cli.ts | 4 ---- package.json | 1 - yarn.lock | 25 ------------------------- 3 files changed, 30 deletions(-) diff --git a/ecosystem-tests/cli.ts b/ecosystem-tests/cli.ts index 00120e5f9..4803b47c2 100644 --- a/ecosystem-tests/cli.ts +++ b/ecosystem-tests/cli.ts @@ -4,10 +4,6 @@ import yargs from 'yargs'; import assert from 'assert'; import path from 'path'; -// @ts-ignore -var SegfaultHandler = require('segfault-handler'); -SegfaultHandler.registerHandler('crash.log'); - const TAR_NAME = 'openai.tgz'; const PACK_FOLDER = '.pack'; const PACK_FILE = `${PACK_FOLDER}/${TAR_NAME}`; diff --git a/package.json b/package.json index bd507e9f8..df2dcd2bc 100644 --- a/package.json +++ b/package.json @@ -47,7 +47,6 @@ "jest": "^29.4.0", "prettier": "^3.0.0", "prettier-2": "npm:prettier@^2", - "segfault-handler": "^1.3.0", "ts-jest": "^29.1.0", "ts-node": "^10.5.0", "tsc-multi": "^1.1.0", diff --git a/yarn.lock b/yarn.lock index 0a4307f70..ad5fb7630 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1176,13 +1176,6 @@ big-integer@^1.6.44: resolved "https://registry.yarnpkg.com/big-integer/-/big-integer-1.6.52.tgz#60a887f3047614a8e1bffe5d7173490a97dc8c85" integrity sha512-QxD8cf2eVqJOOz63z6JIN9BzvVs/dlySa5HGSBH5xtR8dPteIRQnBxxKqkNTiT6jbDTF6jAfrd4oMcND9RGbQg== -bindings@^1.2.1: - version "1.5.0" - resolved "https://registry.yarnpkg.com/bindings/-/bindings-1.5.0.tgz#10353c9e945334bc0511a6d90b38fbc7c9c504df" - integrity sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ== - dependencies: - file-uri-to-path "1.0.0" - bplist-parser@^0.2.0: version "0.2.0" resolved "https://registry.yarnpkg.com/bplist-parser/-/bplist-parser-0.2.0.tgz#43a9d183e5bf9d545200ceac3e712f79ebbe8d0e" @@ -1760,11 +1753,6 @@ file-entry-cache@^6.0.1: dependencies: flat-cache "^3.0.4" -file-uri-to-path@1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz#553a7b8446ff6f684359c445f1e37a05dacc33dd" - integrity sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw== - fill-range@^7.1.1: version "7.1.1" resolved "https://registry.yarnpkg.com/fill-range/-/fill-range-7.1.1.tgz#44265d3cac07e3ea7dc247516380643754a05292" @@ -2706,11 +2694,6 @@ ms@^2.0.0, ms@^2.1.3: resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2" integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== -nan@^2.14.0: - version "2.22.0" - resolved "https://registry.yarnpkg.com/nan/-/nan-2.22.0.tgz#31bc433fc33213c97bad36404bb68063de604de3" - integrity sha512-nbajikzWTMwsW+eSsNm3QwlOs7het9gGJU5dDZzRTQGk03vyBOauxgI4VakDzE0PtsGTmXPsXTbbjVhRwR5mpw== - natural-compare@^1.4.0: version "1.4.0" resolved "https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7" @@ -3061,14 +3044,6 @@ safe-buffer@~5.2.0: resolved "https://registry.yarnpkg.com/safer-buffer/-/safer-buffer-2.1.2.tgz#44fa161b0187b9549dd84bb91802f9bd8385cd6a" integrity sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg== -segfault-handler@^1.3.0: - version "1.3.0" - resolved "https://registry.yarnpkg.com/segfault-handler/-/segfault-handler-1.3.0.tgz#054bc847832fa14f218ba6a79e42877501c8870e" - integrity sha512-p7kVHo+4uoYkr0jmIiTBthwV5L2qmWtben/KDunDZ834mbos+tY+iO0//HpAJpOFSQZZ+wxKWuRo4DxV02B7Lg== - dependencies: - bindings "^1.2.1" - nan "^2.14.0" - semver@^6.3.0, semver@^6.3.1: version "6.3.1" resolved "https://registry.yarnpkg.com/semver/-/semver-6.3.1.tgz#556d2ef8689146e46dcea4bfdd095f3434dffcb4" From 85ff876a75147490e60c70c2f36e964513f1086a Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Mon, 10 Feb 2025 20:06:34 +0000 Subject: [PATCH 6/8] fix: correctly decode multi-byte characters over multiple chunks (#1316) --- src/internal/decoders/line.ts | 107 ++++++++++++++++++++++------------ src/streaming.ts | 6 +- tests/streaming.test.ts | 53 ++++++++++++++++- 3 files changed, 126 insertions(+), 40 deletions(-) diff --git a/src/internal/decoders/line.ts b/src/internal/decoders/line.ts index 34e41d1dc..66f62c057 100644 --- a/src/internal/decoders/line.ts +++ b/src/internal/decoders/line.ts @@ -13,52 +13,58 @@ export class LineDecoder { static NEWLINE_CHARS = new Set(['\n', '\r']); static NEWLINE_REGEXP = /\r\n|[\n\r]/g; - buffer: string[]; - trailingCR: boolean; + buffer: Uint8Array; + #carriageReturnIndex: number | null; textDecoder: any; // TextDecoder found in browsers; not typed to avoid pulling in either "dom" or "node" types. constructor() { - this.buffer = []; - this.trailingCR = false; + this.buffer = new Uint8Array(); + this.#carriageReturnIndex = null; } decode(chunk: Bytes): string[] { - let text = this.decodeText(chunk); - - if (this.trailingCR) { - text = '\r' + text; - this.trailingCR = false; - } - if (text.endsWith('\r')) { - this.trailingCR = true; - text = text.slice(0, -1); - } - - if (!text) { + if (chunk == null) { return []; } - const trailingNewline = LineDecoder.NEWLINE_CHARS.has(text[text.length - 1] || ''); - let lines = text.split(LineDecoder.NEWLINE_REGEXP); + const binaryChunk = + chunk instanceof ArrayBuffer ? new Uint8Array(chunk) + : typeof chunk === 'string' ? new TextEncoder().encode(chunk) + : chunk; + + let newData = new Uint8Array(this.buffer.length + binaryChunk.length); + newData.set(this.buffer); + newData.set(binaryChunk, this.buffer.length); + this.buffer = newData; + + const lines: string[] = []; + let patternIndex; + while ((patternIndex = findNewlineIndex(this.buffer, this.#carriageReturnIndex)) != null) { + if (patternIndex.carriage && this.#carriageReturnIndex == null) { + // skip until we either get a corresponding `\n`, a new `\r` or nothing + this.#carriageReturnIndex = patternIndex.index; + continue; + } - // if there is a trailing new line then the last entry will be an empty - // string which we don't care about - if (trailingNewline) { - lines.pop(); - } + // we got double \r or \rtext\n + if ( + this.#carriageReturnIndex != null && + (patternIndex.index !== this.#carriageReturnIndex + 1 || patternIndex.carriage) + ) { + lines.push(this.decodeText(this.buffer.slice(0, this.#carriageReturnIndex - 1))); + this.buffer = this.buffer.slice(this.#carriageReturnIndex); + this.#carriageReturnIndex = null; + continue; + } - if (lines.length === 1 && !trailingNewline) { - this.buffer.push(lines[0]!); - return []; - } + const endIndex = + this.#carriageReturnIndex !== null ? patternIndex.preceding - 1 : patternIndex.preceding; - if (this.buffer.length > 0) { - lines = [this.buffer.join('') + lines[0], ...lines.slice(1)]; - this.buffer = []; - } + const line = this.decodeText(this.buffer.slice(0, endIndex)); + lines.push(line); - if (!trailingNewline) { - this.buffer = [lines.pop() || '']; + this.buffer = this.buffer.slice(patternIndex.index); + this.#carriageReturnIndex = null; } return lines; @@ -102,13 +108,38 @@ export class LineDecoder { } flush(): string[] { - if (!this.buffer.length && !this.trailingCR) { + if (!this.buffer.length) { return []; } + return this.decode('\n'); + } +} - const lines = [this.buffer.join('')]; - this.buffer = []; - this.trailingCR = false; - return lines; +/** + * This function searches the buffer for the end patterns, (\r or \n) + * and returns an object with the index preceding the matched newline and the + * index after the newline char. `null` is returned if no new line is found. + * + * ```ts + * findNewLineIndex('abc\ndef') -> { preceding: 2, index: 3 } + * ``` + */ +function findNewlineIndex( + buffer: Uint8Array, + startIndex: number | null, +): { preceding: number; index: number; carriage: boolean } | null { + const newline = 0x0a; // \n + const carriage = 0x0d; // \r + + for (let i = startIndex ?? 0; i < buffer.length; i++) { + if (buffer[i] === newline) { + return { preceding: i, index: i + 1, carriage: false }; + } + + if (buffer[i] === carriage) { + return { preceding: i, index: i + 1, carriage: true }; + } } + + return null; } diff --git a/src/streaming.ts b/src/streaming.ts index 6a57a50a0..1d1ae344b 100644 --- a/src/streaming.ts +++ b/src/streaming.ts @@ -346,13 +346,17 @@ class SSEDecoder { } /** This is an internal helper function that's just used for testing */ -export function _decodeChunks(chunks: string[]): string[] { +export function _decodeChunks(chunks: string[], { flush }: { flush: boolean } = { flush: false }): string[] { const decoder = new LineDecoder(); const lines: string[] = []; for (const chunk of chunks) { lines.push(...decoder.decode(chunk)); } + if (flush) { + lines.push(...decoder.flush()); + } + return lines; } diff --git a/tests/streaming.test.ts b/tests/streaming.test.ts index 6fe9a5781..8e5d0ca31 100644 --- a/tests/streaming.test.ts +++ b/tests/streaming.test.ts @@ -2,6 +2,7 @@ import { Response } from 'node-fetch'; import { PassThrough } from 'stream'; import assert from 'assert'; import { _iterSSEMessages, _decodeChunks as decodeChunks } from 'openai/streaming'; +import { LineDecoder } from 'openai/internal/decoders/line'; describe('line decoder', () => { test('basic', () => { @@ -10,8 +11,8 @@ describe('line decoder', () => { }); test('basic with \\r', () => { - // baz is not included because the line hasn't ended yet expect(decodeChunks(['foo', ' bar\r\nbaz'])).toEqual(['foo bar']); + expect(decodeChunks(['foo', ' bar\r\nbaz'], { flush: true })).toEqual(['foo bar', 'baz']); }); test('trailing new lines', () => { @@ -29,6 +30,56 @@ describe('line decoder', () => { test('escaped new lines with \\r', () => { expect(decodeChunks(['foo', ' bar\\r\\nbaz\n'])).toEqual(['foo bar\\r\\nbaz']); }); + + test('\\r & \\n split across multiple chunks', () => { + expect(decodeChunks(['foo\r', '\n', 'bar'], { flush: true })).toEqual(['foo', 'bar']); + }); + + test('single \\r', () => { + expect(decodeChunks(['foo\r', 'bar'], { flush: true })).toEqual(['foo', 'bar']); + }); + + test('double \\r', () => { + expect(decodeChunks(['foo\r', 'bar\r'], { flush: true })).toEqual(['foo', 'bar']); + expect(decodeChunks(['foo\r', '\r', 'bar'], { flush: true })).toEqual(['foo', '', 'bar']); + // implementation detail that we don't yield the single \r line until a new \r or \n is encountered + expect(decodeChunks(['foo\r', '\r', 'bar'], { flush: false })).toEqual(['foo']); + }); + + test('double \\r then \\r\\n', () => { + expect(decodeChunks(['foo\r', '\r', '\r', '\n', 'bar', '\n'])).toEqual(['foo', '', '', 'bar']); + expect(decodeChunks(['foo\n', '\n', '\n', 'bar', '\n'])).toEqual(['foo', '', '', 'bar']); + }); + + test('double newline', () => { + expect(decodeChunks(['foo\n\nbar'], { flush: true })).toEqual(['foo', '', 'bar']); + expect(decodeChunks(['foo', '\n', '\nbar'], { flush: true })).toEqual(['foo', '', 'bar']); + expect(decodeChunks(['foo\n', '\n', 'bar'], { flush: true })).toEqual(['foo', '', 'bar']); + expect(decodeChunks(['foo', '\n', '\n', 'bar'], { flush: true })).toEqual(['foo', '', 'bar']); + }); + + test('multi-byte characters across chunks', () => { + const decoder = new LineDecoder(); + + // bytes taken from the string 'известни' and arbitrarily split + // so that some multi-byte characters span multiple chunks + expect(decoder.decode(new Uint8Array([0xd0]))).toHaveLength(0); + expect(decoder.decode(new Uint8Array([0xb8, 0xd0, 0xb7, 0xd0]))).toHaveLength(0); + expect( + decoder.decode(new Uint8Array([0xb2, 0xd0, 0xb5, 0xd1, 0x81, 0xd1, 0x82, 0xd0, 0xbd, 0xd0, 0xb8])), + ).toHaveLength(0); + + const decoded = decoder.decode(new Uint8Array([0xa])); + expect(decoded).toEqual(['известни']); + }); + + test('flushing trailing newlines', () => { + expect(decodeChunks(['foo\n', '\nbar'], { flush: true })).toEqual(['foo', '', 'bar']); + }); + + test('flushing empty buffer', () => { + expect(decodeChunks([], { flush: true })).toEqual([]); + }); }); describe('streaming decoding', () => { From 5e5a38a3f5bd45e74eb624fe85664294247bf580 Mon Sep 17 00:00:00 2001 From: Robert Craigie Date: Tue, 11 Feb 2025 11:19:35 +0000 Subject: [PATCH 7/8] fix(assistants): handle `thread.run.incomplete` event --- src/lib/AssistantStream.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/lib/AssistantStream.ts b/src/lib/AssistantStream.ts index caf68e7dd..9b6cc20c5 100644 --- a/src/lib/AssistantStream.ts +++ b/src/lib/AssistantStream.ts @@ -370,6 +370,7 @@ export class AssistantStream case 'thread.run.in_progress': case 'thread.run.requires_action': case 'thread.run.completed': + case 'thread.run.incomplete': case 'thread.run.failed': case 'thread.run.cancelling': case 'thread.run.cancelled': @@ -400,6 +401,8 @@ export class AssistantStream throw new Error( 'Encountered an error event in event processing - errors should be processed earlier', ); + default: + assertNever(event); } } @@ -772,3 +775,5 @@ export class AssistantStream return await this._createToolAssistantStream(runs, threadId, runId, params, options); } } + +function assertNever(_x: never) {} From 0ea723831b52ed22cadfc997ddb45a758e2247db Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 12 Feb 2025 05:07:11 +0000 Subject: [PATCH 8/8] release: 4.84.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 25 +++++++++++++++++++++++++ jsr.json | 2 +- package.json | 2 +- src/version.ts | 2 +- 5 files changed, 29 insertions(+), 4 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6eb0f130e..063dfb8fd 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "4.83.0" + ".": "4.84.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index f61def5e4..d18ddf815 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,30 @@ # Changelog +## 4.84.0 (2025-02-12) + +Full Changelog: [v4.83.0...v4.84.0](https://github.com/openai/openai-node/compare/v4.83.0...v4.84.0) + +### Features + +* **pagination:** avoid fetching when has_more: false ([#1305](https://github.com/openai/openai-node/issues/1305)) ([b6944c6](https://github.com/openai/openai-node/commit/b6944c634b53c9084f2ccf777c2491e89b2cc7af)) + + +### Bug Fixes + +* **api:** add missing reasoning effort + model enums ([#1302](https://github.com/openai/openai-node/issues/1302)) ([14c55c3](https://github.com/openai/openai-node/commit/14c55c312e31f1ed46d02f39a99049f785504a53)) +* **assistants:** handle `thread.run.incomplete` event ([7032cc4](https://github.com/openai/openai-node/commit/7032cc40b8aa0a58459cf114bceb8028a8517400)) +* correctly decode multi-byte characters over multiple chunks ([#1316](https://github.com/openai/openai-node/issues/1316)) ([dd776c4](https://github.com/openai/openai-node/commit/dd776c4867401f527f699bd4b9e567890256e849)) + + +### Chores + +* **internal:** remove segfault-handler dependency ([3521ca3](https://github.com/openai/openai-node/commit/3521ca34e7f5bd51542084e27c084a5d7cc5448b)) + + +### Documentation + +* **readme:** cleanup into multiple files ([da94424](https://github.com/openai/openai-node/commit/da944242e542e9e5e51cb11853c621fc6825ac02)) + ## 4.83.0 (2025-02-05) Full Changelog: [v4.82.0...v4.83.0](https://github.com/openai/openai-node/compare/v4.82.0...v4.83.0) diff --git a/jsr.json b/jsr.json index 6fa05e624..47c478074 100644 --- a/jsr.json +++ b/jsr.json @@ -1,6 +1,6 @@ { "name": "@openai/openai", - "version": "4.83.0", + "version": "4.84.0", "exports": { ".": "./index.ts", "./helpers/zod": "./helpers/zod.ts", diff --git a/package.json b/package.json index df2dcd2bc..96e9b048f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "openai", - "version": "4.83.0", + "version": "4.84.0", "description": "The official TypeScript library for the OpenAI API", "author": "OpenAI ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 13c764d7d..b67556e78 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '4.83.0'; // x-release-please-version +export const VERSION = '4.84.0'; // x-release-please-version