archastro.platform.v1.resources.ai

  1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 7fb31d670565
  4
  5from __future__ import annotations
  6
  7from collections.abc import AsyncIterator, Iterator
  8from typing import Any, Literal, Required, TypedDict
  9
 10from pydantic import BaseModel, Field
 11
 12from ...runtime.http_client import HttpClient, SyncHttpClient
 13from ...types.ai import (
 14    AIChatStreamDone,
 15    AIChatStreamError,
 16    AIChatStreamMessageComplete,
 17    AIChatStreamMessageDelta,
 18    AIChatStreamToolCallDelta,
 19    AIChatStreamToolResult,
 20    AICompletionResult,
 21    AIImageResult,
 22)
 23
 24
 25class CompletionCreateInputMessagesItemToolCallsItem(TypedDict, total=False):
 26    arguments: Required[dict[str, Any]]
 27    "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."
 28    id: Required[str]
 29    "Unique identifier for this tool call, assigned by the model. Use this value as `id` when submitting the corresponding tool result."
 30    name: Required[str]
 31    'Name of the tool or function the model wants to invoke, e.g. `"web_search"` or `"run_code"`.'
 32    thought_signature: str | None
 33    "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."
 34
 35
 36class CompletionCreateInputMessagesItemToolResultsItem(TypedDict, total=False):
 37    content: str | None
 38    "Plain-text output produced by the tool execution. `null` when the result is expressed entirely through `resolution`."
 39    id: Required[str]
 40    "ID of the tool call this result satisfies. Must match the `id` from the corresponding `AIToolCall`."
 41    name: Required[str]
 42    'Name of the tool or function that was executed, e.g. `"web_search"`. Must match the `name` from the corresponding `AIToolCall`.'
 43    resolution: Any | None
 44    "Structured result data from the tool execution. Shape varies by tool. `null` when the result is expressed as plain text in `content`."
 45
 46
 47class CompletionCreateInputMessagesItem(TypedDict, total=False):
 48    content: str | None
 49    "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`."
 50    content_parts: list[dict[str, Any]] | None
 51    '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.'
 52    resume_token: str | None
 53    "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."
 54    role: Required[str]
 55    'The speaker role for this message. One of `"system"`, `"user"`, `"assistant"`, or `"tool"`.'
 56    structured_output: Any | None
 57    "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."
 58    tool_calls: list[CompletionCreateInputMessagesItemToolCallsItem] | None
 59    "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."
 60    tool_results: list[CompletionCreateInputMessagesItemToolResultsItem] | None
 61    "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."
 62
 63
 64class CompletionCreateInputOptsToolsItemFunction(TypedDict, total=False):
 65    description: str | None
 66    "Human-readable description of what the function does. The model uses this to decide when to call the function. `null` if not provided."
 67    name: Required[str]
 68    'Unique name of the function that the model can invoke, e.g. `"get_weather"`.'
 69    parameters: Required[dict[str, Any]]
 70    'JSON Schema object describing the function\'s accepted parameters. Must be a valid JSON Schema of type `"object"`.'
 71
 72
 73class CompletionCreateInputOptsToolsItem(TypedDict):
 74    function: CompletionCreateInputOptsToolsItemFunction
 75    "Callable function this tool exposes, including its name, description, and parameter schema."
 76    type: str
 77    'The tool type. Currently always `"function"`.'
 78
 79
 80class CompletionCreateInputOpts(TypedDict, total=False):
 81    max_tokens: int | None
 82    "Maximum number of tokens the model may generate in the completion. Omit to use the model's default limit."
 83    model: Required[str]
 84    'Model identifier to use for the completion, e.g. `"gpt-4o"` or `"claude-3-7-sonnet-latest"`.'
 85    server_tools: list[dict[str, Any]] | None
 86    'Server-managed tool declarations executed before the response is returned. Each entry must include a `type` key; currently only `"search"` is supported.'
 87    temperature: float | None
 88    "Sampling temperature between `0.0` and `2.0`. Higher values produce more random output. Omit to use the model's default."
 89    tool_choice: str | None
 90    'Controls how the model selects tools. One of `"auto"`, `"required"`, or `"none"`. Omit to let the model decide.'
 91    tools: list[CompletionCreateInputOptsToolsItem] | None
 92    "OpenAI-compatible tool definitions available to the model. Omit when not using function calling."
 93
 94
 95class CompletionCreateInput(TypedDict, total=False):
 96    "Create a chat completion"
 97
 98    context: dict[str, Any] | None
 99    "Key-value map used to resolve template variables in message content. Omit if messages contain no templates."
