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

refactor: rename createAndStream to stream

README.md

@@ -51,12 +51,30 @@ we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
 to add `OPENAI_API_KEY="My API Key"` to your `.env` file
 so that your API Key is not stored in source control.
 
+### 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 '\_and_poll'.
+
+For instance to create a Run and poll until it reaches a terminal state you can run:
+
+```python
+run = client.beta.threads.runs.create_and_poll(
+    thread_id=thread.id,
+    assistant_id=assistant.id,
+)
+```
+
+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.
 
 ```python
-with client.beta.threads.runs.create_and_stream(
+with client.beta.threads.runs.stream(
     thread_id=thread.id,
     assistant_id=assistant.id,
     instructions="Please address the user as Jane Doe. The user has a premium account.",

api.md

@@ -230,6 +230,7 @@ Methods:
 - <code title="post /threads/{thread_id}">client.beta.threads.<a href="./src/openai/resources/beta/threads/threads.py">update</a>(thread_id, \*\*<a href="src/openai/types/beta/thread_update_params.py">params</a>) -> <a href="./src/openai/types/beta/thread.py">Thread</a></code>
 - <code title="delete /threads/{thread_id}">client.beta.threads.<a href="./src/openai/resources/beta/threads/threads.py">delete</a>(thread_id) -> <a href="./src/openai/types/beta/thread_deleted.py">ThreadDeleted</a></code>
 - <code title="post /threads/runs">client.beta.threads.<a href="./src/openai/resources/beta/threads/threads.py">create_and_run</a>(\*\*<a href="src/openai/types/beta/thread_create_and_run_params.py">params</a>) -> <a href="./src/openai/types/beta/threads/run.py">Run</a></code>
+- <code>client.beta.threads.<a href="./src/openai/resources/beta/threads/threads.py">create_and_run_poll</a>(\*args) -> Run</code>
 - <code>client.beta.threads.<a href="./src/openai/resources/beta/threads/threads.py">create_and_run_stream</a>(\*args) -> AssistantStreamManager[AssistantEventHandler] | AssistantStreamManager[AssistantEventHandlerT]</code>
 
 ### Runs
@@ -248,7 +249,11 @@ Methods:
 - <code title="get /threads/{thread_id}/runs">client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">list</a>(thread_id, \*\*<a href="src/openai/types/beta/threads/run_list_params.py">params</a>) -> <a href="./src/openai/types/beta/threads/run.py">SyncCursorPage[Run]</a></code>
 - <code title="post /threads/{thread_id}/runs/{run_id}/cancel">client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">cancel</a>(run_id, \*, thread_id) -> <a href="./src/openai/types/beta/threads/run.py">Run</a></code>
 - <code title="post /threads/{thread_id}/runs/{run_id}/submit_tool_outputs">client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">submit_tool_outputs</a>(run_id, \*, thread_id, \*\*<a href="src/openai/types/beta/threads/run_submit_tool_outputs_params.py">params</a>) -> <a href="./src/openai/types/beta/threads/run.py">Run</a></code>
+- <code>client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">create_and_poll</a>(\*args) -> Run</code>
 - <code>client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">create_and_stream</a>(\*args) -> AssistantStreamManager[AssistantEventHandler] | AssistantStreamManager[AssistantEventHandlerT]</code>
+- <code>client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">poll</a>(\*args) -> Run</code>
+- <code>client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">stream</a>(\*args) -> AssistantStreamManager[AssistantEventHandler] | AssistantStreamManager[AssistantEventHandlerT]</code>
+- <code>client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">submit_tool_outputs_and_poll</a>(\*args) -> Run</code>
 - <code>client.beta.threads.runs.<a href="./src/openai/resources/beta/threads/runs/runs.py">submit_tool_outputs_stream</a>(\*args) -> AssistantStreamManager[AssistantEventHandler] | AssistantStreamManager[AssistantEventHandlerT]</code>
 
 #### Steps

examples/assistant.py

@@ -1,4 +1,3 @@
-import time
 
 import openai
 
@@ -20,28 +19,20 @@
     content="I need to solve the equation `3x + 11 = 14`. Can you help me?",
 )
 
-run = client.beta.threads.runs.create(
+run = client.beta.threads.runs.create_and_poll(
     thread_id=thread.id,
     assistant_id=assistant.id,
     instructions="Please address the user as Jane Doe. The user has a premium account.",
 )
 
-print("checking assistant status. ")
-while True:
-    run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
+print("Run completed with status: " + run.status)
 
-    if run.status == "completed":
-        print("done!")
-        messages = client.beta.threads.messages.list(thread_id=thread.id)
+if run.status == "completed":
+    messages = client.beta.threads.messages.list(thread_id=thread.id)
 
-        print("messages: ")
-        for message in messages:
-            assert message.content[0].type == "text"
-            print({"role": message.role, "message": message.content[0].text.value})
+    print("messages: ")
+    for message in messages:
+        assert message.content[0].type == "text"
+        print({"role": message.role, "message": message.content[0].text.value})
 
-        client.beta.assistants.delete(assistant.id)
-
-        break
-    else:
-        print("in progress...")
-        time.sleep(5)
+    client.beta.assistants.delete(assistant.id)

examples/assistant_stream_helpers.py

@@ -63,7 +63,7 @@ def main() -> None:
         )
         print(f"Question: {question}\n")
 
-        with client.beta.threads.runs.create_and_stream(
+        with client.beta.threads.runs.stream(
             thread_id=thread.id,
             assistant_id=assistant.id,
             instructions="Please address the user as Jane Doe. The user has a premium account.",

helpers.md

@@ -46,11 +46,11 @@ class EventHandler(AssistantEventHandler):
           if output.type == "logs":
             print(f"\n{output.logs}", flush=True)
 
-# Then, we use the `create_and_stream` SDK helper
+# Then, we use the `stream` SDK helper
 # with the `EventHandler` class to create the Run
 # and stream the response.
 
-with client.beta.threads.runs.create_and_stream(
+with client.beta.threads.runs.stream(
   thread_id="thread_id",
   assistant_id="assistant_id",
   event_handler=EventHandler(),
@@ -63,7 +63,7 @@ with client.beta.threads.runs.create_and_stream(
 You can also iterate over all the streamed events.
 
 ```python
-with client.beta.threads.runs.create_and_stream(
+with client.beta.threads.runs.stream(
   thread_id=thread.id,
   assistant_id=assistant.id
 ) as stream:
@@ -78,7 +78,7 @@ with client.beta.threads.runs.create_and_stream(
 You can also iterate over just the text deltas received
 
 ```python
-with client.beta.threads.runs.create_and_stream(
+with client.beta.threads.runs.stream(
   thread_id=thread.id,
   assistant_id=assistant.id
 ) as stream:
@@ -91,7 +91,7 @@ with client.beta.threads.runs.create_and_stream(
 There are three helper methods for creating streams:
 
 ```python
-client.beta.threads.runs.create_and_stream()
+client.beta.threads.runs.stream()
 ```
 
 This method can be used to start and stream the response to an existing run with an associated thread