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