100    messages: Required[list[CompletionCreateInputMessagesItem]]
101    "Ordered list of conversation messages to send to the model."
102    opts: Required[CompletionCreateInputOpts]
103    "Model and sampling configuration for this request."
104
105
106class CompletionStreamInputMessagesItemToolCallsItem(TypedDict, total=False):
107    arguments: Required[dict[str, Any]]
108    "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."
109    id: Required[str]
110    "Unique identifier for this tool call, assigned by the model. Use this value as `id` when submitting the corresponding tool result."
111    name: Required[str]
112    'Name of the tool or function the model wants to invoke, e.g. `"web_search"` or `"run_code"`.'
113    thought_signature: str | None
114    "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."
115
116
117class CompletionStreamInputMessagesItemToolResultsItem(TypedDict, total=False):
118    content: str | None
119    "Plain-text output produced by the tool execution. `null` when the result is expressed entirely through `resolution`."
120    id: Required[str]
121    "ID of the tool call this result satisfies. Must match the `id` from the corresponding `AIToolCall`."
122    name: Required[str]
123    'Name of the tool or function that was executed, e.g. `"web_search"`. Must match the `name` from the corresponding `AIToolCall`.'
124    resolution: Any | None
125    "Structured result data from the tool execution. Shape varies by tool. `null` when the result is expressed as plain text in `content`."
126
127
128class CompletionStreamInputMessagesItem(TypedDict, total=False):
129    content: str | None
130    "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`."
131    content_parts: list[dict[str, Any]] | None
132    '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.'
133    resume_token: str | None
134    "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."
135    role: Required[str]
136    'The speaker role for this message. One of `"system"`, `"user"`, `"assistant"`, or `"tool"`.'
137    structured_output: Any | None
138    "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."
139    tool_calls: list[CompletionStreamInputMessagesItemToolCallsItem] | None
140    "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    tool_results: list[CompletionStreamInputMessagesItemToolResultsItem] | None
142    "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."
143
144
145class CompletionStreamInputOptsToolsItemFunction(TypedDict, total=False):
146    description: str | None
147    "Human-readable description of what the function does. The model uses this to decide when to call the function. `null` if not provided."
148    name: Required[str]
149    'Unique name of the function that the model can invoke, e.g. `"get_weather"`.'
150    parameters: Required[dict[str, Any]]
151    'JSON Schema object describing the function\'s accepted parameters. Must be a valid JSON Schema of type `"object"`.'
152
153
154class CompletionStreamInputOptsToolsItem(TypedDict):
155    function: CompletionStreamInputOptsToolsItemFunction
156    "Callable function this tool exposes, including its name, description, and parameter schema."
157    type: str
158    'The tool type. Currently always `"function"`.'
159
160
161class CompletionStreamInputOpts(TypedDict, total=False):
162    max_tokens: int | None
163    "Maximum number of tokens the model may generate. Omit for the model default."
164    model: Required[str]
165    'Model identifier, e.g. `"gpt-4o"` or `"claude-3-7-sonnet-latest"`.'
166    server_tools: list[dict[str, Any]] | None
167    'Server-managed tool declarations executed before the response. Each entry must include a `type` key; currently only `"search"` is supported.'
168    temperature: float | None
169    "Sampling temperature between `0.0` and `2.0`. Higher values produce more random output. Omit for the model default."
170    tool_choice: str | None
171    'Controls tool selection. One of `"auto"`, `"required"`, or `"none"`. Omit to let the model decide.'
172    tools: list[CompletionStreamInputOptsToolsItem] | None
173    "OpenAI-compatible tool definitions available to the model. Omit when not using function calling."
174
175
176class CompletionStreamInput(TypedDict, total=False):
177    "Stream a chat completion"
178
179    context: dict[str, Any] | None
180    "Key-value map used to resolve template variables in message content. Omit if messages contain no templates."
181    messages: Required[list[CompletionStreamInputMessagesItem]]
182    "Ordered list of conversation messages to send to the model."
183    opts: Required[CompletionStreamInputOpts]
184    "Model and sampling configuration for this request."
185
186
187class ImageEditsInputImagesItem(TypedDict):
188    image_data: str
189    "The raw image content encoded as a base64 string (standard encoding, no line breaks)."
190    image_type: str
191    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. Must match the actual encoding of `image_data`.'
192
193
194class ImageEditsInput(TypedDict, total=False):
195    "Edit an image with a text prompt"
196
197    aspect_ratio: str | None
198    '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.'
199    background: str | None
200    "Background treatment for the output. Accepted values and behavior are model-dependent."
201    height: int | None
202    "Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models."
203    image_size: str | None
204    'Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.'
205    images: Required[list[ImageEditsInputImagesItem]]
206    "One or more source images to edit. Each image must be supplied as a base64-encoded object."
207    model: str | None
208    "Model identifier to use for editing. Omit to use the platform default image model."
209    output_format: str | None
210    'Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model\'s native format.'
211    prompt: Required[str]
212    "Natural-language description of the edit to apply to the source image(s)."
213    quality: str | None
214    "Quality preset for the output image. Accepted values and behavior are model-dependent."
215    size: str | None
216    'Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model\'s default.'
217    style: str | None
218    "Style preset applied to the edit. Accepted values and behavior are model-dependent."
219    width: int | None
220    "Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models."
221
222
223class ImageGenerationsInput(TypedDict, total=False):
224    "Generate an image from a text prompt"
225
226    aspect_ratio: str | None
227    '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.'
228    background: str | None
229    "Background treatment for the output. Accepted values and behavior are model-dependent."
230    height: int | None
231    "Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models."
232    image_size: str | None
233    'Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.'
234    model: str | None
235    "Model identifier to use for generation. Omit to use the platform default image model."
236    n: int | None
237    "Number of images to generate. Defaults to `1`. Values greater than `1` are only supported by models that allow batch generation."
238    output_format: str | None
239    'Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model\'s native format.'
240    prompt: Required[str]
241    "Natural-language description of the image to generate."
242    quality: str | None
243    "Quality preset for the output image. Accepted values and behavior are model-dependent."
244    size: str | None
245    'Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model\'s default.'
246    style: str | None
247    "Style preset applied to the generated image. Accepted values and behavior are model-dependent."
248    width: int | None
249    "Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models."
250
251
252class ChatModelsResponseDataItem(BaseModel):
253    capabilities: list[Literal["image", "search", "thinking"]] = Field(
254        ...,
255        description='Machine-readable model capabilities. `"image"` marks image-input chat, `"search"` marks built-in web search, and `"thinking"` marks models with configurable reasoning. Empty when the catalog entry declares no special capabilities.',
256    )
257    default: bool = Field(
258        ...,
259        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.",
260    )
261    id: str = Field(
262        ...,
263        description='Provider-assigned model identifier used when specifying a model on API requests, e.g. `"claude-sonnet-4-6"` or `"gemini-2.5-flash"`.',
264    )
265    input_media_formats: list[str] = Field(
266        ...,
267        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.',
268    )
269    name: str = Field(
270        ...,
271        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.',
272    )
273    output_media_formats: list[str] = Field(
274        ...,
275        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.",
276    )
277
278
279class ChatModelsResponse(BaseModel):
280    """
281    Successful response
282    """
283
284    data: list[ChatModelsResponseDataItem] = Field(
285        ..., description="Array of available model objects. At least one entry is always present."
286    )
287
288
289class ImageModelsResponseDataItem(BaseModel):
290    capabilities: list[Literal["image", "search", "thinking"]] = Field(
291        ...,
292        description='Machine-readable model capabilities. `"image"` marks image-input chat, `"search"` marks built-in web search, and `"thinking"` marks models with configurable reasoning. Empty when the catalog entry declares no special capabilities.',
293    )
294    default: bool = Field(
295        ...,
296        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.",
297    )
298    id: str = Field(
299        ...,
300        description='Provider-assigned model identifier used when specifying a model on API requests, e.g. `"claude-sonnet-4-6"` or `"gemini-2.5-flash"`.',
301    )
302    input_media_formats: list[str] = Field(
303        ...,
304        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.',
305    )
306    name: str = Field(
307        ...,
308        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.',
309    )
310    output_media_formats: list[str] = Field(
311        ...,
312        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.",
313    )
314
315
316class ImageModelsResponse(BaseModel):
317    """
318    Successful response
319    """
320
321    data: list[ImageModelsResponseDataItem] = Field(
322        ...,
323        description="Array of available image generation models, including their identifiers, human-readable names, and which one is the platform default.",
324    )
325
326
327class CompletionStreamEventDone(TypedDict):
328    event: Literal["done"]
329    data: AIChatStreamDone
330
331
332class CompletionStreamEventError(TypedDict):
333    event: Literal["error"]
334    data: AIChatStreamError
335
336
337class CompletionStreamEventMessageComplete(TypedDict):
338    event: Literal["message_complete"]
339    data: AIChatStreamMessageComplete
340
341
342class CompletionStreamEventMessageDelta(TypedDict):
343    event: Literal["message_delta"]
344    data: AIChatStreamMessageDelta
345
346
347class CompletionStreamEventToolCallDelta(TypedDict):
348    event: Literal["tool_call_delta"]
349    data: AIChatStreamToolCallDelta
350
351
352class CompletionStreamEventToolResult(TypedDict):
353    event: Literal["tool_result"]
354    data: AIChatStreamToolResult
355
356
357CompletionStreamEvent = (
358    CompletionStreamEventDone
359    | CompletionStreamEventError
360    | CompletionStreamEventMessageComplete
361    | CompletionStreamEventMessageDelta
362    | CompletionStreamEventToolCallDelta
363    | CompletionStreamEventToolResult
364)
365
366
367class AsyncCompletionResource:
368    def __init__(self, http: HttpClient):
369        self._http = http
370
371    async def create(self, input: CompletionCreateInput) -> AICompletionResult:
372        """
373        Create a chat completion
374        Sends a list of messages to the configured AI provider and returns a single
375        completion. Use this endpoint when you want direct, low-level access to the
376        underlying model without any workflow or agent orchestration.
377        The authenticated app must have the `llm_calls` entitlement enabled on its
378        plan. Requests that exceed the plan quota are rejected with `402`. Token
379        usage is recorded against the authenticated app and organization.
380        Supply `tools` and `tool_choice` to enable OpenAI-compatible function
381        calling. Use `server_tools` to activate platform-managed tools such as
382        search that run on the server side before the response is returned.
383
384        Args:
385            input: Request body.
386            input.context: Key-value map used to resolve template variables in message content. Omit if messages contain no templates.
387            input.messages: Ordered list of conversation messages to send to the model.
388            input.opts: Model and sampling configuration for this request.
389
390        Returns:
391            The completed AI response, including the generated message, finish reason, and token usage.
392        """
393        return await self._http.request(
394            "/api/v1/ai/chat/completions",
395            method="POST",
396            body=input,
397            response_type=AICompletionResult,
398        )
399
400    async def stream(self, input: CompletionStreamInput) -> AsyncIterator[CompletionStreamEvent]:
401        """
402        Stream a chat completion
403        Streams a chat completion over Server-Sent Events. Emits `message_delta`,
404        `message_complete`, `tool_call_*`, `tool_result`, and a terminal `done` (or
405        `error`) event. Same request shape as the non-streaming completion endpoint;
406        the app must have the `llm_calls` entitlement.
407
408        Args:
409            input: Request body.
410            input.context: Key-value map used to resolve template variables in message content. Omit if messages contain no templates.
411            input.messages: Ordered list of conversation messages to send to the model.
412            input.opts: Model and sampling configuration for this request.
413
414        Returns:
415            Server-Sent Events stream
416        """
417        async for event in self._http.stream_sse(
418            "/api/v1/ai/chat/completions/stream", method="POST", body=input
419        ):
420            yield event
421
422
423class AsyncChatResource:
424    def __init__(self, http: HttpClient):
425        self._http = http
426        self.completions = AsyncCompletionResource(http)
427
428    async def models(self) -> ChatModelsResponse:
429        """
430        List available AI models
431        Returns the set of AI models that can be used with the chat completion and
432        workflow endpoints. The list reflects models currently enabled for the
433        platform and includes each model's identifier and whether it is the default.
434        Use the `model` field from any entry in `data` as the value for
435        `opts.model` when calling the completions or workflows endpoint.
436
437        Returns:
438            Successful response
439        """
440        return await self._http.request("/api/v1/ai/chat/models", response_type=ChatModelsResponse)
441
442
443class AsyncImageResource:
444    def __init__(self, http: HttpClient):
445        self._http = http
446
447    async def edits(self, input: ImageEditsInput) -> AIImageResult:
448        """
449        Edit an image with a text prompt
450        Applies a text-guided edit to one or more source images and returns the
451        resulting image. Pass the source images as base64-encoded objects in the
452        `images` array alongside a `prompt` describing the desired modification.
453        The underlying provider is selected by the `model` parameter. Omit `model`
454        to use the platform default. Size, quality, style, and format options are
455        forwarded to the provider as-is; unsupported combinations for a given model
456        return a 422 error with the provider's error message.
457        This endpoint requires authentication. The request is billed against the
458        workspace associated with the authenticated user.
459
460        Args:
461            input: Request body.
462            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.
463            input.background: Background treatment for the output. Accepted values and behavior are model-dependent.
464            input.height: Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
465            input.image_size: Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.
466            input.images: One or more source images to edit. Each image must be supplied as a base64-encoded object.
467            input.model: Model identifier to use for editing. Omit to use the platform default image model.
468            input.output_format: Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model's native format.
469            input.prompt: Natural-language description of the edit to apply to the source image(s).
470            input.quality: Quality preset for the output image. Accepted values and behavior are model-dependent.
471            input.size: Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model's default.
472            input.style: Style preset applied to the edit. Accepted values and behavior are model-dependent.
473            input.width: Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
474
475        Returns:
476            The resulting edited image, including base64 data or a URL depending on the model.
477        """
478        return await self._http.request(
479            "/api/v1/ai/image/edits",
480            method="POST",
481            body=input,
482            response_type=AIImageResult,
483        )
484
485    async def generations(self, input: ImageGenerationsInput) -> AIImageResult:
486        """
487        Generate an image from a text prompt
488        Generates one or more images from a natural-language `prompt` using the
489        specified AI image model. The response contains the first generated image;
490        use `n` to request additional images (where supported by the model).
491        The underlying provider is selected by the `model` parameter. Omit `model`
492        to use the platform default. Size, quality, style, and format options are
493        forwarded to the provider as-is; unsupported combinations for a given model
494        return a 422 error with the provider's error message.
495        This endpoint requires authentication. The request is billed against the
496        workspace associated with the authenticated user.
497
498        Args:
499            input: Request body.
500            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.
501            input.background: Background treatment for the output. Accepted values and behavior are model-dependent.
502            input.height: Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
503            input.image_size: Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.
504            input.model: Model identifier to use for generation. Omit to use the platform default image model.
505            input.n: Number of images to generate. Defaults to `1`. Values greater than `1` are only supported by models that allow batch generation.
506            input.output_format: Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model's native format.
507            input.prompt: Natural-language description of the image to generate.
508            input.quality: Quality preset for the output image. Accepted values and behavior are model-dependent.
509            input.size: Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model's default.
510            input.style: Style preset applied to the generated image. Accepted values and behavior are model-dependent.
511            input.width: Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
512
513        Returns:
514            The generated image, including base64 data or a URL depending on the model.
515        """
516        return await self._http.request(
517            "/api/v1/ai/image/generations",
518            method="POST",
519            body=input,
520            response_type=AIImageResult,
521        )
522
523    async def models(self) -> ImageModelsResponse:
524        """
525        List available image generation models
526        Returns the list of image generation models available on the platform.
527        Exactly one entry in the list carries `default: true`, indicating the model
528        used when no `model` parameter is supplied to the generation or editing
529        endpoints.
530        This endpoint requires authentication and reflects the models enabled for
531        the authenticated user's workspace.
532
533        Returns:
534            Successful response
535        """
536        return await self._http.request(
537            "/api/v1/ai/image/models",
538            response_type=ImageModelsResponse,
539        )
540
541
542class AsyncAiResource:
543    def __init__(self, http: HttpClient):
544        self._http = http
545        self.chat = AsyncChatResource(http)
546        self.image = AsyncImageResource(http)
547
548
549class CompletionResource:
550    def __init__(self, http: SyncHttpClient):
551        self._http = http
552
553    def create(self, input: CompletionCreateInput) -> AICompletionResult:
554        """
555        Create a chat completion
556        Sends a list of messages to the configured AI provider and returns a single
557        completion. Use this endpoint when you want direct, low-level access to the
558        underlying model without any workflow or agent orchestration.
559        The authenticated app must have the `llm_calls` entitlement enabled on its
560        plan. Requests that exceed the plan quota are rejected with `402`. Token
561        usage is recorded against the authenticated app and organization.
562        Supply `tools` and `tool_choice` to enable OpenAI-compatible function
563        calling. Use `server_tools` to activate platform-managed tools such as
564        search that run on the server side before the response is returned.
565
566        Args:
567            input: Request body.
568            input.context: Key-value map used to resolve template variables in message content. Omit if messages contain no templates.
569            input.messages: Ordered list of conversation messages to send to the model.
570            input.opts: Model and sampling configuration for this request.
571
572        Returns:
573            The completed AI response, including the generated message, finish reason, and token usage.
574        """
575        return self._http.request(
576            "/api/v1/ai/chat/completions",
577            method="POST",
578            body=input,
579            response_type=AICompletionResult,
580        )
581
582    def stream(self, input: CompletionStreamInput) -> Iterator[CompletionStreamEvent]:
583        """
584        Stream a chat completion
585        Streams a chat completion over Server-Sent Events. Emits `message_delta`,
586        `message_complete`, `tool_call_*`, `tool_result`, and a terminal `done` (or
587        `error`) event. Same request shape as the non-streaming completion endpoint;
588        the app must have the `llm_calls` entitlement.
589
590        Args:
591            input: Request body.
592            input.context: Key-value map used to resolve template variables in message content. Omit if messages contain no templates.
593            input.messages: Ordered list of conversation messages to send to the model.
594            input.opts: Model and sampling configuration for this request.
595
596        Returns:
597            Server-Sent Events stream
598        """
599        yield from self._http.stream_sse_sync(
600            "/api/v1/ai/chat/completions/stream", method="POST", body=input
601        )
602
603
604class ChatResource:
605    def __init__(self, http: SyncHttpClient):
606        self._http = http
607        self.completions = CompletionResource(http)
608
609    def models(self) -> ChatModelsResponse:
610        """
611        List available AI models
612        Returns the set of AI models that can be used with the chat completion and
613        workflow endpoints. The list reflects models currently enabled for the
614        platform and includes each model's identifier and whether it is the default.
615        Use the `model` field from any entry in `data` as the value for
616        `opts.model` when calling the completions or workflows endpoint.
617
618        Returns:
619            Successful response
620        """
621        return self._http.request("/api/v1/ai/chat/models", response_type=ChatModelsResponse)
622
623
624class ImageResource:
625    def __init__(self, http: SyncHttpClient):
626        self._http = http
627
628    def edits(self, input: ImageEditsInput) -> AIImageResult:
629        """
630        Edit an image with a text prompt
631        Applies a text-guided edit to one or more source images and returns the
632        resulting image. Pass the source images as base64-encoded objects in the
633        `images` array alongside a `prompt` describing the desired modification.
634        The underlying provider is selected by the `model` parameter. Omit `model`
635        to use the platform default. Size, quality, style, and format options are
636        forwarded to the provider as-is; unsupported combinations for a given model
637        return a 422 error with the provider's error message.
638        This endpoint requires authentication. The request is billed against the
639        workspace associated with the authenticated user.
640
641        Args:
642            input: Request body.
643            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.
644            input.background: Background treatment for the output. Accepted values and behavior are model-dependent.
645            input.height: Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
646            input.image_size: Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.
647            input.images: One or more source images to edit. Each image must be supplied as a base64-encoded object.
648            input.model: Model identifier to use for editing. Omit to use the platform default image model.
649            input.output_format: Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model's native format.
650            input.prompt: Natural-language description of the edit to apply to the source image(s).
651            input.quality: Quality preset for the output image. Accepted values and behavior are model-dependent.
652            input.size: Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model's default.
653            input.style: Style preset applied to the edit. Accepted values and behavior are model-dependent.
654            input.width: Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
655
656        Returns:
657            The resulting edited image, including base64 data or a URL depending on the model.
658        """
659        return self._http.request(
660            "/api/v1/ai/image/edits",
661            method="POST",
662            body=input,
663            response_type=AIImageResult,
664        )
665
666    def generations(self, input: ImageGenerationsInput) -> AIImageResult:
667        """
668        Generate an image from a text prompt
669        Generates one or more images from a natural-language `prompt` using the
670        specified AI image model. The response contains the first generated image;
671        use `n` to request additional images (where supported by the model).
672        The underlying provider is selected by the `model` parameter. Omit `model`
673        to use the platform default. Size, quality, style, and format options are
674        forwarded to the provider as-is; unsupported combinations for a given model
675        return a 422 error with the provider's error message.
676        This endpoint requires authentication. The request is billed against the
677        workspace associated with the authenticated user.
678
679        Args:
680            input: Request body.
681            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.
682            input.background: Background treatment for the output. Accepted values and behavior are model-dependent.
683            input.height: Explicit output height in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
684            input.image_size: Output resolution tier for Gemini models, e.g. `"1K"`, `"2K"`, or `"4K"`. Ignored by non-Gemini models.
685            input.model: Model identifier to use for generation. Omit to use the platform default image model.
686            input.n: Number of images to generate. Defaults to `1`. Values greater than `1` are only supported by models that allow batch generation.
687            input.output_format: Desired MIME type or format for the returned image. Common values: `"png"`, `"jpeg"`, `"webp"`. Defaults to the model's native format.
688            input.prompt: Natural-language description of the image to generate.
689            input.quality: Quality preset for the output image. Accepted values and behavior are model-dependent.
690            input.size: Output dimensions as a WxH string, e.g. `"1024x1024"`. Applies to OpenAI-compatible models. Omit to use the model's default.
691            input.style: Style preset applied to the generated image. Accepted values and behavior are model-dependent.
692            input.width: Explicit output width in pixels. Takes precedence over `size` when both are provided. Not supported by all models.
693
694        Returns:
695            The generated image, including base64 data or a URL depending on the model.
696        """
697        return self._http.request(
698            "/api/v1/ai/image/generations",
699            method="POST",
700            body=input,
701            response_type=AIImageResult,
702        )
703
704    def models(self) -> ImageModelsResponse:
705        """
706        List available image generation models
707        Returns the list of image generation models available on the platform.
708        Exactly one entry in the list carries `default: true`, indicating the model
709        used when no `model` parameter is supplied to the generation or editing
710        endpoints.
711        This endpoint requires authentication and reflects the models enabled for
712        the authenticated user's workspace.
713
714        Returns:
715            Successful response
716        """
717        return self._http.request("/api/v1/ai/image/models", response_type=ImageModelsResponse)
718
719
720class AiResource:
721    def __init__(self, http: SyncHttpClient):
722        self._http = http
723        self.chat = ChatResource(http)
724        self.image = ImageResource(http)