feat(api): run polling helpers (#749)

refactor: rename createAndStream to stream

README.md

@@ -100,13 +100,30 @@ Documentation for each method, request param, and response field are available i
 > [!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 may 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/how-it-works/run-lifecycle)
+
 ### Streaming Helpers
 
 The SDK also includes helpers to process streams and handle the incoming events.
 
 ```ts
 const run = openai.beta.threads.runs
-  .createAndStream(thread.id, {
+  .stream(thread.id, {
     assistant_id: assistant.id,
   })
   .on('textCreated', (text) => process.stdout.write('\nassistant > '))

api.md

@@ -224,6 +224,7 @@ Methods:
 - <code title="post /threads/{thread_id}">client.beta.threads.<a href="./src/resources/beta/threads/threads.ts">update</a>(threadId, { ...params }) -> Thread</code>
 - <code title="delete /threads/{thread_id}">client.beta.threads.<a href="./src/resources/beta/threads/threads.ts">del</a>(threadId) -> ThreadDeleted</code>
 - <code title="post /threads/runs">client.beta.threads.<a href="./src/resources/beta/threads/threads.ts">createAndRun</a>({ ...params }) -> Run</code>
+- <code>client.beta.threads.<a href="./src/resources/beta/threads/threads.ts">createAndRunPoll</a>(body, options?) -> Promise&lt;Threads.Run&gt;</code>
 - <code>client.beta.threads.<a href="./src/resources/beta/threads/threads.ts">createAndRunStream</a>(body, options?) -> AssistantStream</code>
 
 ### Runs
@@ -242,7 +243,11 @@ Methods:
 - <code title="get /threads/{thread_id}/runs">client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">list</a>(threadId, { ...params }) -> RunsPage</code>
 - <code title="post /threads/{thread_id}/runs/{run_id}/cancel">client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">cancel</a>(threadId, runId) -> Run</code>
 - <code title="post /threads/{thread_id}/runs/{run_id}/submit_tool_outputs">client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">submitToolOutputs</a>(threadId, runId, { ...params }) -> Run</code>
+- <code>client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">createAndPoll</a>(threadId, body, options?) -> Promise&lt;Run&gt;</code>
 - <code>client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">createAndStream</a>(threadId, body, options?) -> AssistantStream</code>
+- <code>client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">poll</a>(threadId, runId, options?) -> Promise&lt;Run&gt;</code>
+- <code>client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">stream</a>(threadId, body, options?) -> AssistantStream</code>
+- <code>client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">submitToolOutputsAndPoll</a>(threadId, runId, body, options?) -> Promise&lt;Run&gt;</code>
 - <code>client.beta.threads.runs.<a href="./src/resources/beta/threads/runs/runs.ts">submitToolOutputsStream</a>(threadId, runId, body, options?) -> AssistantStream</code>
 
 #### Steps

examples/assistant-stream.ts

@@ -31,7 +31,7 @@ async function main() {
   console.log('Created thread with Id: ' + threadId);
 
   const run = openai.beta.threads.runs
-    .createAndStream(threadId, {
+    .stream(threadId, {
       assistant_id: assistantId,
     })
     //Subscribe to streaming events and log them

examples/assistants.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env -S npm run tsn -T
 
 import OpenAI from 'openai';
-import { sleep } from 'openai/core';
 
 /**
  * Example of polling for a complete response from an assistant
@@ -32,24 +31,17 @@ async function main() {
   let threadId = thread.id;
   console.log('Created thread with Id: ' + threadId);
 
-  const run = await openai.beta.threads.runs.create(thread.id, {
+  const run = await openai.beta.threads.runs.createAndPoll(thread.id, {
     assistant_id: assistantId,
     additional_instructions: 'Please address the user as Jane Doe. The user has a premium account.',
   });
 
-  console.log('Created run with Id: ' + run.id);
-
-  while (true) {
-    const result = await openai.beta.threads.runs.retrieve(thread.id, run.id);
-    if (result.status == 'completed') {
-      const messages = await openai.beta.threads.messages.list(thread.id);
-      for (const message of messages.getPaginatedItems()) {
-        console.log(message);
-      }
-      break;
-    } else {
-      console.log('Waiting for completion. Current status: ' + result.status);
-      await sleep(5000);
+  console.log('Run finished with status: ' + run.status);
+
+  if (run.status == 'completed') {
+    const messages = await openai.beta.threads.messages.list(thread.id);
+    for (const message of messages.getPaginatedItems()) {
+      console.log(message);
     }
   }
 }

helpers.md

@@ -13,7 +13,7 @@ More information can be found in the documentation: [Assistant Streaming](https:
 
 ```ts
 const run = openai.beta.threads.runs
-  .createAndStream(thread.id, {
+  .stream(thread.id, {
     assistant_id: assistant.id,
   })
   .on('textCreated', (text) => process.stdout.write('\nassistant > '))
@@ -41,7 +41,7 @@ const run = openai.beta.threads.runs
 There are three helper methods for creating streams:
 
 ```ts
-openai.beta.threads.runs.createAndStream();
+openai.beta.threads.runs.stream();
 ```
 
 This method can be used to start and stream the response to an existing run with an associated thread

src/resources/beta/beta.ts

@@ -37,5 +37,6 @@ export namespace Beta {
   export import ThreadCreateAndRunParams = ThreadsAPI.ThreadCreateAndRunParams;
   export import ThreadCreateAndRunParamsNonStreaming = ThreadsAPI.ThreadCreateAndRunParamsNonStreaming;
   export import ThreadCreateAndRunParamsStreaming = ThreadsAPI.ThreadCreateAndRunParamsStreaming;
+  export import ThreadCreateAndRunPollParams = ThreadsAPI.ThreadCreateAndRunPollParams;
   export import ThreadCreateAndRunStreamParams = ThreadsAPI.ThreadCreateAndRunStreamParams;
 }

src/resources/beta/index.ts

@@ -28,6 +28,7 @@ export {
   ThreadCreateAndRunParams,
   ThreadCreateAndRunParamsNonStreaming,
   ThreadCreateAndRunParamsStreaming,
+  ThreadCreateAndRunPollParams,
   ThreadCreateAndRunStreamParams,
   Threads,
 } from './threads/index';

src/resources/beta/threads/index.ts

@@ -36,10 +36,13 @@ export {
   RunCreateParamsStreaming,
   RunUpdateParams,
   RunListParams,
+  RunCreateAndPollParams,
   RunCreateAndStreamParams,
+  RunStreamParams,
   RunSubmitToolOutputsParams,
   RunSubmitToolOutputsParamsNonStreaming,
   RunSubmitToolOutputsParamsStreaming,
+  RunSubmitToolOutputsAndPollParams,
   RunSubmitToolOutputsStreamParams,
   RunsPage,
   Runs,
@@ -52,6 +55,7 @@ export {
   ThreadCreateAndRunParams,
   ThreadCreateAndRunParamsNonStreaming,
   ThreadCreateAndRunParamsStreaming,
+  ThreadCreateAndRunPollParams,
   ThreadCreateAndRunStreamParams,
   Threads,
 } from './threads';

src/resources/beta/threads/runs/index.ts

@@ -31,10 +31,13 @@ export {
   RunCreateParamsStreaming,
   RunUpdateParams,
   RunListParams,
+  RunCreateAndPollParams,
   RunCreateAndStreamParams,
+  RunStreamParams,
   RunSubmitToolOutputsParams,
   RunSubmitToolOutputsParamsNonStreaming,
   RunSubmitToolOutputsParamsStreaming,
+  RunSubmitToolOutputsAndPollParams,
   RunSubmitToolOutputsStreamParams,
   RunsPage,
   Runs,