1# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
  2
  3from typing import List, Optional
  4from typing_extensions import Literal
  5
  6from ...._models import BaseModel
  7from .run_status import RunStatus
  8from ..assistant_tool import AssistantTool
  9from ...shared.metadata import Metadata
 10from ..assistant_tool_choice_option import AssistantToolChoiceOption
 11from ..assistant_response_format_option import AssistantResponseFormatOption
 12from .required_action_function_tool_call import RequiredActionFunctionToolCall
 13
 14__all__ = [
 15    "Run",
 16    "IncompleteDetails",
 17    "LastError",
 18    "RequiredAction",
 19    "RequiredActionSubmitToolOutputs",
 20    "TruncationStrategy",
 21    "Usage",
 22]
 23
 24
 25class IncompleteDetails(BaseModel):
 26    reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]] = None
 27    """The reason why the run is incomplete.
 28
 29    This will point to which specific token limit was reached over the course of the
 30    run.
 31    """
 32
 33
 34class LastError(BaseModel):
 35    code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]
 36    """One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`."""
 37
 38    message: str
 39    """A human-readable description of the error."""
 40
 41
 42class RequiredActionSubmitToolOutputs(BaseModel):
 43    tool_calls: List[RequiredActionFunctionToolCall]
 44    """A list of the relevant tool calls."""
 45
 46
 47class RequiredAction(BaseModel):
 48    submit_tool_outputs: RequiredActionSubmitToolOutputs
 49    """Details on the tool outputs needed for this run to continue."""
 50
 51    type: Literal["submit_tool_outputs"]
 52    """For now, this is always `submit_tool_outputs`."""
 53
 54
 55class TruncationStrategy(BaseModel):
 56    type: Literal["auto", "last_messages"]
 57    """The truncation strategy to use for the thread.
 58
 59    The default is `auto`. If set to `last_messages`, the thread will be truncated
 60    to the n most recent messages in the thread. When set to `auto`, messages in the
 61    middle of the thread will be dropped to fit the context length of the model,
 62    `max_prompt_tokens`.
 63    """
 64
 65    last_messages: Optional[int] = None
 66    """
 67    The number of most recent messages from the thread when constructing the context
 68    for the run.
 69    """
 70
 71
 72class Usage(BaseModel):
 73    completion_tokens: int
 74    """Number of completion tokens used over the course of the run."""
 75
 76    prompt_tokens: int
 77    """Number of prompt tokens used over the course of the run."""
 78
 79    total_tokens: int
 80    """Total number of tokens used (prompt + completion)."""
 81
 82
 83class Run(BaseModel):
 84    id: str
 85    """The identifier, which can be referenced in API endpoints."""
 86
 87    assistant_id: str
 88    """
 89    The ID of the
 90    [assistant](https://platform.openai.com/docs/api-reference/assistants) used for
 91    execution of this run.
 92    """
 93
 94    cancelled_at: Optional[int] = None
 95    """The Unix timestamp (in seconds) for when the run was cancelled."""
 96
 97    completed_at: Optional[int] = None
 98    """The Unix timestamp (in seconds) for when the run was completed."""
 99
100    created_at: int
101    """The Unix timestamp (in seconds) for when the run was created."""
102
103    expires_at: Optional[int] = None
104    """The Unix timestamp (in seconds) for when the run will expire."""
105
106    failed_at: Optional[int] = None
107    """The Unix timestamp (in seconds) for when the run failed."""
108
109    incomplete_details: Optional[IncompleteDetails] = None
110    """Details on why the run is incomplete.
111
112    Will be `null` if the run is not incomplete.
113    """
114
115    instructions: str
116    """
117    The instructions that the
118    [assistant](https://platform.openai.com/docs/api-reference/assistants) used for
119    this run.
120    """
121
122    last_error: Optional[LastError] = None
123    """The last error associated with this run. Will be `null` if there are no errors."""
124
125    max_completion_tokens: Optional[int] = None
126    """
127    The maximum number of completion tokens specified to have been used over the
128    course of the run.
129    """
130
131    max_prompt_tokens: Optional[int] = None
132    """
133    The maximum number of prompt tokens specified to have been used over the course
134    of the run.
135    """
136
137    metadata: Optional[Metadata] = None
138    """Set of 16 key-value pairs that can be attached to an object.
139
140    This can be useful for storing additional information about the object in a
141    structured format, and querying for objects via API or the dashboard.
142
143    Keys are strings with a maximum length of 64 characters. Values are strings with
144    a maximum length of 512 characters.
145    """
146
147    model: str
148    """
149    The model that the
150    [assistant](https://platform.openai.com/docs/api-reference/assistants) used for
151    this run.
152    """
153
154    object: Literal["thread.run"]
155    """The object type, which is always `thread.run`."""
156
157    parallel_tool_calls: bool
158    """
159    Whether to enable
160    [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling)
161    during tool use.
162    """
163
164    required_action: Optional[RequiredAction] = None
165    """Details on the action required to continue the run.
166
167    Will be `null` if no action is required.
168    """
169
170    response_format: Optional[AssistantResponseFormatOption] = None
171    """Specifies the format that the model must output.
172
173    Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o),
174    [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4),
175    and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
176
177    Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured
178    Outputs which ensures the model will match your supplied JSON schema. Learn more
179    in the
180    [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs).
181
182    Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the
183    message the model generates is valid JSON.
184
185    **Important:** when using JSON mode, you **must** also instruct the model to
186    produce JSON yourself via a system or user message. Without this, the model may
187    generate an unending stream of whitespace until the generation reaches the token
188    limit, resulting in a long-running and seemingly "stuck" request. Also note that
189    the message content may be partially cut off if `finish_reason="length"`, which
190    indicates the generation exceeded `max_tokens` or the conversation exceeded the
191    max context length.
192    """
193
194    started_at: Optional[int] = None
195    """The Unix timestamp (in seconds) for when the run was started."""
196
197    status: RunStatus
198    """
199    The status of the run, which can be either `queued`, `in_progress`,
200    `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`,
201    `incomplete`, or `expired`.
202    """
203
204    thread_id: str
205    """
206    The ID of the [thread](https://platform.openai.com/docs/api-reference/threads)
207    that was executed on as a part of this run.
208    """
209
210    tool_choice: Optional[AssistantToolChoiceOption] = None
211    """
212    Controls which (if any) tool is called by the model. `none` means the model will
213    not call any tools and instead generates a message. `auto` is the default value
214    and means the model can pick between generating a message or calling one or more
215    tools. `required` means the model must call one or more tools before responding
216    to the user. Specifying a particular tool like `{"type": "file_search"}` or
217    `{"type": "function", "function": {"name": "my_function"}}` forces the model to
218    call that tool.
219    """
220
221    tools: List[AssistantTool]
222    """
223    The list of tools that the
224    [assistant](https://platform.openai.com/docs/api-reference/assistants) used for
225    this run.
226    """
227
228    truncation_strategy: Optional[TruncationStrategy] = None
229    """Controls for how a thread will be truncated prior to the run.
230
231    Use this to control the initial context window of the run.
232    """
233
234    usage: Optional[Usage] = None
235    """Usage statistics related to the run.
236
237    This value will be `null` if the run is not in a terminal state (i.e.
238    `in_progress`, `queued`, etc.).
239    """
240
241    temperature: Optional[float] = None
242    """The sampling temperature used for this run. If not set, defaults to 1."""
243
244    top_p: Optional[float] = None
245    """The nucleus sampling value used for this run. If not set, defaults to 1."""