archastro.platform.v1.resources.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: a1da119e9408
   4
   5from __future__ import annotations
   6
   7from collections.abc import AsyncIterator, Iterator
   8from typing import (
   9    Any,
  10    Literal,
  11    Required,
  12    TypedDict,
  13)
  14
  15from pydantic import BaseModel, Field
  16
  17from ...runtime.http_client import HttpClient, SyncHttpClient
  18from ...types.ai import (
  19    AIChatStreamDone,
  20    AIChatStreamError,
  21    AIChatStreamMessageComplete,
  22    AIChatStreamMessageDelta,
  23    AIChatStreamThinkingDelta,
  24    AIChatStreamToolCallDelta,
  25    AIChatStreamToolResult,
  26    AICompletionResult,
  27    AIEvaluationResult,
  28    AIImageResult,
  29)
  30
  31
  32class StreamCreateInputMessagesItemToolCallsItem(TypedDict, total=False):
  33    arguments: Required[dict[str, Any]]
  34    "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."
  35    id: Required[str]
  36    "Unique identifier for this tool call, assigned by the model. Use this value as `id` when submitting the corresponding tool result."
  37    name: Required[str]
  38    'Name of the tool or function the model wants to invoke, e.g. `"web_search"` or `"run_code"`.'
  39    thought_signature: str | None
  40    "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."
  41
  42
  43class StreamCreateInputMessagesItemToolResultsItem(TypedDict, total=False):
  44    content: str | None
  45    "Plain-text output produced by the tool execution. `null` when the result is expressed entirely through `resolution`."
  46    id: Required[str]
  47    "ID of the tool call this result satisfies. Must match the `id` from the corresponding `AIToolCall`."
  48    name: Required[str]
  49    'Name of the tool or function that was executed, e.g. `"web_search"`. Must match the `name` from the corresponding `AIToolCall`.'
  50    resolution: Any | None
  51    "Structured result data from the tool execution. Shape varies by tool. `null` when the result is expressed as plain text in `content`."
  52
  53
  54class StreamCreateInputMessagesItem(TypedDict, total=False):
  55    content: str | None
  56    "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`."
  57    content_parts: list[dict[str, Any]] | None
  58    '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.'
  59    resume_token: str | None
  60    "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."
  61    role: Required[str]
  62    'The speaker role for this message. One of `"system"`, `"user"`, `"assistant"`, or `"tool"`.'
  63    structured_output: Any | None
  64    "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."
  65    tool_calls: list[StreamCreateInputMessagesItemToolCallsItem] | None
  66    "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."
  67    tool_results: list[StreamCreateInputMessagesItemToolResultsItem] | None
  68    "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."
  69
  70
  71class StreamCreateInputOptsToolsItemFunction(TypedDict, total=False):
  72    description: str | None
  73    "Human-readable description of what the function does. The model uses this to decide when to call the function. `null` if not provided."
  74    name: Required[str]
  75    'Unique name of the function that the model can invoke, e.g. `"get_weather"`.'
  76    parameters: Required[dict[str, Any]]
  77    'JSON Schema object describing the function\'s accepted parameters. Must be a valid JSON Schema of type `"object"`.'
  78
  79
  80class StreamCreateInputOptsToolsItem(TypedDict):
  81    function: StreamCreateInputOptsToolsItemFunction
  82    "Callable function this tool exposes, including its name, description, and parameter schema."
  83    type: str
  84    'The tool type. Currently always `"function"`.'
  85
  86
  87class StreamCreateInputOpts(TypedDict, total=False):
  88    max_tokens: int | None
  89    "Maximum number of tokens the model may generate. Omit for the model default."
  90    model: Required[str]
  91    'Model identifier, e.g. `"gpt-4o"` or `"claude-3-7-sonnet-latest"`.'
  92    server_tools: list[dict[str, Any]] | None
  93    'Server-managed tool declarations executed before the response. Each entry must include a `type` key; currently only `"search"` is supported.'
  94    temperature: float | None
  95    "Sampling temperature between `0.0` and `2.0`. Higher values produce more random output. Omit for the model default."
  96    tool_choice: str | None
  97    'Controls tool selection. One of `"auto"`, `"required"`, or `"none"`. Omit to let the model decide.'
  98    tools: list[StreamCreateInputOptsToolsItem] | None
  99    "OpenAI-compatible tool definitions available to the model. Omit when not using function calling."
 100
 101
 102class StreamCreateInput(TypedDict, total=False):
 103    "Stream a chat completion"
 104
 105    attribution: dict[str, Any] | None
 106    "Optional caller tags recorded on the LLM-call accounting row. Allowed keys: `task_id` (max 64 chars), `work_id` (max 64), `agent_kind` (one of `worker`, `one_off`, `subagent`, `overseer`, `task_reviewer`, `interactive`, `daemon_job`), `agent_id` (max 64), `client` (max 32). Anything else is a 400."
 107    context: dict[str, Any] | None
 108    "Key-value map used to resolve template variables in message content. Omit if messages contain no templates."
 109    messages: Required[list[StreamCreateInputMessagesItem]]
 110    "Ordered list of conversation messages to send to the model."
 111    opts: Required[StreamCreateInputOpts]
 112    "Model and sampling configuration for this request."
 113    session_id: str | None
 114    "Optional UUID grouping this and other completions under one session in the Developers dashboard. Pass the same value across requests to link them; omit to auto-generate a per-request session."
 115
 116
 117class CompletionCreateInputMessagesItemToolCallsItem(TypedDict, total=False):
 118    arguments: Required[dict[str, Any]]
 119    "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."
 120    id: Required[str]
 121    "Unique identifier for this tool call, assigned by the model. Use this value as `id` when submitting the corresponding tool result."
 122    name: Required[str]
 123    'Name of the tool or function the model wants to invoke, e.g. `"web_search"` or `"run_code"`.'
 124    thought_signature: str | None
 125    "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."
 126
 127
 128class CompletionCreateInputMessagesItemToolResultsItem(TypedDict, total=False):
 129    content: str | None
 130    "Plain-text output produced by the tool execution. `null` when the result is expressed entirely through `resolution`."
 131    id: Required[str]
 132    "ID of the tool call this result satisfies. Must match the `id` from the corresponding `AIToolCall`."
 133    name: Required[str]
 134    'Name of the tool or function that was executed, e.g. `"web_search"`. Must match the `name` from the corresponding `AIToolCall`.'
 135    resolution: Any | None
 136    "Structured result data from the tool execution. Shape varies by tool. `null` when the result is expressed as plain text in `content`."
 137
 138
 139class CompletionCreateInputMessagesItem(TypedDict, total=False):
 140    content: str | None
 141    "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`."
 142    content_parts: list[dict[str, Any]] | None
 143    '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.'
 144    resume_token: str | None
 145    "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."
 146    role: Required[str]
 147    'The speaker role for this message. One of `"system"`, `"user"`, `"assistant"`, or `"tool"`.'
 148    structured_output: Any | None
 149    "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."
 150    tool_calls: list[CompletionCreateInputMessagesItemToolCallsItem] | None
 151    "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."
 152    tool_results: list[CompletionCreateInputMessagesItemToolResultsItem] | None
 153    "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."
 154
 155
 156class CompletionCreateInputOptsToolsItemFunction(TypedDict, total=False):
 157    description: str | None
 158    "Human-readable description of what the function does. The model uses this to decide when to call the function. `null` if not provided."
 159    name: Required[str]
 160    'Unique name of the function that the model can invoke, e.g. `"get_weather"`.'
 161    parameters: Required[dict[str, Any]]
 162    'JSON Schema object describing the function\'s accepted parameters. Must be a valid JSON Schema of type `"object"`.'
 163
 164
 165class CompletionCreateInputOptsToolsItem(TypedDict):
 166    function: CompletionCreateInputOptsToolsItemFunction
 167    "Callable function this tool exposes, including its name, description, and parameter schema."
 168    type: str
 169    'The tool type. Currently always `"function"`.'
 170
 171
 172class CompletionCreateInputOpts(TypedDict, total=False):
 173    max_tokens: int | None
 174    "Maximum number of tokens the model may generate in the completion. Omit to use the model's default limit."
 175    model: Required[str]
 176    'Model identifier to use for the completion, e.g. `"gpt-4o"` or `"claude-3-7-sonnet-latest"`.'
 177    server_tools: list[dict[str, Any]] | None
 178    'Server-managed tool declarations executed before the response is returned. Each entry must include a `type` key; currently only `"search"` is supported.'
 179    structured_output: dict[str, Any] | None
 180    "Native structured-output configuration. Include a `schema` JSON Schema object and optional `name` and `strict` fields."
 181    temperature: float | None
 182    "Sampling temperature between `0.0` and `2.0`. Higher values produce more random output. Omit to use the model's default."
 183    tool_choice: str | None
 184    'Controls how the model selects tools. One of `"auto"`, `"required"`, or `"none"`. Omit to let the model decide.'
 185    tools: list[CompletionCreateInputOptsToolsItem] | None
 186    "OpenAI-compatible tool definitions available to the model. Omit when not using function calling."
 187
 188
 189class CompletionCreateInput(TypedDict, total=False):
 190    "Create a chat completion"
 191
 192    attribution: dict[str, Any] | None
 193    "Optional caller tags recorded on the LLM-call accounting row. Allowed keys: `task_id` (max 64 chars), `work_id` (max 64), `agent_kind` (one of `worker`, `one_off`, `subagent`, `overseer`, `task_reviewer`, `interactive`, `daemon_job`), `agent_id` (max 64), `client` (max 32). Anything else is a 400."
 194    context: dict[str, Any] | None
 195    "Key-value map used to resolve template variables in message content. Omit if messages contain no templates."
 196    messages: Required[list[CompletionCreateInputMessagesItem]]
 197    "Ordered list of conversation messages to send to the model."
 198    opts: Required[CompletionCreateInputOpts]
 199    "Model and sampling configuration for this request."
 200    session_id: str | None
 201    "Optional UUID grouping this and other completions under one session in the Developers dashboard. Pass the same value across requests to link them; omit to auto-generate a per-request session."
 202
 203
 204class EmbeddingSimilarityComparisonInput(TypedDict):
 205    "Compare the embedding similarity of two texts"
 206
 207    text_a: str
 208    "First text to embed and compare."
 209    text_b: str
 210    "Second text to embed and compare."
 211
 212
 213class EvaluationEvaluationsInputImagesItem(TypedDict, total=False):
 214    image_data: str | None
 215    "Base64 image bytes; requires image_type."
 216    image_type: str | None
 217    "Image MIME type, such as image/png."
 218    image_url: str | None
 219    "Image URL; mutually exclusive with image_data."
 220    type: Required[Literal["image"]]
 221
 222
 223class EvaluationEvaluationsInput(TypedDict, total=False):
 224    "Create an evaluation"
 225
 226    images: list[EvaluationEvaluationsInputImagesItem] | None
 227    "Optional image content parts. Omitted or empty means no images. Requires model image support."
 228    model: str | None
 229    "Evaluation model identifier. Omit to use the platform default."
 230    questions: Required[list[dict[str, Any] | dict[str, Any] | dict[str, Any]]]
 231    "Nonempty list of boolean, choice, or score questions. Each question must include `id`, `type`, and `instructions`."
 232    session_id: str | None
 233    "Optional UUID grouping this evaluation under one session in the Developers dashboard. Generated when omitted."
 234    state: Required[Any]
 235    "Shared content the model judges. A string, JSON object, or JSON array. Every question in the request sees this same state."
 236
 237
 238class ImageEditsInputImagesItem(TypedDict):
 239    image_data: str
 240    "The raw image content encoded as a base64 string (standard encoding, no line breaks)."
 241    image_type: str
 242    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. Must match the actual encoding of `image_data`.'
 243
 244
 245class ImageEditsInput(TypedDict, total=False):
 246    "Edit an image with a text prompt"
 247
 248    aspect_ratio: str | None
 249    'Desired aspect ratio of the output, e.g. `"1:1"` or `"16:9"`. Not supported by all models; omit to use the model\'s default.'
 250    background: str | None
 251    "Background treatment for the output. Accepted values and behavior are model-dependent."
 252    height: int | None
 253    "Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models."
 254    image_size: str | None
 255    'Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.'
 256    images: Required[list[ImageEditsInputImagesItem]]
 257    "One or more source images to edit. Each image must be supplied as a base64-encoded object."
 258    model: str | None
 259    "Model identifier to use for editing. Omit to use the platform default image model."
 260    output_format: str | None
 261    'Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model\'s native format.'
 262    prompt: Required[str]
 263    "Natural-language description of the edit to apply to the source image(s)."
 264    quality: str | None
 265    "Quality preset for the output image. Accepted values and behavior are model-dependent."
 266    session_id: str | None
 267    "Optional session UUID for grouping provider attempts in usage records. Generated when omitted."
 268    size: str | None
 269    'Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model\'s default.'
 270    style: str | None
 271    "Style preset applied to the edit. Accepted values and behavior are model-dependent."
 272    width: int | None
 273    "Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models."
 274
 275
 276class ImageGenerationsInput(TypedDict, total=False):
 277    "Generate an image from a text prompt"
 278
 279    aspect_ratio: str | None
 280    'Desired aspect ratio of the output, e.g. `"1:1"` or `"16:9"`. Not supported by all models; omit to use the model\'s default.'
 281    background: str | None
 282    "Background treatment for the output. Accepted values and behavior are model-dependent."
 283    height: int | None
 284    "Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models."
 285    image_size: str | None
 286    'Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.'
 287    model: str | None
 288    "Model identifier to use for generation. Omit to use the platform default image model."
 289    n: int | None
 290    "Number of images to generate. Defaults to `1`. Values greater than `1` are only supported by models that allow batch generation."
 291    output_format: str | None
 292    'Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model\'s native format.'
 293    prompt: Required[str]
 294    "Natural-language description of the image to generate."
 295    quality: str | None
 296    "Quality preset for the output image. Accepted values and behavior are model-dependent."
 297    session_id: str | None
 298    "Optional session UUID for grouping provider attempts in usage records. Generated when omitted."
 299    size: str | None
 300    'Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model\'s default.'
 301    style: str | None
 302    "Style preset applied to the generated image. Accepted values and behavior are model-dependent."
 303    width: int | None
 304    "Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models."
 305
 306
 307class AiSessionTokenInput(TypedDict, total=False):
 308    "Mint a principal-bound billing session token"
 309
 310    entitlement: Literal["llm_calls", "run_automation"] | None
 311    restrictions: dict[str, Any] | None
 312    ttl: int | None
 313    user_id: Required[str]
 314
 315
 316class ChatModelsResponseDataItem(BaseModel):
 317    capabilities: list[Literal["image", "search", "temperature", "thinking"]] = Field(
 318        ...,
 319        description='Machine-readable model capabilities. `"image"` marks image-input chat, `"search"` marks built-in web search, `"temperature"` marks models that accept the temperature generation parameter, and `"thinking"` marks models with configurable reasoning. Empty when the catalog entry declares no special capabilities.',
 320    )
 321    context_window: int | None = Field(
 322        default=None,
 323        description="Maximum context-window size in tokens this model accepts, when the platform publishes it. Use it to size prompt/history against the real window rather than a hardcoded default. `null` for entries whose window the platform does not report (e.g. legacy or mock model listings); clients should apply a conservative fallback in that case.",
 324    )
 325    default: bool = Field(
 326        ...,
 327        description="`true` for the model the platform selects when an agent has no `default_model` configured, or for the system-wide fallback in image-generation contexts. Exactly one entry in any given model list carries this flag.",
 328    )
 329    id: str = Field(
 330        ...,
 331        description='Provider-assigned model identifier used when specifying a model on API requests, e.g. `"claude-sonnet-4-6"` or `"gemini-2.5-flash"`.',
 332    )
 333    input_media_formats: list[str] = Field(
 334        ...,
 335        description='MIME types accepted in chat `content_parts` image/file inputs for this model. For image-capable chat models this includes values such as `"image/png"`. Empty for text-only models.',
 336    )
 337    name: str = Field(
 338        ...,
 339        description='Human-readable display label for this model, e.g. `"Claude Sonnet 4.6"` or `"Gemini 3.5 Flash (thinking)"`. Render this value directly in pickers rather than attempting to parse or transform `id`. Falls back to the `id` string when the catalog entry does not declare an explicit name.',
 340    )
 341    output_media_formats: list[str] = Field(
 342        ...,
 343        description="MIME types this model can emit as media in chat responses. Empty for text-output models, including image-understanding models that only return text.",
 344    )
 345
 346
 347class ChatModelsResponse(BaseModel):
 348    """
 349    Successful response
 350    """
 351
 352    data: list[ChatModelsResponseDataItem] = Field(
 353        ..., description="Array of available model objects. At least one entry is always present."
 354    )
 355
 356
 357class EmbeddingSimilarityComparisonResponse(BaseModel):
 358    """
 359    Successful response
 360    """
 361
 362    model: str = Field(
 363        ..., description="Configured default embedding model key used for both texts."
 364    )
 365    similarity_score: float = Field(
 366        ...,
 367        description="Cosine similarity from `-1.0` to `1.0`, computed as `1 - cosine_distance`.",
 368    )
 369
 370
 371class EvaluationModelsResponseDataItem(BaseModel):
 372    capabilities: list[Literal["image", "search", "temperature", "thinking"]] = Field(
 373        ...,
 374        description='Machine-readable model capabilities. `"image"` marks image-input chat, `"search"` marks built-in web search, `"temperature"` marks models that accept the temperature generation parameter, and `"thinking"` marks models with configurable reasoning. Empty when the catalog entry declares no special capabilities.',
 375    )
 376    context_window: int | None = Field(
 377        default=None,
 378        description="Maximum context-window size in tokens this model accepts, when the platform publishes it. Use it to size prompt/history against the real window rather than a hardcoded default. `null` for entries whose window the platform does not report (e.g. legacy or mock model listings); clients should apply a conservative fallback in that case.",
 379    )
 380    default: bool = Field(
 381        ...,
 382        description="`true` for the model the platform selects when an agent has no `default_model` configured, or for the system-wide fallback in image-generation contexts. Exactly one entry in any given model list carries this flag.",
 383    )
 384    id: str = Field(
 385        ...,
 386        description='Provider-assigned model identifier used when specifying a model on API requests, e.g. `"claude-sonnet-4-6"` or `"gemini-2.5-flash"`.',
 387    )
 388    input_media_formats: list[str] = Field(
 389        ...,
 390        description='MIME types accepted in chat `content_parts` image/file inputs for this model. For image-capable chat models this includes values such as `"image/png"`. Empty for text-only models.',
 391    )
 392    name: str = Field(
 393        ...,
 394        description='Human-readable display label for this model, e.g. `"Claude Sonnet 4.6"` or `"Gemini 3.5 Flash (thinking)"`. Render this value directly in pickers rather than attempting to parse or transform `id`. Falls back to the `id` string when the catalog entry does not declare an explicit name.',
 395    )
 396    output_media_formats: list[str] = Field(
 397        ...,
 398        description="MIME types this model can emit as media in chat responses. Empty for text-output models, including image-understanding models that only return text.",
 399    )
 400
 401
 402class EvaluationModelsResponse(BaseModel):
 403    """
 404    Successful response
 405    """
 406
 407    data: list[EvaluationModelsResponseDataItem] = Field(
 408        ...,
 409        description="Array of available evaluation model objects. At least one entry is always present.",
 410    )
 411
 412
 413class ImageModelsResponseDataItem(BaseModel):
 414    capabilities: list[Literal["image", "search", "temperature", "thinking"]] = Field(
 415        ...,
 416        description='Machine-readable model capabilities. `"image"` marks image-input chat, `"search"` marks built-in web search, `"temperature"` marks models that accept the temperature generation parameter, and `"thinking"` marks models with configurable reasoning. Empty when the catalog entry declares no special capabilities.',
 417    )
 418    context_window: int | None = Field(
 419        default=None,
 420        description="Maximum context-window size in tokens this model accepts, when the platform publishes it. Use it to size prompt/history against the real window rather than a hardcoded default. `null` for entries whose window the platform does not report (e.g. legacy or mock model listings); clients should apply a conservative fallback in that case.",
 421    )
 422    default: bool = Field(
 423        ...,
 424        description="`true` for the model the platform selects when an agent has no `default_model` configured, or for the system-wide fallback in image-generation contexts. Exactly one entry in any given model list carries this flag.",
 425    )
 426    id: str = Field(
 427        ...,
 428        description='Provider-assigned model identifier used when specifying a model on API requests, e.g. `"claude-sonnet-4-6"` or `"gemini-2.5-flash"`.',
 429    )
 430    input_media_formats: list[str] = Field(
 431        ...,
 432        description='MIME types accepted in chat `content_parts` image/file inputs for this model. For image-capable chat models this includes values such as `"image/png"`. Empty for text-only models.',
 433    )
 434    name: str = Field(
 435        ...,
 436        description='Human-readable display label for this model, e.g. `"Claude Sonnet 4.6"` or `"Gemini 3.5 Flash (thinking)"`. Render this value directly in pickers rather than attempting to parse or transform `id`. Falls back to the `id` string when the catalog entry does not declare an explicit name.',
 437    )
 438    output_media_formats: list[str] = Field(
 439        ...,
 440        description="MIME types this model can emit as media in chat responses. Empty for text-output models, including image-understanding models that only return text.",
 441    )
 442
 443
 444class ImageModelsResponse(BaseModel):
 445    """
 446    Successful response
 447    """
 448
 449    data: list[ImageModelsResponseDataItem] = Field(
 450        ...,
 451        description="Array of available image generation models, including their identifiers, human-readable names, and which one is the platform default.",
 452    )
 453
 454
 455class AiSessionTokenResponse(BaseModel):
 456    """
 457    Successful response
 458    """
 459
 460    expires_at: str
 461    token: str
 462
 463
 464class AiUsageResponseDataItem(BaseModel):
 465    agent_id: str | None = Field(
 466        default=None,
 467        description="Agent ID for this group. Present only when grouped by `agent_id`.",
 468    )
 469    agent_kind: str | None = Field(
 470        default=None,
 471        description="Agent kind for this group. Present only when grouped by `agent_kind`.",
 472    )
 473    billed_usd: float | None = Field(
 474        default=None,
 475        description="Customer-billed cost for this group in USD. `null` when `priced` is `false`.",
 476    )
 477    cache_read_tokens: int = Field(..., description="Summed cache-read tokens in this group.")
 478    cache_write_tokens: int = Field(..., description="Summed cache-write tokens in this group.")
 479    completion_tokens: int = Field(
 480        ..., description="Summed completion (output) tokens in this group."
 481    )
 482    hour: str | None = Field(
 483        default=None,
 484        description="Hour bucket (ISO 8601) for this group. Present only when grouped by `hour`.",
 485    )
 486    model: str | None = Field(
 487        default=None,
 488        description="Model identifier for this group. Present only when grouped by `model`.",
 489    )
 490    priced: bool = Field(
 491        ...,
 492        description="`true` when `billed_usd` was priced from the customer's active billing plan; `false` when the group could not be priced.",
 493    )
 494    prompt_tokens: int = Field(..., description="Summed prompt (input) tokens in this group.")
 495    requests: int = Field(..., description="Number of LLM calls in this group.")
 496    task: str | None = Field(
 497        default=None,
 498        description="Caller task ID for this group. Present only when grouped by `task`.",
 499    )
 500
 501
 502class AiUsageResponse(BaseModel):
 503    """
 504    Successful response
 505    """
 506
 507    data: list[AiUsageResponseDataItem] = Field(
 508        ...,
 509        description="One row per group with request/token sums, the group key fields, `billed_usd`, and `priced`.",
 510    )
 511    since: str = Field(..., description="Effective window start (ISO 8601).")
 512    until: str = Field(..., description="Effective window end (ISO 8601).")
 513
 514
 515class StreamCreateEventDone(TypedDict):
 516    event: Literal["done"]
 517    data: AIChatStreamDone
 518
 519
 520class StreamCreateEventError(TypedDict):
 521    event: Literal["error"]
 522    data: AIChatStreamError
 523
 524
 525class StreamCreateEventMessageComplete(TypedDict):
 526    event: Literal["message_complete"]
 527    data: AIChatStreamMessageComplete
 528
 529
 530class StreamCreateEventMessageDelta(TypedDict):
 531    event: Literal["message_delta"]
 532    data: AIChatStreamMessageDelta
 533
 534
 535class StreamCreateEventThinkingDelta(TypedDict):
 536    event: Literal["thinking_delta"]
 537    data: AIChatStreamThinkingDelta
 538
 539
 540class StreamCreateEventToolCallDelta(TypedDict):
 541    event: Literal["tool_call_delta"]
 542    data: AIChatStreamToolCallDelta
 543
 544
 545class StreamCreateEventToolResult(TypedDict):
 546    event: Literal["tool_result"]
 547    data: AIChatStreamToolResult
 548
 549
 550StreamCreateEvent = (
 551    StreamCreateEventDone
 552    | StreamCreateEventError
 553    | StreamCreateEventMessageComplete
 554    | StreamCreateEventMessageDelta
 555    | StreamCreateEventThinkingDelta
 556    | StreamCreateEventToolCallDelta
 557    | StreamCreateEventToolResult
 558)
 559
 560
 561class AsyncStreamResource:
 562    def __init__(self, http: HttpClient):
 563        self._http = http
 564
 565    async def create(self, input: StreamCreateInput) -> AsyncIterator[StreamCreateEvent]:
 566        """
 567        Stream a chat completion
 568        Streams a chat completion over Server-Sent Events. Emits `thinking_delta` for
 569        supported reasoning models, `message_delta`, `message_complete`,
 570        `tool_call_*`, `tool_result`, and a terminal `done` (or `error`) event. Same
 571        request shape as the non-streaming completion endpoint; the app must have the
 572        `llm_calls` entitlement.
 573
 574        Args:
 575            input: Request body.
 576            input.attribution: Optional caller tags recorded on the LLM-call accounting row. Allowed keys: `task_id` (max 64 chars), `work_id` (max 64), `agent_kind` (one of `worker`, `one_off`, `subagent`, `overseer`, `task_reviewer`, `interactive`, `daemon_job`), `agent_id` (max 64), `client` (max 32). Anything else is a 400.
 577            input.context: Key-value map used to resolve template variables in message content. Omit if messages contain no templates.
 578            input.messages: Ordered list of conversation messages to send to the model.
 579            input.opts: Model and sampling configuration for this request.
 580            input.session_id: Optional UUID grouping this and other completions under one session in the Developers dashboard. Pass the same value across requests to link them; omit to auto-generate a per-request session.
 581
 582        Returns:
 583            Server-Sent Events stream
 584        """
 585        async for event in self._http.stream_sse(
 586            "/api/v1/ai/chat/completions/stream", method="POST", body=input
 587        ):
 588            yield event
 589
 590
 591class AsyncCompletionResource:
 592    def __init__(self, http: HttpClient):
 593        self._http = http
 594        self.stream = AsyncStreamResource(http)
 595
 596    async def create(self, input: CompletionCreateInput) -> AICompletionResult:
 597        """
 598        Create a chat completion
 599        Sends a list of messages to the configured AI provider and returns a single
 600        completion. Use this endpoint when you want direct, low-level access to the
 601        underlying model without any workflow or agent orchestration.
 602        The authenticated app must have the `llm_calls` entitlement enabled on its
 603        plan. Requests that exceed the plan quota are rejected with `402`. Token
 604        usage is recorded against the authenticated app and organization.
 605        Supply `tools` and `tool_choice` to enable OpenAI-compatible function
 606        calling. Use `server_tools` to activate platform-managed tools such as
 607        search that run on the server side before the response is returned.
 608
 609        Args:
 610            input: Request body.
 611            input.attribution: Optional caller tags recorded on the LLM-call accounting row. Allowed keys: `task_id` (max 64 chars), `work_id` (max 64), `agent_kind` (one of `worker`, `one_off`, `subagent`, `overseer`, `task_reviewer`, `interactive`, `daemon_job`), `agent_id` (max 64), `client` (max 32). Anything else is a 400.
 612            input.context: Key-value map used to resolve template variables in message content. Omit if messages contain no templates.
 613            input.messages: Ordered list of conversation messages to send to the model.
 614            input.opts: Model and sampling configuration for this request.
 615            input.session_id: Optional UUID grouping this and other completions under one session in the Developers dashboard. Pass the same value across requests to link them; omit to auto-generate a per-request session.
 616
 617        Returns:
 618            The completed AI response, including the generated message, finish reason, and token usage.
 619        """
 620        return await self._http.request(
 621            "/api/v1/ai/chat/completions",
 622            method="POST",
 623            body=input,
 624            response_type=AICompletionResult,
 625        )
 626
 627
 628class AsyncChatResource:
 629    def __init__(self, http: HttpClient):
 630        self._http = http
 631        self.completions = AsyncCompletionResource(http)
 632
 633    async def models(self) -> ChatModelsResponse:
 634        """
 635        List available AI models
 636        Returns the set of AI models that can be used with the chat completion and
 637        workflow endpoints. The list reflects models currently enabled for the
 638        platform and includes each model's identifier and whether it is the default.
 639        Use the `model` field from any entry in `data` as the value for
 640        `opts.model` when calling the completions or workflows endpoint.
 641
 642        Returns:
 643            Successful response
 644        """
 645        return await self._http.request("/api/v1/ai/chat/models", response_type=ChatModelsResponse)
 646
 647
 648class AsyncEmbeddingResource:
 649    def __init__(self, http: HttpClient):
 650        self._http = http
 651
 652    async def similarity_comparison(
 653        self, input: EmbeddingSimilarityComparisonInput
 654    ) -> EmbeddingSimilarityComparisonResponse:
 655        """
 656        Compare the embedding similarity of two texts
 657        Embeds both texts in one synchronous request using the platform's default
 658        embedding model, then returns their cosine similarity. The score uses the
 659        same `1 - cosine_distance` convention as context retrieval. A score near
 660        `1.0` indicates similar vector direction; lower scores indicate less similar
 661        text. This endpoint is intended for authenticated users interactively
 662        exploring how the platform's retrieval similarity behaves.
 663
 664        Args:
 665            input: Request body.
 666            input.text_a: First text to embed and compare.
 667            input.text_b: Second text to embed and compare.
 668
 669        Returns:
 670            Successful response
 671        """
 672        return await self._http.request(
 673            "/api/v1/ai/embedding/similarity_comparison",
 674            method="POST",
 675            body=input,
 676            response_type=EmbeddingSimilarityComparisonResponse,
 677        )
 678
 679
 680class AsyncEvaluationResource:
 681    def __init__(self, http: HttpClient):
 682        self._http = http
 683
 684    async def evaluations(self, input: EvaluationEvaluationsInput) -> AIEvaluationResult:
 685        """
 686        Create an evaluation
 687        Sends a shared `state` and a list of typed questions to an evaluation
 688        model and returns typed answers. This is not chat completion and not
 689        JSON-schema structured output: there is no generated text.
 690        Each question is a `boolean`, `choice`, or `score` object with its own
 691        `id`. Answers carry that `id`, including a `refusal` answer containing
 692        only `id` and `type` when the model declines to judge a question.
 693        Image input, labelled score levels, and refusal answers are model-dependent.
 694        Images are separate from `state` and use the chat completion image-part format.
 695        Models without image support reject image input with `400 unsupported_capability`.
 696        The authenticated app must have the `llm_calls` entitlement enabled on its
 697        plan. Requests that exceed the plan quota are rejected with `402`. Token
 698        usage is recorded against the authenticated app and organization.
 699
 700        Args:
 701            input: Request body.
 702            input.images: Optional image content parts. Omitted or empty means no images. Requires model image support.
 703            input.model: Evaluation model identifier. Omit to use the platform default.
 704            input.questions: Nonempty list of boolean, choice, or score questions. Each question must include `id`, `type`, and `instructions`.
 705            input.session_id: Optional UUID grouping this evaluation under one session in the Developers dashboard. Generated when omitted.
 706            input.state: Shared content the model judges. A string, JSON object, or JSON array. Every question in the request sees this same state.
 707
 708        Returns:
 709            Typed boolean, choice, score, or refusal answers, plus model and usage.
 710        """
 711        return await self._http.request(
 712            "/api/v1/ai/evaluation/evaluations",
 713            method="POST",
 714            body=input,
 715            response_type=AIEvaluationResult,
 716        )
 717
 718    async def models(self) -> EvaluationModelsResponse:
 719        """
 720        List available evaluation models
 721        Returns the set of evaluation models that can be used with the evaluations
 722        endpoint. The list reflects models currently enabled for the platform and
 723        includes each model's identifier and whether it is the default.
 724        Use the `id` field from any entry in `data` as the `model` value when
 725        calling the evaluations endpoint.
 726
 727        Returns:
 728            Successful response
 729        """
 730        return await self._http.request(
 731            "/api/v1/ai/evaluation/models",
 732            response_type=EvaluationModelsResponse,
 733        )
 734
 735
 736class AsyncImageResource:
 737    def __init__(self, http: HttpClient):
 738        self._http = http
 739
 740    async def edits(self, input: ImageEditsInput) -> AIImageResult:
 741        """
 742        Edit an image with a text prompt
 743        Applies a text-guided edit to one or more source images and returns the
 744        resulting image. Pass the source images as base64-encoded objects in the
 745        `images` array alongside a `prompt` describing the desired modification.
 746        The underlying provider is selected by the `model` parameter. Omit `model`
 747        to use the platform default. Size, quality, style, and format options are
 748        forwarded to the provider as-is; unsupported combinations for a given model
 749        return a 422 error with the provider's error message.
 750        This endpoint requires authentication. The request is billed against the
 751        workspace associated with the authenticated user.
 752
 753        Args:
 754            input: Request body.
 755            input.aspect_ratio: Desired aspect ratio of the output, e.g. `"1:1"` or `"16:9"`. Not supported by all models; omit to use the model's default.
 756            input.background: Background treatment for the output. Accepted values and behavior are model-dependent.
 757            input.height: Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
 758            input.image_size: Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.
 759            input.images: One or more source images to edit. Each image must be supplied as a base64-encoded object.
 760            input.model: Model identifier to use for editing. Omit to use the platform default image model.
 761            input.output_format: Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model's native format.
 762            input.prompt: Natural-language description of the edit to apply to the source image(s).
 763            input.quality: Quality preset for the output image. Accepted values and behavior are model-dependent.
 764            input.session_id: Optional session UUID for grouping provider attempts in usage records. Generated when omitted.
 765            input.size: Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model's default.
 766            input.style: Style preset applied to the edit. Accepted values and behavior are model-dependent.
 767            input.width: Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
 768
 769        Returns:
 770            The resulting edited image, including base64 data or a URL depending on the model.
 771        """
 772        return await self._http.request(
 773            "/api/v1/ai/image/edits",
 774            method="POST",
 775            body=input,
 776            response_type=AIImageResult,
 777        )
 778
 779    async def generations(self, input: ImageGenerationsInput) -> AIImageResult:
 780        """
 781        Generate an image from a text prompt
 782        Generates one or more images from a natural-language `prompt` using the
 783        specified AI image model. The response contains the first generated image;
 784        use `n` to request additional images (where supported by the model).
 785        The underlying provider is selected by the `model` parameter. Omit `model`
 786        to use the platform default. Size, quality, style, and format options are
 787        forwarded to the provider as-is; unsupported combinations for a given model
 788        return a 422 error with the provider's error message.
 789        This endpoint requires authentication. The request is billed against the
 790        workspace associated with the authenticated user.
 791
 792        Args:
 793            input: Request body.
 794            input.aspect_ratio: Desired aspect ratio of the output, e.g. `"1:1"` or `"16:9"`. Not supported by all models; omit to use the model's default.
 795            input.background: Background treatment for the output. Accepted values and behavior are model-dependent.
 796            input.height: Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
 797            input.image_size: Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.
 798            input.model: Model identifier to use for generation. Omit to use the platform default image model.
 799            input.n: Number of images to generate. Defaults to `1`. Values greater than `1` are only supported by models that allow batch generation.
 800            input.output_format: Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model's native format.
 801            input.prompt: Natural-language description of the image to generate.
 802            input.quality: Quality preset for the output image. Accepted values and behavior are model-dependent.
 803            input.session_id: Optional session UUID for grouping provider attempts in usage records. Generated when omitted.
 804            input.size: Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model's default.
 805            input.style: Style preset applied to the generated image. Accepted values and behavior are model-dependent.
 806            input.width: Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
 807
 808        Returns:
 809            The generated image, including base64 data or a URL depending on the model.
 810        """
 811        return await self._http.request(
 812            "/api/v1/ai/image/generations",
 813            method="POST",
 814            body=input,
 815            response_type=AIImageResult,
 816        )
 817
 818    async def models(self) -> ImageModelsResponse:
 819        """
 820        List available image generation models
 821        Returns the list of image generation models available on the platform.
 822        Exactly one entry in the list carries `default: true`, indicating the model
 823        used when no `model` parameter is supplied to the generation or editing
 824        endpoints.
 825        This endpoint requires authentication and reflects the models enabled for
 826        the authenticated user's workspace.
 827
 828        Returns:
 829            Successful response
 830        """
 831        return await self._http.request(
 832            "/api/v1/ai/image/models",
 833            response_type=ImageModelsResponse,
 834        )
 835
 836
 837class AsyncAiResource:
 838    def __init__(self, http: HttpClient):
 839        self._http = http
 840        self.chat = AsyncChatResource(http)
 841        self.embedding = AsyncEmbeddingResource(http)
 842        self.evaluation = AsyncEvaluationResource(http)
 843        self.image = AsyncImageResource(http)
 844
 845    async def session_token(self, input: AiSessionTokenInput) -> AiSessionTokenResponse:
 846        """
 847        Mint a principal-bound billing session token
 848
 849        Args:
 850            input: Request body.
 851
 852        Returns:
 853            Successful response
 854        """
 855        return await self._http.request(
 856            "/api/v1/ai/session_token",
 857            method="POST",
 858            body=input,
 859            response_type=AiSessionTokenResponse,
 860        )
 861
 862    async def usage(
 863        self,
 864        *,
 865        since: str | None = None,
 866        until: str | None = None,
 867        group_by: list[Literal["task", "model", "agent_kind", "agent_id", "hour"]] | None = None,
 868        task: list[str] | None = None,
 869        limit: int | None = None,
 870    ) -> AiUsageResponse:
 871        """
 872        Read the authenticated user's LLM usage
 873        Returns the authenticated user's own LLM usage aggregated over a bounded
 874        time window. Each row carries request and token sums plus the customer-billed
 875        cost for the group. Cost is derived from the customer's active billing plan;
 876        provider-reported cost is never returned.
 877        Pass `group_by` one or more times to choose the grouping dimensions
 878        (`task`, `model`, `agent_kind`, `agent_id`, `hour`). The window (`since` to
 879        `until`) may span at most 31 days. Results are capped at `limit` groups.
 880
 881        Args:
 882            since: Window start as an ISO 8601 timestamp (inclusive). Defaults to 7 days before `until`.
 883            until: Window end as an ISO 8601 timestamp (inclusive). Defaults to now.
 884            group_by: Grouping dimensions. Repeat for multiple dimensions (e.g. `group_by[]=task&group_by[]=model`). Defaults to `model`.
 885            task: Restrict results to these caller task IDs. Omit to include every task.
 886            limit: Maximum number of groups to return. Defaults to 50; maximum is 200.
 887
 888        Returns:
 889            Successful response
 890        """
 891        query: dict[str, object] = {}
 892        if since is not None:
 893            query["since"] = since
 894        if until is not None:
 895            query["until"] = until
 896        if group_by is not None:
 897            query["group_by"] = group_by
 898        if task is not None:
 899            query["task"] = task
 900        if limit is not None:
 901            query["limit"] = limit
 902        return await self._http.request(
 903            "/api/v1/ai/usage",
 904            query=query,
 905            response_type=AiUsageResponse,
 906        )
 907
 908
 909class StreamResource:
 910    def __init__(self, http: SyncHttpClient):
 911        self._http = http
 912
 913    def create(self, input: StreamCreateInput) -> Iterator[StreamCreateEvent]:
 914        """
 915        Stream a chat completion
 916        Streams a chat completion over Server-Sent Events. Emits `thinking_delta` for
 917        supported reasoning models, `message_delta`, `message_complete`,
 918        `tool_call_*`, `tool_result`, and a terminal `done` (or `error`) event. Same
 919        request shape as the non-streaming completion endpoint; the app must have the
 920        `llm_calls` entitlement.
 921
 922        Args:
 923            input: Request body.
 924            input.attribution: Optional caller tags recorded on the LLM-call accounting row. Allowed keys: `task_id` (max 64 chars), `work_id` (max 64), `agent_kind` (one of `worker`, `one_off`, `subagent`, `overseer`, `task_reviewer`, `interactive`, `daemon_job`), `agent_id` (max 64), `client` (max 32). Anything else is a 400.
 925            input.context: Key-value map used to resolve template variables in message content. Omit if messages contain no templates.
 926            input.messages: Ordered list of conversation messages to send to the model.
 927            input.opts: Model and sampling configuration for this request.
 928            input.session_id: Optional UUID grouping this and other completions under one session in the Developers dashboard. Pass the same value across requests to link them; omit to auto-generate a per-request session.
 929
 930        Returns:
 931            Server-Sent Events stream
 932        """
 933        yield from self._http.stream_sse_sync(
 934            "/api/v1/ai/chat/completions/stream", method="POST", body=input
 935        )
 936
 937
 938class CompletionResource:
 939    def __init__(self, http: SyncHttpClient):
 940        self._http = http
 941        self.stream = StreamResource(http)
 942
 943    def create(self, input: CompletionCreateInput) -> AICompletionResult:
 944        """
 945        Create a chat completion
 946        Sends a list of messages to the configured AI provider and returns a single
 947        completion. Use this endpoint when you want direct, low-level access to the
 948        underlying model without any workflow or agent orchestration.
 949        The authenticated app must have the `llm_calls` entitlement enabled on its
 950        plan. Requests that exceed the plan quota are rejected with `402`. Token
 951        usage is recorded against the authenticated app and organization.
 952        Supply `tools` and `tool_choice` to enable OpenAI-compatible function
 953        calling. Use `server_tools` to activate platform-managed tools such as
 954        search that run on the server side before the response is returned.
 955
 956        Args:
 957            input: Request body.
 958            input.attribution: Optional caller tags recorded on the LLM-call accounting row. Allowed keys: `task_id` (max 64 chars), `work_id` (max 64), `agent_kind` (one of `worker`, `one_off`, `subagent`, `overseer`, `task_reviewer`, `interactive`, `daemon_job`), `agent_id` (max 64), `client` (max 32). Anything else is a 400.
 959            input.context: Key-value map used to resolve template variables in message content. Omit if messages contain no templates.
 960            input.messages: Ordered list of conversation messages to send to the model.
 961            input.opts: Model and sampling configuration for this request.
 962            input.session_id: Optional UUID grouping this and other completions under one session in the Developers dashboard. Pass the same value across requests to link them; omit to auto-generate a per-request session.
 963
 964        Returns:
 965            The completed AI response, including the generated message, finish reason, and token usage.
 966        """
 967        return self._http.request(
 968            "/api/v1/ai/chat/completions",
 969            method="POST",
 970            body=input,
 971            response_type=AICompletionResult,
 972        )
 973
 974
 975class ChatResource:
 976    def __init__(self, http: SyncHttpClient):
 977        self._http = http
 978        self.completions = CompletionResource(http)
 979
 980    def models(self) -> ChatModelsResponse:
 981        """
 982        List available AI models
 983        Returns the set of AI models that can be used with the chat completion and
 984        workflow endpoints. The list reflects models currently enabled for the
 985        platform and includes each model's identifier and whether it is the default.
 986        Use the `model` field from any entry in `data` as the value for
 987        `opts.model` when calling the completions or workflows endpoint.
 988
 989        Returns:
 990            Successful response
 991        """
 992        return self._http.request("/api/v1/ai/chat/models", response_type=ChatModelsResponse)
 993
 994
 995class EmbeddingResource:
 996    def __init__(self, http: SyncHttpClient):
 997        self._http = http
 998
 999    def similarity_comparison(
1000        self, input: EmbeddingSimilarityComparisonInput
1001    ) -> EmbeddingSimilarityComparisonResponse:
1002        """
1003        Compare the embedding similarity of two texts
1004        Embeds both texts in one synchronous request using the platform's default
1005        embedding model, then returns their cosine similarity. The score uses the
1006        same `1 - cosine_distance` convention as context retrieval. A score near
1007        `1.0` indicates similar vector direction; lower scores indicate less similar
1008        text. This endpoint is intended for authenticated users interactively
1009        exploring how the platform's retrieval similarity behaves.
1010
1011        Args:
1012            input: Request body.
1013            input.text_a: First text to embed and compare.
1014            input.text_b: Second text to embed and compare.
1015
1016        Returns:
1017            Successful response
1018        """
1019        return self._http.request(
1020            "/api/v1/ai/embedding/similarity_comparison",
1021            method="POST",
1022            body=input,
1023            response_type=EmbeddingSimilarityComparisonResponse,
1024        )
1025
1026
1027class EvaluationResource:
1028    def __init__(self, http: SyncHttpClient):
1029        self._http = http
1030
1031    def evaluations(self, input: EvaluationEvaluationsInput) -> AIEvaluationResult:
1032        """
1033        Create an evaluation
1034        Sends a shared `state` and a list of typed questions to an evaluation
1035        model and returns typed answers. This is not chat completion and not
1036        JSON-schema structured output: there is no generated text.
1037        Each question is a `boolean`, `choice`, or `score` object with its own
1038        `id`. Answers carry that `id`, including a `refusal` answer containing
1039        only `id` and `type` when the model declines to judge a question.
1040        Image input, labelled score levels, and refusal answers are model-dependent.
1041        Images are separate from `state` and use the chat completion image-part format.
1042        Models without image support reject image input with `400 unsupported_capability`.
1043        The authenticated app must have the `llm_calls` entitlement enabled on its
1044        plan. Requests that exceed the plan quota are rejected with `402`. Token
1045        usage is recorded against the authenticated app and organization.
1046
1047        Args:
1048            input: Request body.
1049            input.images: Optional image content parts. Omitted or empty means no images. Requires model image support.
1050            input.model: Evaluation model identifier. Omit to use the platform default.
1051            input.questions: Nonempty list of boolean, choice, or score questions. Each question must include `id`, `type`, and `instructions`.
1052            input.session_id: Optional UUID grouping this evaluation under one session in the Developers dashboard. Generated when omitted.
1053            input.state: Shared content the model judges. A string, JSON object, or JSON array. Every question in the request sees this same state.
1054
1055        Returns:
1056            Typed boolean, choice, score, or refusal answers, plus model and usage.
1057        """
1058        return self._http.request(
1059            "/api/v1/ai/evaluation/evaluations",
1060            method="POST",
1061            body=input,
1062            response_type=AIEvaluationResult,
1063        )
1064
1065    def models(self) -> EvaluationModelsResponse:
1066        """
1067        List available evaluation models
1068        Returns the set of evaluation models that can be used with the evaluations
1069        endpoint. The list reflects models currently enabled for the platform and
1070        includes each model's identifier and whether it is the default.
1071        Use the `id` field from any entry in `data` as the `model` value when
1072        calling the evaluations endpoint.
1073
1074        Returns:
1075            Successful response
1076        """
1077        return self._http.request(
1078            "/api/v1/ai/evaluation/models",
1079            response_type=EvaluationModelsResponse,
1080        )
1081
1082
1083class ImageResource:
1084    def __init__(self, http: SyncHttpClient):
1085        self._http = http
1086
1087    def edits(self, input: ImageEditsInput) -> AIImageResult:
1088        """
1089        Edit an image with a text prompt
1090        Applies a text-guided edit to one or more source images and returns the
1091        resulting image. Pass the source images as base64-encoded objects in the
1092        `images` array alongside a `prompt` describing the desired modification.
1093        The underlying provider is selected by the `model` parameter. Omit `model`
1094        to use the platform default. Size, quality, style, and format options are
1095        forwarded to the provider as-is; unsupported combinations for a given model
1096        return a 422 error with the provider's error message.
1097        This endpoint requires authentication. The request is billed against the
1098        workspace associated with the authenticated user.
1099
1100        Args:
1101            input: Request body.
1102            input.aspect_ratio: Desired aspect ratio of the output, e.g. `"1:1"` or `"16:9"`. Not supported by all models; omit to use the model's default.
1103            input.background: Background treatment for the output. Accepted values and behavior are model-dependent.
1104            input.height: Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
1105            input.image_size: Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.
1106            input.images: One or more source images to edit. Each image must be supplied as a base64-encoded object.
1107            input.model: Model identifier to use for editing. Omit to use the platform default image model.
1108            input.output_format: Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model's native format.
1109            input.prompt: Natural-language description of the edit to apply to the source image(s).
1110            input.quality: Quality preset for the output image. Accepted values and behavior are model-dependent.
1111            input.session_id: Optional session UUID for grouping provider attempts in usage records. Generated when omitted.
1112            input.size: Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model's default.
1113            input.style: Style preset applied to the edit. Accepted values and behavior are model-dependent.
1114            input.width: Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
1115
1116        Returns:
1117            The resulting edited image, including base64 data or a URL depending on the model.
1118        """
1119        return self._http.request(
1120            "/api/v1/ai/image/edits",
1121            method="POST",
1122            body=input,
1123            response_type=AIImageResult,
1124        )
1125
1126    def generations(self, input: ImageGenerationsInput) -> AIImageResult:
1127        """
1128        Generate an image from a text prompt
1129        Generates one or more images from a natural-language `prompt` using the
1130        specified AI image model. The response contains the first generated image;
1131        use `n` to request additional images (where supported by the model).
1132        The underlying provider is selected by the `model` parameter. Omit `model`
1133        to use the platform default. Size, quality, style, and format options are
1134        forwarded to the provider as-is; unsupported combinations for a given model
1135        return a 422 error with the provider's error message.
1136        This endpoint requires authentication. The request is billed against the
1137        workspace associated with the authenticated user.
1138
1139        Args:
1140            input: Request body.
1141            input.aspect_ratio: Desired aspect ratio of the output, e.g. `"1:1"` or `"16:9"`. Not supported by all models; omit to use the model's default.
1142            input.background: Background treatment for the output. Accepted values and behavior are model-dependent.
1143            input.height: Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
1144            input.image_size: Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.
1145            input.model: Model identifier to use for generation. Omit to use the platform default image model.
1146            input.n: Number of images to generate. Defaults to `1`. Values greater than `1` are only supported by models that allow batch generation.
1147            input.output_format: Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model's native format.
1148            input.prompt: Natural-language description of the image to generate.
1149            input.quality: Quality preset for the output image. Accepted values and behavior are model-dependent.
1150            input.session_id: Optional session UUID for grouping provider attempts in usage records. Generated when omitted.
1151            input.size: Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model's default.
1152            input.style: Style preset applied to the generated image. Accepted values and behavior are model-dependent.
1153            input.width: Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
1154
1155        Returns:
1156            The generated image, including base64 data or a URL depending on the model.
1157        """
1158        return self._http.request(
1159            "/api/v1/ai/image/generations",
1160            method="POST",
1161            body=input,
1162            response_type=AIImageResult,
1163        )
1164
1165    def models(self) -> ImageModelsResponse:
1166        """
1167        List available image generation models
1168        Returns the list of image generation models available on the platform.
1169        Exactly one entry in the list carries `default: true`, indicating the model
1170        used when no `model` parameter is supplied to the generation or editing
1171        endpoints.
1172        This endpoint requires authentication and reflects the models enabled for
1173        the authenticated user's workspace.
1174
1175        Returns:
1176            Successful response
1177        """
1178        return self._http.request("/api/v1/ai/image/models", response_type=ImageModelsResponse)
1179
1180
1181class AiResource:
1182    def __init__(self, http: SyncHttpClient):
1183        self._http = http
1184        self.chat = ChatResource(http)
1185        self.embedding = EmbeddingResource(http)
1186        self.evaluation = EvaluationResource(http)
1187        self.image = ImageResource(http)
1188
1189    def session_token(self, input: AiSessionTokenInput) -> AiSessionTokenResponse:
1190        """
1191        Mint a principal-bound billing session token
1192
1193        Args:
1194            input: Request body.
1195
1196        Returns:
1197            Successful response
1198        """
1199        return self._http.request(
1200            "/api/v1/ai/session_token",
1201            method="POST",
1202            body=input,
1203            response_type=AiSessionTokenResponse,
1204        )
1205
1206    def usage(
1207        self,
1208        *,
1209        since: str | None = None,
1210        until: str | None = None,
1211        group_by: list[Literal["task", "model", "agent_kind", "agent_id", "hour"]] | None = None,
1212        task: list[str] | None = None,
1213        limit: int | None = None,
1214    ) -> AiUsageResponse:
1215        """
1216        Read the authenticated user's LLM usage
1217        Returns the authenticated user's own LLM usage aggregated over a bounded
1218        time window. Each row carries request and token sums plus the customer-billed
1219        cost for the group. Cost is derived from the customer's active billing plan;
1220        provider-reported cost is never returned.
1221        Pass `group_by` one or more times to choose the grouping dimensions
1222        (`task`, `model`, `agent_kind`, `agent_id`, `hour`). The window (`since` to
1223        `until`) may span at most 31 days. Results are capped at `limit` groups.
1224
1225        Args:
1226            since: Window start as an ISO 8601 timestamp (inclusive). Defaults to 7 days before `until`.
1227            until: Window end as an ISO 8601 timestamp (inclusive). Defaults to now.
1228            group_by: Grouping dimensions. Repeat for multiple dimensions (e.g. `group_by[]=task&group_by[]=model`). Defaults to `model`.
1229            task: Restrict results to these caller task IDs. Omit to include every task.
1230            limit: Maximum number of groups to return. Defaults to 50; maximum is 200.
1231
1232        Returns:
1233            Successful response
1234        """
1235        query: dict[str, object] = {}
1236        if since is not None:
1237            query["since"] = since
1238        if until is not None:
1239            query["until"] = until
1240        if group_by is not None:
1241            query["group_by"] = group_by
1242        if task is not None:
1243            query["task"] = task
1244        if limit is not None:
1245            query["limit"] = limit
1246        return self._http.request("/api/v1/ai/usage", query=query, response_type=AiUsageResponse)