archastro.platform.types.ai
1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. 2# This file is auto-generated by @archastro/sdk-generator. Do not edit. 3# Content hash: 6c3ad9b487cf 4 5from typing import Annotated, Any, Literal 6 7from pydantic import BaseModel, Field 8 9from .common import Refusal 10 11 12class AICompletionProvenance(BaseModel): 13 """ 14 One accepted provider completion. An empty record preserves an unknown identity. 15 """ 16 17 response_model: str | None = Field( 18 default=None, 19 description="Model identity reported by the provider response, not the requested model or usage key.", 20 ) 21 timing: dict[str, Any] | None = Field( 22 default=None, 23 description="Optional monotonic timing for this accepted completion and its retries. request_ms includes all attempts, backoff and local processing; provider_attempts_ms is the sum of provider request wall times, including transport and parsing; retry_backoff_ms is measured retry sleep. attempt_count includes the accepted call and retry_count counts earlier attempts. These overlapping measurements are not provider-internal inference time. Missing timing is unknown, not zero.", 24 ) 25 26 27class AIChatStreamDone(BaseModel): 28 """ 29 Terminal event marking the end of a streaming chat completion (SSE `done` event). 30 """ 31 32 completions: list[AICompletionProvenance] | None = Field( 33 default=None, 34 description="Ordered accepted completions; empty records retain unknown identities.", 35 ) 36 finish_reason: str | None = Field( 37 default=None, description="The overall finish reason for the completion." 38 ) 39 run_count: int | None = Field( 40 default=None, 41 description="Number of model runs executed, including continuations triggered by tool calls.", 42 ) 43 total_usage: dict[str, Any] | None = Field( 44 default=None, 45 description="Aggregate token usage across every run in the completion (including tool-call continuations), keyed by model ID.", 46 ) 47 usage: dict[str, Any] | None = Field( 48 default=None, description="Token usage for the final run, keyed by model ID." 49 ) 50 51 52class AIChatStreamError(BaseModel): 53 """ 54 Terminal error event for a streaming chat completion (SSE `error` event). 55 """ 56 57 message: str = Field( 58 ..., description="Human-readable description of the error that terminated the stream." 59 ) 60 retryable: bool | None = Field( 61 default=None, description="Whether the provider failure can be retried." 62 ) 63 status: int | None = Field(default=None, description="Upstream HTTP status, when reported.") 64 65 66class AIToolCall(BaseModel): 67 """ 68 A tool (function) call emitted by the assistant within an AI message. Mirrors the OpenAI tool-call object format. 69 """ 70 71 arguments: dict[str, Any] = Field( 72 ..., 73 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.", 74 ) 75 id: str = Field( 76 ..., 77 description="Unique identifier for this tool call, assigned by the model. Use this value as `id` when submitting the corresponding tool result.", 78 ) 79 name: str = Field( 80 ..., 81 description='Name of the tool or function the model wants to invoke, e.g. `"web_search"` or `"run_code"`.', 82 ) 83 thought_signature: str | None = Field( 84 default=None, 85 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.", 86 ) 87 88 89class AIToolResult(BaseModel): 90 """ 91 The result of executing a tool call, submitted back to the model as a tool-role message. Mirrors the OpenAI tool-result object format. 92 """ 93 94 content: str | None = Field( 95 default=None, 96 description="Plain-text output produced by the tool execution. `null` when the result is expressed entirely through `resolution`.", 97 ) 98 id: str = Field( 99 ..., 100 description="ID of the tool call this result satisfies. Must match the `id` from the corresponding `AIToolCall`.", 101 ) 102 name: str = Field( 103 ..., 104 description='Name of the tool or function that was executed, e.g. `"web_search"`. Must match the `name` from the corresponding `AIToolCall`.', 105 ) 106 resolution: Any | None = Field( 107 default=None, 108 description="Structured result data from the tool execution. Shape varies by tool. `null` when the result is expressed as plain text in `content`.", 109 ) 110 111 112class AIMessage(BaseModel): 113 """ 114 A single message in an AI conversation, following the OpenAI-compatible chat format. Used in both request inputs and completion responses. 115 """ 116 117 content: str | None = Field( 118 default=None, 119 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`.", 120 ) 121 content_parts: list[dict[str, Any]] | None = Field( 122 default=None, 123 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.', 124 ) 125 resume_token: str | None = Field( 126 default=None, 127 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.", 128 ) 129 role: str = Field( 130 ..., 131 description='The speaker role for this message. One of `"system"`, `"user"`, `"assistant"`, or `"tool"`.', 132 ) 133 structured_output: Any | None = Field( 134 default=None, 135 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.", 136 ) 137 tool_calls: list[AIToolCall] | None = Field( 138 default=None, 139 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.", 140 ) 141 tool_results: list[AIToolResult] | None = Field( 142 default=None, 143 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.", 144 ) 145 146 147class AIChatStreamMessageComplete(BaseModel): 148 """ 149 The fully assembled assistant message for one run of a streaming chat completion (SSE `message_complete` event). 150 """ 151 152 finish_reason: str | None = Field( 153 default=None, 154 description='Why the model stopped generating this message, e.g. `"stop"`, `"length"`, or `"tool_calls"`.', 155 ) 156 message: AIMessage = Field( 157 ..., 158 description="The complete assistant message for this run, assembled from the preceding deltas.", 159 ) 160 response_model: str | None = Field( 161 default=None, description="Provider-reported model identity for this accepted completion." 162 ) 163 usage: dict[str, Any] | None = Field( 164 default=None, 165 description="Token consumption for this run, keyed by model ID. `null` when usage data is unavailable.", 166 ) 167 168 169class AIChatStreamMessageDelta(BaseModel): 170 """ 171 Incremental assistant text emitted during a streaming chat completion (SSE `message_delta` event). 172 """ 173 174 delta: str = Field( 175 ..., 176 description="The chunk of assistant text produced since the previous `message_delta` event. Concatenate deltas in order to reconstruct the message.", 177 ) 178 179 180class AIChatStreamThinkingDelta(BaseModel): 181 """ 182 Incremental model reasoning emitted during a streaming chat completion (SSE `thinking_delta` event). 183 """ 184 185 delta: str = Field( 186 ..., 187 description="The chunk of model reasoning produced since the previous `thinking_delta` event.", 188 ) 189 190 191class AIChatStreamToolCallDelta(BaseModel): 192 """ 193 Incremental tool-call data emitted as the model assembles a tool invocation (SSE `tool_call_delta` event). 194 """ 195 196 delta: str | None = Field( 197 default=None, 198 description="A chunk of the tool call's serialized arguments. Concatenate deltas to reconstruct the arguments JSON.", 199 ) 200 id: str | None = Field( 201 default=None, 202 description="Identifier of the tool call this delta belongs to, once the model has assigned one.", 203 ) 204 name: str | None = Field(default=None, description="Name of the tool being called, once known.") 205 206 207class AIChatStreamToolResult(BaseModel): 208 """ 209 The result of a server-executed tool, streamed back into the run (SSE `tool_result` event). 210 """ 211 212 content: str | None = Field( 213 default=None, description="The tool's output, serialized as a string." 214 ) 215 id: str | None = Field(default=None, description="ID of the tool call this result satisfies.") 216 name: str | None = Field( 217 default=None, description="Name of the tool that produced this result." 218 ) 219 resolution: str | None = Field( 220 default=None, description='How the tool call resolved, e.g. `"ok"` or `"error"`.' 221 ) 222 223 224class AICompletionResult(BaseModel): 225 """ 226 The result of an AI chat completion request. Returned by chat completion endpoints after the model finishes generating. 227 """ 228 229 completions: list[AICompletionProvenance] | None = Field( 230 default=None, 231 description="Ordered accepted provider completions, including empty records for unknown identities.", 232 ) 233 finish_reason: str = Field( 234 ..., 235 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).', 236 ) 237 message: AIMessage = Field( 238 ..., description="The final assistant message produced by the completion." 239 ) 240 messages: list[AIMessage] = Field( 241 ..., 242 description="The complete message history for the conversation, including all user, assistant, and tool messages in order.", 243 ) 244 response_model: str | None = Field( 245 default=None, 246 description="Final accepted completion provider-reported identity; absent when unknown.", 247 ) 248 token_usage: dict[str, Any] | None = Field( 249 default=None, 250 description="Token consumption keyed by model ID. Each value has `input` (all prompt tokens, including cache reads and writes) and `output` counts. When reported, `fresh_input`, `cache_read`, and `cache_creation` are disjoint input buckets; missing cache counts remain unknown. `null` when usage data is unavailable.", 251 ) 252 253 254class AIEvaluationAnswerBoolean(BaseModel): 255 """ 256 Probability that the statement is true, in `[0, 1]`. 257 """ 258 259 id: str 260 probability: float 261 type: Literal["boolean"] = "boolean" 262 263 264class AIEvaluationAnswerChoice(BaseModel): 265 """ 266 Selected option plus the full probability distribution. 267 """ 268 269 choice: str 270 confidence: float | None = None 271 id: str 272 probabilities: dict[str, Any] 273 type: Literal["choice"] = "choice" 274 275 276class AIEvaluationAnswerScore(BaseModel): 277 """ 278 Probability-weighted position along the caller-defined levels. 279 """ 280 281 confidence: float | None = None 282 id: str 283 legend: dict[str, Any] 284 probabilities: dict[str, Any] 285 score: float 286 type: Literal["score"] = "score" 287 288 289# One typed evaluation answer. `type` selects boolean, choice, score, or refusal. 290# `id` matches the question id. 291AIEvaluationAnswer = Annotated[ 292 AIEvaluationAnswerBoolean | AIEvaluationAnswerChoice | AIEvaluationAnswerScore | Refusal, 293 Field(discriminator="type"), 294] 295 296 297class AIEvaluationUsage(BaseModel): 298 """ 299 Token counts for one evaluation request. 300 """ 301 302 input_tokens: int | None = Field( 303 default=None, 304 description="Provider-reported input tokens. `null` when the provider omitted the count.", 305 ) 306 output_tokens: int | None = Field( 307 default=None, 308 description="Provider-reported output tokens. `null` when the provider omitted the count.", 309 ) 310 311 312class AIEvaluationResult(BaseModel): 313 """ 314 Result of an evaluation request: typed answers, the model that ran, and 315 token usage. 316 """ 317 318 answers: list[AIEvaluationAnswer] = Field( 319 ..., description="Typed boolean, choice, score, or refusal answers with the question `id`." 320 ) 321 model: str = Field(..., description="Model identifier that produced the answers.") 322 session_id: str | None = Field( 323 default=None, 324 description="UUID grouping this evaluation's usage record. Generated when omitted on the request.", 325 ) 326 usage: AIEvaluationUsage | None = Field( 327 default=None, 328 description="Token usage for this request. `null` when usage data is unavailable.", 329 ) 330 331 332class AIImageResult(BaseModel): 333 """ 334 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. 335 """ 336 337 aspect_ratio: str | None = Field( 338 default=None, 339 description='Aspect ratio of the generated image, e.g. `"16:9"` or `"1:1"`. `null` when not reported by the provider.', 340 ) 341 height: int | None = Field( 342 default=None, 343 description="Height of the generated image in pixels. `null` when the provider does not report dimensions.", 344 ) 345 image_data: str | None = Field( 346 default=None, 347 description="The generated image encoded as a base64 string. Present when the provider returns inline image data. `null` when `image_url` is set instead.", 348 ) 349 image_size: str | None = Field( 350 default=None, 351 description='Resolution tier label for the image, e.g. `"1K"` or `"2K"`. `null` when the provider does not include a tier label.', 352 ) 353 image_type: str | None = Field( 354 default=None, 355 description='MIME type of the generated image, e.g. `"image/png"` or `"image/jpeg"`. `null` when the provider does not report a content type.', 356 ) 357 image_url: str | None = Field( 358 default=None, 359 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.", 360 ) 361 model: str = Field( 362 ..., 363 description='Identifier of the model that produced the image, e.g. `"dall-e-3"` or `"imagen-3"`.', 364 ) 365 revised_prompt: str | None = Field( 366 default=None, 367 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.", 368 ) 369 session_id: str | None = Field( 370 default=None, 371 description="UUID grouping this image request's provider attempts for usage and billing.", 372 ) 373 size: str | None = Field( 374 default=None, 375 description='Canonical size string as returned by the provider, e.g. `"1024x1024"`. `null` when not reported.', 376 ) 377 usage: dict[str, Any] | None = Field( 378 default=None, 379 description="Provider-reported token and compute usage for the request. Structure varies by provider. `null` when usage data is unavailable.", 380 ) 381 usage_attempt_count: int | None = Field( 382 default=None, 383 description="Number of provider responses contributing usage records to this request, including image-generation retries.", 384 ) 385 width: int | None = Field( 386 default=None, 387 description="Width of the generated image in pixels. `null` when the provider does not report dimensions.", 388 )
class
AICompletionProvenance(pydantic.main.BaseModel):
13class AICompletionProvenance(BaseModel): 14 """ 15 One accepted provider completion. An empty record preserves an unknown identity. 16 """ 17 18 response_model: str | None = Field( 19 default=None, 20 description="Model identity reported by the provider response, not the requested model or usage key.", 21 ) 22 timing: dict[str, Any] | None = Field( 23 default=None, 24 description="Optional monotonic timing for this accepted completion and its retries. request_ms includes all attempts, backoff and local processing; provider_attempts_ms is the sum of provider request wall times, including transport and parsing; retry_backoff_ms is measured retry sleep. attempt_count includes the accepted call and retry_count counts earlier attempts. These overlapping measurements are not provider-internal inference time. Missing timing is unknown, not zero.", 25 )
One accepted provider completion. An empty record preserves an unknown identity.
response_model: str | None =
None
Model identity reported by the provider response, not the requested model or usage key.
timing: dict[str, typing.Any] | None =
None
Optional monotonic timing for this accepted completion and its retries. request_ms includes all attempts, backoff and local processing; provider_attempts_ms is the sum of provider request wall times, including transport and parsing; retry_backoff_ms is measured retry sleep. attempt_count includes the accepted call and retry_count counts earlier attempts. These overlapping measurements are not provider-internal inference time. Missing timing is unknown, not zero.
class
AIChatStreamDone(pydantic.main.BaseModel):
28class AIChatStreamDone(BaseModel): 29 """ 30 Terminal event marking the end of a streaming chat completion (SSE `done` event). 31 """ 32 33 completions: list[AICompletionProvenance] | None = Field( 34 default=None, 35 description="Ordered accepted completions; empty records retain unknown identities.", 36 ) 37 finish_reason: str | None = Field( 38 default=None, description="The overall finish reason for the completion." 39 ) 40 run_count: int | None = Field( 41 default=None, 42 description="Number of model runs executed, including continuations triggered by tool calls.", 43 ) 44 total_usage: dict[str, Any] | None = Field( 45 default=None, 46 description="Aggregate token usage across every run in the completion (including tool-call continuations), keyed by model ID.", 47 ) 48 usage: dict[str, Any] | None = Field( 49 default=None, description="Token usage for the final run, keyed by model ID." 50 )
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):
53class AIChatStreamError(BaseModel): 54 """ 55 Terminal error event for a streaming chat completion (SSE `error` event). 56 """ 57 58 message: str = Field( 59 ..., description="Human-readable description of the error that terminated the stream." 60 ) 61 retryable: bool | None = Field( 62 default=None, description="Whether the provider failure can be retried." 63 ) 64 status: int | None = Field(default=None, description="Upstream HTTP status, when reported.")
Terminal error event for a streaming chat completion (SSE error event).
class
AIToolCall(pydantic.main.BaseModel):
67class AIToolCall(BaseModel): 68 """ 69 A tool (function) call emitted by the assistant within an AI message. Mirrors the OpenAI tool-call object format. 70 """ 71 72 arguments: dict[str, Any] = Field( 73 ..., 74 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.", 75 ) 76 id: str = Field( 77 ..., 78 description="Unique identifier for this tool call, assigned by the model. Use this value as `id` when submitting the corresponding tool result.", 79 ) 80 name: str = Field( 81 ..., 82 description='Name of the tool or function the model wants to invoke, e.g. `"web_search"` or `"run_code"`.', 83 ) 84 thought_signature: str | None = Field( 85 default=None, 86 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.", 87 )
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):
90class AIToolResult(BaseModel): 91 """ 92 The result of executing a tool call, submitted back to the model as a tool-role message. Mirrors the OpenAI tool-result object format. 93 """ 94 95 content: str | None = Field( 96 default=None, 97 description="Plain-text output produced by the tool execution. `null` when the result is expressed entirely through `resolution`.", 98 ) 99 id: str = Field( 100 ..., 101 description="ID of the tool call this result satisfies. Must match the `id` from the corresponding `AIToolCall`.", 102 ) 103 name: str = Field( 104 ..., 105 description='Name of the tool or function that was executed, e.g. `"web_search"`. Must match the `name` from the corresponding `AIToolCall`.', 106 ) 107 resolution: Any | None = Field( 108 default=None, 109 description="Structured result data from the tool execution. Shape varies by tool. `null` when the result is expressed as plain text in `content`.", 110 )
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):
113class AIMessage(BaseModel): 114 """ 115 A single message in an AI conversation, following the OpenAI-compatible chat format. Used in both request inputs and completion responses. 116 """ 117 118 content: str | None = Field( 119 default=None, 120 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`.", 121 ) 122 content_parts: list[dict[str, Any]] | None = Field( 123 default=None, 124 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.', 125 ) 126 resume_token: str | None = Field( 127 default=None, 128 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.", 129 ) 130 role: str = Field( 131 ..., 132 description='The speaker role for this message. One of `"system"`, `"user"`, `"assistant"`, or `"tool"`.', 133 ) 134 structured_output: Any | None = Field( 135 default=None, 136 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.", 137 ) 138 tool_calls: list[AIToolCall] | None = Field( 139 default=None, 140 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.", 141 ) 142 tool_results: list[AIToolResult] | None = Field( 143 default=None, 144 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.", 145 )
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):
148class AIChatStreamMessageComplete(BaseModel): 149 """ 150 The fully assembled assistant message for one run of a streaming chat completion (SSE `message_complete` event). 151 """ 152 153 finish_reason: str | None = Field( 154 default=None, 155 description='Why the model stopped generating this message, e.g. `"stop"`, `"length"`, or `"tool_calls"`.', 156 ) 157 message: AIMessage = Field( 158 ..., 159 description="The complete assistant message for this run, assembled from the preceding deltas.", 160 ) 161 response_model: str | None = Field( 162 default=None, description="Provider-reported model identity for this accepted completion." 163 ) 164 usage: dict[str, Any] | None = Field( 165 default=None, 166 description="Token consumption for this run, keyed by model ID. `null` when usage data is unavailable.", 167 )
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):
170class AIChatStreamMessageDelta(BaseModel): 171 """ 172 Incremental assistant text emitted during a streaming chat completion (SSE `message_delta` event). 173 """ 174 175 delta: str = Field( 176 ..., 177 description="The chunk of assistant text produced since the previous `message_delta` event. Concatenate deltas in order to reconstruct the message.", 178 )
Incremental assistant text emitted during a streaming chat completion (SSE message_delta event).
class
AIChatStreamThinkingDelta(pydantic.main.BaseModel):
181class AIChatStreamThinkingDelta(BaseModel): 182 """ 183 Incremental model reasoning emitted during a streaming chat completion (SSE `thinking_delta` event). 184 """ 185 186 delta: str = Field( 187 ..., 188 description="The chunk of model reasoning produced since the previous `thinking_delta` event.", 189 )
Incremental model reasoning emitted during a streaming chat completion (SSE thinking_delta event).
class
AIChatStreamToolCallDelta(pydantic.main.BaseModel):
192class AIChatStreamToolCallDelta(BaseModel): 193 """ 194 Incremental tool-call data emitted as the model assembles a tool invocation (SSE `tool_call_delta` event). 195 """ 196 197 delta: str | None = Field( 198 default=None, 199 description="A chunk of the tool call's serialized arguments. Concatenate deltas to reconstruct the arguments JSON.", 200 ) 201 id: str | None = Field( 202 default=None, 203 description="Identifier of the tool call this delta belongs to, once the model has assigned one.", 204 ) 205 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):
208class AIChatStreamToolResult(BaseModel): 209 """ 210 The result of a server-executed tool, streamed back into the run (SSE `tool_result` event). 211 """ 212 213 content: str | None = Field( 214 default=None, description="The tool's output, serialized as a string." 215 ) 216 id: str | None = Field(default=None, description="ID of the tool call this result satisfies.") 217 name: str | None = Field( 218 default=None, description="Name of the tool that produced this result." 219 ) 220 resolution: str | None = Field( 221 default=None, description='How the tool call resolved, e.g. `"ok"` or `"error"`.' 222 )
The result of a server-executed tool, streamed back into the run (SSE tool_result event).
class
AICompletionResult(pydantic.main.BaseModel):
225class AICompletionResult(BaseModel): 226 """ 227 The result of an AI chat completion request. Returned by chat completion endpoints after the model finishes generating. 228 """ 229 230 completions: list[AICompletionProvenance] | None = Field( 231 default=None, 232 description="Ordered accepted provider completions, including empty records for unknown identities.", 233 ) 234 finish_reason: str = Field( 235 ..., 236 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).', 237 ) 238 message: AIMessage = Field( 239 ..., description="The final assistant message produced by the completion." 240 ) 241 messages: list[AIMessage] = Field( 242 ..., 243 description="The complete message history for the conversation, including all user, assistant, and tool messages in order.", 244 ) 245 response_model: str | None = Field( 246 default=None, 247 description="Final accepted completion provider-reported identity; absent when unknown.", 248 ) 249 token_usage: dict[str, Any] | None = Field( 250 default=None, 251 description="Token consumption keyed by model ID. Each value has `input` (all prompt tokens, including cache reads and writes) and `output` counts. When reported, `fresh_input`, `cache_read`, and `cache_creation` are disjoint input buckets; missing cache counts remain unknown. `null` when usage data is unavailable.", 252 )
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).
The complete message history for the conversation, including all user, assistant, and tool messages in order.
response_model: str | None =
None
Final accepted completion provider-reported identity; absent when unknown.
token_usage: dict[str, typing.Any] | None =
None
Token consumption keyed by model ID. Each value has input (all prompt tokens, including cache reads and writes) and output counts. When reported, fresh_input, cache_read, and cache_creation are disjoint input buckets; missing cache counts remain unknown. null when usage data is unavailable.
class
AIEvaluationAnswerBoolean(pydantic.main.BaseModel):
255class AIEvaluationAnswerBoolean(BaseModel): 256 """ 257 Probability that the statement is true, in `[0, 1]`. 258 """ 259 260 id: str 261 probability: float 262 type: Literal["boolean"] = "boolean"
Probability that the statement is true, in [0, 1].
class
AIEvaluationAnswerChoice(pydantic.main.BaseModel):
265class AIEvaluationAnswerChoice(BaseModel): 266 """ 267 Selected option plus the full probability distribution. 268 """ 269 270 choice: str 271 confidence: float | None = None 272 id: str 273 probabilities: dict[str, Any] 274 type: Literal["choice"] = "choice"
Selected option plus the full probability distribution.
class
AIEvaluationAnswerScore(pydantic.main.BaseModel):
277class AIEvaluationAnswerScore(BaseModel): 278 """ 279 Probability-weighted position along the caller-defined levels. 280 """ 281 282 confidence: float | None = None 283 id: str 284 legend: dict[str, Any] 285 probabilities: dict[str, Any] 286 score: float 287 type: Literal["score"] = "score"
Probability-weighted position along the caller-defined levels.
AIEvaluationAnswer =
typing.Annotated[AIEvaluationAnswerBoolean | AIEvaluationAnswerChoice | AIEvaluationAnswerScore | archastro.platform.types.common.Refusal, FieldInfo(annotation=NoneType, required=True, discriminator='type')]
class
AIEvaluationUsage(pydantic.main.BaseModel):
298class AIEvaluationUsage(BaseModel): 299 """ 300 Token counts for one evaluation request. 301 """ 302 303 input_tokens: int | None = Field( 304 default=None, 305 description="Provider-reported input tokens. `null` when the provider omitted the count.", 306 ) 307 output_tokens: int | None = Field( 308 default=None, 309 description="Provider-reported output tokens. `null` when the provider omitted the count.", 310 )
Token counts for one evaluation request.
class
AIEvaluationResult(pydantic.main.BaseModel):
313class AIEvaluationResult(BaseModel): 314 """ 315 Result of an evaluation request: typed answers, the model that ran, and 316 token usage. 317 """ 318 319 answers: list[AIEvaluationAnswer] = Field( 320 ..., description="Typed boolean, choice, score, or refusal answers with the question `id`." 321 ) 322 model: str = Field(..., description="Model identifier that produced the answers.") 323 session_id: str | None = Field( 324 default=None, 325 description="UUID grouping this evaluation's usage record. Generated when omitted on the request.", 326 ) 327 usage: AIEvaluationUsage | None = Field( 328 default=None, 329 description="Token usage for this request. `null` when usage data is unavailable.", 330 )
Result of an evaluation request: typed answers, the model that ran, and token usage.
answers: list[typing.Annotated[AIEvaluationAnswerBoolean | AIEvaluationAnswerChoice | AIEvaluationAnswerScore | archastro.platform.types.common.Refusal, FieldInfo(annotation=NoneType, required=True, discriminator='type')]] =
PydanticUndefined
Typed boolean, choice, score, or refusal answers with the question id.
session_id: str | None =
None
UUID grouping this evaluation's usage record. Generated when omitted on the request.
class
AIImageResult(pydantic.main.BaseModel):
333class AIImageResult(BaseModel): 334 """ 335 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. 336 """ 337 338 aspect_ratio: str | None = Field( 339 default=None, 340 description='Aspect ratio of the generated image, e.g. `"16:9"` or `"1:1"`. `null` when not reported by the provider.', 341 ) 342 height: int | None = Field( 343 default=None, 344 description="Height of the generated image in pixels. `null` when the provider does not report dimensions.", 345 ) 346 image_data: str | None = Field( 347 default=None, 348 description="The generated image encoded as a base64 string. Present when the provider returns inline image data. `null` when `image_url` is set instead.", 349 ) 350 image_size: str | None = Field( 351 default=None, 352 description='Resolution tier label for the image, e.g. `"1K"` or `"2K"`. `null` when the provider does not include a tier label.', 353 ) 354 image_type: str | None = Field( 355 default=None, 356 description='MIME type of the generated image, e.g. `"image/png"` or `"image/jpeg"`. `null` when the provider does not report a content type.', 357 ) 358 image_url: str | None = Field( 359 default=None, 360 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.", 361 ) 362 model: str = Field( 363 ..., 364 description='Identifier of the model that produced the image, e.g. `"dall-e-3"` or `"imagen-3"`.', 365 ) 366 revised_prompt: str | None = Field( 367 default=None, 368 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.", 369 ) 370 session_id: str | None = Field( 371 default=None, 372 description="UUID grouping this image request's provider attempts for usage and billing.", 373 ) 374 size: str | None = Field( 375 default=None, 376 description='Canonical size string as returned by the provider, e.g. `"1024x1024"`. `null` when not reported.', 377 ) 378 usage: dict[str, Any] | None = Field( 379 default=None, 380 description="Provider-reported token and compute usage for the request. Structure varies by provider. `null` when usage data is unavailable.", 381 ) 382 usage_attempt_count: int | None = Field( 383 default=None, 384 description="Number of provider responses contributing usage records to this request, including image-generation retries.", 385 ) 386 width: int | None = Field( 387 default=None, 388 description="Width of the generated image in pixels. `null` when the provider does not report dimensions.", 389 )
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.
session_id: str | None =
None
UUID grouping this image request's provider attempts for usage and billing.
size: str | None =
None
Canonical size string as returned by the provider, e.g. "1024x1024". null when not reported.
usage: dict[str, typing.Any] | None =
None
Provider-reported token and compute usage for the request. Structure varies by provider. null when usage data is unavailable.