archastro.platform.types.ai
1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved. 2# This file is auto-generated by @archastro/sdk-generator. Do not edit. 3# Content hash: c92e31a74295 4 5from typing import Any 6 7from pydantic import BaseModel, Field 8 9 10class AIChatStreamDone(BaseModel): 11 """ 12 Terminal event marking the end of a streaming chat completion (SSE `done` event). 13 """ 14 15 finish_reason: str | None = Field( 16 default=None, description="The overall finish reason for the completion." 17 ) 18 run_count: int | None = Field( 19 default=None, 20 description="Number of model runs executed, including continuations triggered by tool calls.", 21 ) 22 total_usage: dict[str, Any] | None = Field( 23 default=None, 24 description="Aggregate token usage across every run in the completion (including tool-call continuations), keyed by model ID.", 25 ) 26 usage: dict[str, Any] | None = Field( 27 default=None, description="Token usage for the final run, keyed by model ID." 28 ) 29 30 31class AIChatStreamError(BaseModel): 32 """ 33 Terminal error event for a streaming chat completion (SSE `error` event). 34 """ 35 36 message: str = Field( 37 ..., description="Human-readable description of the error that terminated the stream." 38 ) 39 40 41class AIToolCall(BaseModel): 42 """ 43 A tool (function) call emitted by the assistant within an AI message. Mirrors the OpenAI tool-call object format. 44 """ 45 46 arguments: dict[str, Any] = Field( 47 ..., 48 description="Arguments the model wants to pass to the tool, as a key-value map. Deserialize and validate these against the tool's input schema before executing.", 49 ) 50 id: str = Field( 51 ..., 52 description="Unique identifier for this tool call, assigned by the model. Use this value as `id` when submitting the corresponding tool result.", 53 ) 54 name: str = Field( 55 ..., 56 description='Name of the tool or function the model wants to invoke, e.g. `"web_search"` or `"run_code"`.', 57 ) 58 thought_signature: str | None = Field( 59 default=None, 60 description="Opaque signature representing the model's internal reasoning that led to this tool call. `null` when the provider does not expose chain-of-thought data.", 61 ) 62 63 64class AIToolResult(BaseModel): 65 """ 66 The result of executing a tool call, submitted back to the model as a tool-role message. Mirrors the OpenAI tool-result object format. 67 """ 68 69 content: str | None = Field( 70 default=None, 71 description="Plain-text output produced by the tool execution. `null` when the result is expressed entirely through `resolution`.", 72 ) 73 id: str = Field( 74 ..., 75 description="ID of the tool call this result satisfies. Must match the `id` from the corresponding `AIToolCall`.", 76 ) 77 name: str = Field( 78 ..., 79 description='Name of the tool or function that was executed, e.g. `"web_search"`. Must match the `name` from the corresponding `AIToolCall`.', 80 ) 81 resolution: Any | None = Field( 82 default=None, 83 description="Structured result data from the tool execution. Shape varies by tool. `null` when the result is expressed as plain text in `content`.", 84 ) 85 86 87class AIMessage(BaseModel): 88 """ 89 A single message in an AI conversation, following the OpenAI-compatible chat format. Used in both request inputs and completion responses. 90 """ 91 92 content: str | None = Field( 93 default=None, 94 description="Plain-text content of the message. Present for `system`, `user`, and `assistant` messages. `null` when the message body is expressed through `content_parts` or `tool_calls`.", 95 ) 96 content_parts: list[dict[str, Any]] | None = Field( 97 default=None, 98 description='Multimodal content parts for the message, used when the body includes images or mixed media. Each part is a map with a `type` key (`"text"`, `"image_url"`, or `"image_data"`). `null` when `content` is set.', 99 ) 100 resume_token: str | None = Field( 101 default=None, 102 description="Opaque token that can be passed on a subsequent request to resume this conversation from the current state. `null` when the provider does not support conversation resumption.", 103 ) 104 role: str = Field( 105 ..., 106 description='The speaker role for this message. One of `"system"`, `"user"`, `"assistant"`, or `"tool"`.', 107 ) 108 structured_output: Any | None = Field( 109 default=None, 110 description="Parsed structured data returned by the model when a JSON schema or structured-output mode was requested. Shape varies by the schema supplied at call time. `null` when structured output was not requested.", 111 ) 112 tool_calls: list[AIToolCall] | None = Field( 113 default=None, 114 description="Tool calls requested by the model in an `assistant` message. Present only on assistant messages that invoke one or more tools. `null` on all other message roles.", 115 ) 116 tool_results: list[AIToolResult] | None = Field( 117 default=None, 118 description="Tool execution results provided in a `tool` message. Each entry corresponds to a prior tool call by its `id`. `null` on all other message roles.", 119 ) 120 121 122class AIChatStreamMessageComplete(BaseModel): 123 """ 124 The fully assembled assistant message for one run of a streaming chat completion (SSE `message_complete` event). 125 """ 126 127 finish_reason: str | None = Field( 128 default=None, 129 description='Why the model stopped generating this message, e.g. `"stop"`, `"length"`, or `"tool_calls"`.', 130 ) 131 message: AIMessage = Field( 132 ..., 133 description="The complete assistant message for this run, assembled from the preceding deltas.", 134 ) 135 usage: dict[str, Any] | None = Field( 136 default=None, 137 description="Token consumption for this run, keyed by model ID. `null` when usage data is unavailable.", 138 ) 139 140 141class AIChatStreamMessageDelta(BaseModel): 142 """ 143 Incremental assistant text emitted during a streaming chat completion (SSE `message_delta` event). 144 """ 145 146 delta: str = Field( 147 ..., 148 description="The chunk of assistant text produced since the previous `message_delta` event. Concatenate deltas in order to reconstruct the message.", 149 ) 150 151 152class AIChatStreamToolCallDelta(BaseModel): 153 """ 154 Incremental tool-call data emitted as the model assembles a tool invocation (SSE `tool_call_delta` event). 155 """ 156 157 delta: str | None = Field( 158 default=None, 159 description="A chunk of the tool call's serialized arguments. Concatenate deltas to reconstruct the arguments JSON.", 160 ) 161 id: str | None = Field( 162 default=None, 163 description="Identifier of the tool call this delta belongs to, once the model has assigned one.", 164 ) 165 name: str | None = Field(default=None, description="Name of the tool being called, once known.") 166 167 168class AIChatStreamToolResult(BaseModel): 169 """ 170 The result of a server-executed tool, streamed back into the run (SSE `tool_result` event). 171 """ 172 173 content: str | None = Field( 174 default=None, description="The tool's output, serialized as a string." 175 ) 176 id: str | None = Field(default=None, description="ID of the tool call this result satisfies.") 177 name: str | None = Field( 178 default=None, description="Name of the tool that produced this result." 179 ) 180 resolution: str | None = Field( 181 default=None, description='How the tool call resolved, e.g. `"ok"` or `"error"`.' 182 ) 183 184 185class AICompletionResult(BaseModel): 186 """ 187 The result of an AI chat completion request. Returned by chat completion endpoints after the model finishes generating. 188 """ 189 190 finish_reason: str = Field( 191 ..., 192 description='The reason the model stopped generating. Common values include `"stop"` (natural end), `"length"` (token limit reached), and `"tool_calls"` (the model invoked a tool).', 193 ) 194 message: AIMessage = Field( 195 ..., description="The final assistant message produced by the completion." 196 ) 197 messages: list[AIMessage] = Field( 198 ..., 199 description="The complete message history for the conversation, including all user, assistant, and tool messages in order.", 200 ) 201 token_usage: dict[str, Any] | None = Field( 202 default=None, 203 description='Token consumption breakdown keyed by model ID. Each value is a map with `"input_tokens"` and `"output_tokens"` counts. `null` when usage data is unavailable.', 204 ) 205 206 207class AIImageResult(BaseModel): 208 """ 209 The result returned by an AI image generation or editing operation. Contains the generated image (as inline data or a URL) along with dimension, size, and usage metadata. 210 """ 211 212 aspect_ratio: str | None = Field( 213 default=None, 214 description='Aspect ratio of the generated image, e.g. `"16:9"` or `"1:1"`. `null` when not reported by the provider.', 215 ) 216 height: int | None = Field( 217 default=None, 218 description="Height of the generated image in pixels. `null` when the provider does not report dimensions.", 219 ) 220 image_data: str | None = Field( 221 default=None, 222 description="The generated image encoded as a base64 string. Present when the provider returns inline image data. `null` when `image_url` is set instead.", 223 ) 224 image_size: str | None = Field( 225 default=None, 226 description='Resolution tier label for the image, e.g. `"1K"` or `"2K"`. `null` when the provider does not include a tier label.', 227 ) 228 image_type: str | None = Field( 229 default=None, 230 description='MIME type of the generated image, e.g. `"image/png"` or `"image/jpeg"`. `null` when the provider does not report a content type.', 231 ) 232 image_url: str | None = Field( 233 default=None, 234 description="Temporary URL pointing to the generated image hosted by the provider. Present when the provider returns a URL rather than inline data. `null` when `image_data` is set instead.", 235 ) 236 model: str = Field( 237 ..., 238 description='Identifier of the model that produced the image, e.g. `"dall-e-3"` or `"imagen-3"`.', 239 ) 240 revised_prompt: str | None = Field( 241 default=None, 242 description="The prompt as rewritten by the provider before generation. Some providers (e.g. DALL-E 3) automatically expand or safety-check the original prompt. `null` when the provider does not revise prompts.", 243 ) 244 size: str | None = Field( 245 default=None, 246 description='Canonical size string as returned by the provider, e.g. `"1024x1024"`. `null` when not reported.', 247 ) 248 usage: dict[str, Any] | None = Field( 249 default=None, 250 description="Provider-reported token and compute usage for the request. Structure varies by provider. `null` when usage data is unavailable.", 251 ) 252 width: int | None = Field( 253 default=None, 254 description="Width of the generated image in pixels. `null` when the provider does not report dimensions.", 255 )
class
AIChatStreamDone(pydantic.main.BaseModel):
11class AIChatStreamDone(BaseModel): 12 """ 13 Terminal event marking the end of a streaming chat completion (SSE `done` event). 14 """ 15 16 finish_reason: str | None = Field( 17 default=None, description="The overall finish reason for the completion." 18 ) 19 run_count: int | None = Field( 20 default=None, 21 description="Number of model runs executed, including continuations triggered by tool calls.", 22 ) 23 total_usage: dict[str, Any] | None = Field( 24 default=None, 25 description="Aggregate token usage across every run in the completion (including tool-call continuations), keyed by model ID.", 26 ) 27 usage: dict[str, Any] | None = Field( 28 default=None, description="Token usage for the final run, keyed by model ID." 29 )
Terminal event marking the end of a streaming chat completion (SSE done event).
run_count: int | None =
None
Number of model runs executed, including continuations triggered by tool calls.
class
AIChatStreamError(pydantic.main.BaseModel):
32class AIChatStreamError(BaseModel): 33 """ 34 Terminal error event for a streaming chat completion (SSE `error` event). 35 """ 36 37 message: str = Field( 38 ..., description="Human-readable description of the error that terminated the stream." 39 )
Terminal error event for a streaming chat completion (SSE error event).
class
AIToolCall(pydantic.main.BaseModel):
42class AIToolCall(BaseModel): 43 """ 44 A tool (function) call emitted by the assistant within an AI message. Mirrors the OpenAI tool-call object format. 45 """ 46 47 arguments: dict[str, Any] = Field( 48 ..., 49 description="Arguments the model wants to pass to the tool, as a key-value map. Deserialize and validate these against the tool's input schema before executing.", 50 ) 51 id: str = Field( 52 ..., 53 description="Unique identifier for this tool call, assigned by the model. Use this value as `id` when submitting the corresponding tool result.", 54 ) 55 name: str = Field( 56 ..., 57 description='Name of the tool or function the model wants to invoke, e.g. `"web_search"` or `"run_code"`.', 58 ) 59 thought_signature: str | None = Field( 60 default=None, 61 description="Opaque signature representing the model's internal reasoning that led to this tool call. `null` when the provider does not expose chain-of-thought data.", 62 )
A tool (function) call emitted by the assistant within an AI message. Mirrors the OpenAI tool-call object format.
arguments: dict[str, typing.Any] =
PydanticUndefined
Arguments the model wants to pass to the tool, as a key-value map. Deserialize and validate these against the tool's input schema before executing.
id: str =
PydanticUndefined
Unique identifier for this tool call, assigned by the model. Use this value as id when submitting the corresponding tool result.
class
AIToolResult(pydantic.main.BaseModel):
65class AIToolResult(BaseModel): 66 """ 67 The result of executing a tool call, submitted back to the model as a tool-role message. Mirrors the OpenAI tool-result object format. 68 """ 69 70 content: str | None = Field( 71 default=None, 72 description="Plain-text output produced by the tool execution. `null` when the result is expressed entirely through `resolution`.", 73 ) 74 id: str = Field( 75 ..., 76 description="ID of the tool call this result satisfies. Must match the `id` from the corresponding `AIToolCall`.", 77 ) 78 name: str = Field( 79 ..., 80 description='Name of the tool or function that was executed, e.g. `"web_search"`. Must match the `name` from the corresponding `AIToolCall`.', 81 ) 82 resolution: Any | None = Field( 83 default=None, 84 description="Structured result data from the tool execution. Shape varies by tool. `null` when the result is expressed as plain text in `content`.", 85 )
The result of executing a tool call, submitted back to the model as a tool-role message. Mirrors the OpenAI tool-result object format.
content: str | None =
None
Plain-text output produced by the tool execution. null when the result is expressed entirely through resolution.
id: str =
PydanticUndefined
ID of the tool call this result satisfies. Must match the id from the corresponding AIToolCall.
name: str =
PydanticUndefined
Name of the tool or function that was executed, e.g. "web_search". Must match the name from the corresponding AIToolCall.
resolution: typing.Any | None =
None
Structured result data from the tool execution. Shape varies by tool. null when the result is expressed as plain text in content.
class
AIMessage(pydantic.main.BaseModel):
88class AIMessage(BaseModel): 89 """ 90 A single message in an AI conversation, following the OpenAI-compatible chat format. Used in both request inputs and completion responses. 91 """ 92 93 content: str | None = Field( 94 default=None, 95 description="Plain-text content of the message. Present for `system`, `user`, and `assistant` messages. `null` when the message body is expressed through `content_parts` or `tool_calls`.", 96 ) 97 content_parts: list[dict[str, Any]] | None = Field( 98 default=None, 99 description='Multimodal content parts for the message, used when the body includes images or mixed media. Each part is a map with a `type` key (`"text"`, `"image_url"`, or `"image_data"`). `null` when `content` is set.', 100 ) 101 resume_token: str | None = Field( 102 default=None, 103 description="Opaque token that can be passed on a subsequent request to resume this conversation from the current state. `null` when the provider does not support conversation resumption.", 104 ) 105 role: str = Field( 106 ..., 107 description='The speaker role for this message. One of `"system"`, `"user"`, `"assistant"`, or `"tool"`.', 108 ) 109 structured_output: Any | None = Field( 110 default=None, 111 description="Parsed structured data returned by the model when a JSON schema or structured-output mode was requested. Shape varies by the schema supplied at call time. `null` when structured output was not requested.", 112 ) 113 tool_calls: list[AIToolCall] | None = Field( 114 default=None, 115 description="Tool calls requested by the model in an `assistant` message. Present only on assistant messages that invoke one or more tools. `null` on all other message roles.", 116 ) 117 tool_results: list[AIToolResult] | None = Field( 118 default=None, 119 description="Tool execution results provided in a `tool` message. Each entry corresponds to a prior tool call by its `id`. `null` on all other message roles.", 120 )
A single message in an AI conversation, following the OpenAI-compatible chat format. Used in both request inputs and completion responses.
content: str | None =
None
Plain-text content of the message. Present for system, user, and assistant messages. null when the message body is expressed through content_parts or tool_calls.
content_parts: list[dict[str, typing.Any]] | None =
None
Multimodal content parts for the message, used when the body includes images or mixed media. Each part is a map with a type key ("text", "image_url", or "image_data"). null when content is set.
resume_token: str | None =
None
Opaque token that can be passed on a subsequent request to resume this conversation from the current state. null when the provider does not support conversation resumption.
role: str =
PydanticUndefined
The speaker role for this message. One of "system", "user", "assistant", or "tool".
structured_output: typing.Any | None =
None
Parsed structured data returned by the model when a JSON schema or structured-output mode was requested. Shape varies by the schema supplied at call time. null when structured output was not requested.
Tool calls requested by the model in an assistant message. Present only on assistant messages that invoke one or more tools. null on all other message roles.
class
AIChatStreamMessageComplete(pydantic.main.BaseModel):
123class AIChatStreamMessageComplete(BaseModel): 124 """ 125 The fully assembled assistant message for one run of a streaming chat completion (SSE `message_complete` event). 126 """ 127 128 finish_reason: str | None = Field( 129 default=None, 130 description='Why the model stopped generating this message, e.g. `"stop"`, `"length"`, or `"tool_calls"`.', 131 ) 132 message: AIMessage = Field( 133 ..., 134 description="The complete assistant message for this run, assembled from the preceding deltas.", 135 ) 136 usage: dict[str, Any] | None = Field( 137 default=None, 138 description="Token consumption for this run, keyed by model ID. `null` when usage data is unavailable.", 139 )
The fully assembled assistant message for one run of a streaming chat completion (SSE message_complete event).
finish_reason: str | None =
None
Why the model stopped generating this message, e.g. "stop", "length", or "tool_calls".
class
AIChatStreamMessageDelta(pydantic.main.BaseModel):
142class AIChatStreamMessageDelta(BaseModel): 143 """ 144 Incremental assistant text emitted during a streaming chat completion (SSE `message_delta` event). 145 """ 146 147 delta: str = Field( 148 ..., 149 description="The chunk of assistant text produced since the previous `message_delta` event. Concatenate deltas in order to reconstruct the message.", 150 )
Incremental assistant text emitted during a streaming chat completion (SSE message_delta event).
class
AIChatStreamToolCallDelta(pydantic.main.BaseModel):
153class AIChatStreamToolCallDelta(BaseModel): 154 """ 155 Incremental tool-call data emitted as the model assembles a tool invocation (SSE `tool_call_delta` event). 156 """ 157 158 delta: str | None = Field( 159 default=None, 160 description="A chunk of the tool call's serialized arguments. Concatenate deltas to reconstruct the arguments JSON.", 161 ) 162 id: str | None = Field( 163 default=None, 164 description="Identifier of the tool call this delta belongs to, once the model has assigned one.", 165 ) 166 name: str | None = Field(default=None, description="Name of the tool being called, once known.")
Incremental tool-call data emitted as the model assembles a tool invocation (SSE tool_call_delta event).
delta: str | None =
None
A chunk of the tool call's serialized arguments. Concatenate deltas to reconstruct the arguments JSON.
class
AIChatStreamToolResult(pydantic.main.BaseModel):
169class AIChatStreamToolResult(BaseModel): 170 """ 171 The result of a server-executed tool, streamed back into the run (SSE `tool_result` event). 172 """ 173 174 content: str | None = Field( 175 default=None, description="The tool's output, serialized as a string." 176 ) 177 id: str | None = Field(default=None, description="ID of the tool call this result satisfies.") 178 name: str | None = Field( 179 default=None, description="Name of the tool that produced this result." 180 ) 181 resolution: str | None = Field( 182 default=None, description='How the tool call resolved, e.g. `"ok"` or `"error"`.' 183 )
The result of a server-executed tool, streamed back into the run (SSE tool_result event).
class
AICompletionResult(pydantic.main.BaseModel):
186class AICompletionResult(BaseModel): 187 """ 188 The result of an AI chat completion request. Returned by chat completion endpoints after the model finishes generating. 189 """ 190 191 finish_reason: str = Field( 192 ..., 193 description='The reason the model stopped generating. Common values include `"stop"` (natural end), `"length"` (token limit reached), and `"tool_calls"` (the model invoked a tool).', 194 ) 195 message: AIMessage = Field( 196 ..., description="The final assistant message produced by the completion." 197 ) 198 messages: list[AIMessage] = Field( 199 ..., 200 description="The complete message history for the conversation, including all user, assistant, and tool messages in order.", 201 ) 202 token_usage: dict[str, Any] | None = Field( 203 default=None, 204 description='Token consumption breakdown keyed by model ID. Each value is a map with `"input_tokens"` and `"output_tokens"` counts. `null` when usage data is unavailable.', 205 )
The result of an AI chat completion request. Returned by chat completion endpoints after the model finishes generating.
finish_reason: str =
PydanticUndefined
The reason the model stopped generating. Common values include "stop" (natural end), "length" (token limit reached), and "tool_calls" (the model invoked a tool).
class
AIImageResult(pydantic.main.BaseModel):
208class AIImageResult(BaseModel): 209 """ 210 The result returned by an AI image generation or editing operation. Contains the generated image (as inline data or a URL) along with dimension, size, and usage metadata. 211 """ 212 213 aspect_ratio: str | None = Field( 214 default=None, 215 description='Aspect ratio of the generated image, e.g. `"16:9"` or `"1:1"`. `null` when not reported by the provider.', 216 ) 217 height: int | None = Field( 218 default=None, 219 description="Height of the generated image in pixels. `null` when the provider does not report dimensions.", 220 ) 221 image_data: str | None = Field( 222 default=None, 223 description="The generated image encoded as a base64 string. Present when the provider returns inline image data. `null` when `image_url` is set instead.", 224 ) 225 image_size: str | None = Field( 226 default=None, 227 description='Resolution tier label for the image, e.g. `"1K"` or `"2K"`. `null` when the provider does not include a tier label.', 228 ) 229 image_type: str | None = Field( 230 default=None, 231 description='MIME type of the generated image, e.g. `"image/png"` or `"image/jpeg"`. `null` when the provider does not report a content type.', 232 ) 233 image_url: str | None = Field( 234 default=None, 235 description="Temporary URL pointing to the generated image hosted by the provider. Present when the provider returns a URL rather than inline data. `null` when `image_data` is set instead.", 236 ) 237 model: str = Field( 238 ..., 239 description='Identifier of the model that produced the image, e.g. `"dall-e-3"` or `"imagen-3"`.', 240 ) 241 revised_prompt: str | None = Field( 242 default=None, 243 description="The prompt as rewritten by the provider before generation. Some providers (e.g. DALL-E 3) automatically expand or safety-check the original prompt. `null` when the provider does not revise prompts.", 244 ) 245 size: str | None = Field( 246 default=None, 247 description='Canonical size string as returned by the provider, e.g. `"1024x1024"`. `null` when not reported.', 248 ) 249 usage: dict[str, Any] | None = Field( 250 default=None, 251 description="Provider-reported token and compute usage for the request. Structure varies by provider. `null` when usage data is unavailable.", 252 ) 253 width: int | None = Field( 254 default=None, 255 description="Width of the generated image in pixels. `null` when the provider does not report dimensions.", 256 )
The result returned by an AI image generation or editing operation. Contains the generated image (as inline data or a URL) along with dimension, size, and usage metadata.
aspect_ratio: str | None =
None
Aspect ratio of the generated image, e.g. "16:9" or "1:1". null when not reported by the provider.
height: int | None =
None
Height of the generated image in pixels. null when the provider does not report dimensions.
image_data: str | None =
None
The generated image encoded as a base64 string. Present when the provider returns inline image data. null when image_url is set instead.
image_size: str | None =
None
Resolution tier label for the image, e.g. "1K" or "2K". null when the provider does not include a tier label.
image_type: str | None =
None
MIME type of the generated image, e.g. "image/png" or "image/jpeg". null when the provider does not report a content type.
image_url: str | None =
None
Temporary URL pointing to the generated image hosted by the provider. Present when the provider returns a URL rather than inline data. null when image_data is set instead.
model: str =
PydanticUndefined
Identifier of the model that produced the image, e.g. "dall-e-3" or "imagen-3".
revised_prompt: str | None =
None
The prompt as rewritten by the provider before generation. Some providers (e.g. DALL-E 3) automatically expand or safety-check the original prompt. null when the provider does not revise prompts.
size: str | None =
None
Canonical size string as returned by the provider, e.g. "1024x1024". null when not reported.