client.deployments

Bases: SyncResource

Sync deployments namespace (client.deployments).

create

create(model_id: UUID | str) -> Deployment

Launch a model on the shared MME (202). Idempotent: an existing live deployment of the model is returned instead of a second one. The returned deployment is deploying (warming) — poll :meth:get until ready.

Raises:

Type	Description
NotFoundError	model not found (MODEL_NOT_FOUND).
RateLimitError	per-tenant concurrent-deployment cap reached (RESOURCE_LIMIT_EXCEEDED).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).
UnavailableError	the serving control plane failed to launch it (DEPENDENCY_UNAVAILABLE).

list

list(*, limit: int | None = None, cursor: str | None = None) -> Page[Deployment]

List the tenant's live (deploying/ready) deployments, newest first (cursor-paginated; iterate for all pages).

Raises:

Type	Description
BadRequestError	malformed cursor (INVALID_CURSOR).
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

get

get(deployment_id: UUID | str) -> Deployment

Fetch one deployment. capability is populated only once status is ready (null while deploying).

Raises:

Type	Description
NotFoundError	DEPLOYMENT_NOT_FOUND.
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

stop

stop(deployment_id: UUID | str) -> None

Stop a deployment (tears it down from the MME repo). Returns nothing (204) and is idempotent — a no-op on an unknown or already-terminal deployment (never raises NotFoundError).

Raises:

Type	Description
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

predict

predict(deployment_id: UUID | str, *, image_b64: str | None = None, image_url: str | None = None, confidence: float | None = None, iou: float | None = None, max_detections: int | None = None, classes: list[int] | None = None) -> PredictResponse

Run inference on one image (provide exactly one of image_b64 / image_url — for a platform asset, pass its presigned assets.download_url(...)). Omitted tuning params fall back to the model's recommended thresholds.

Parameters:

Name	Type	Description	Default
deployment_id	UUID | str	the deployment to run inference on.	required
image_b64	str | None	base64-encoded image bytes (give exactly one image source).	None
image_url	str | None	a fetchable image URL (give exactly one image source).	None
confidence	float | None	score threshold below which predictions are dropped; omit to use the model's recommended default.	None
iou	float | None	IoU threshold for non-max suppression (higher keeps more overlapping boxes); omit for the model default.	None
max_detections	int | None	maximum number of predictions to return; omit for the model default.	None
classes	list[int] | None	restrict output to these class ids.	None

Raises:

Type	Description
NotFoundError	DEPLOYMENT_NOT_FOUND.
ConflictError	the deployment is stopped/failed (DEPLOYMENT_STATE_FORBIDDEN).
UnavailableError	the model is still warming — code is MODEL_LOADING (retry ~15s) or MODEL_STARTING (retry ~60s); or inference failed (DEPENDENCY_UNAVAILABLE).
UnprocessableError	no image source given (VALIDATION_ERROR).
RateLimitError	inference bucket exhausted (RATE_LIMITED).

Response models

Models returned by client.deployments methods (fields, types, and what each means).

Inference deployment domain models (ADR-0067/0081).

A deployment is a workspace-admin-launched TrainedModel served on the shared Multi-Model Endpoint. It is a tenant-level operational resource (deploy any of the tenant's models, predict on any image). These are tolerant response readers (extra="allow"); enums + geometry come from common (never re-declared). Predict payloads are built as dicts in the resource — the server validates them.

DeploymentLabel

Bases: BaseModel

One class in the deployed model's class map (0-indexed).

ParamSpec

Bases: BaseModel

Bounds + default for a tunable predict parameter (from the train-time val sweep).

CapabilityDescriptor

Bases: BaseModel

Task-keyed contract the playground renders from — present once the deployment is ready (null while deploying).

Deployment

Bases: BaseModel

A model deployment on the shared MME. list/create return this with capability unset; get populates capability once status is ready.

Prediction

Bases: BaseModel

One model prediction. geometry is the same discriminated shape an annotation carries, so a prediction maps onto an annotation without translation.

ImageSize

Bases: BaseModel

Decoded image dimensions echoed on a predict response.

PredictResponse

Bases: BaseModel

Result of a single-image predict.