Deployments

Manage deployments using the Simplismart client methods below (e.g. client.create_deployment(...)).

`create_deployment`

Creates a deployment for a model repo.

Use env for model repo UUID and organization ID (e.g. ORG_ID); do not hardcode secrets.

The example below deploys a model on an H100 with 1 to 2 replicas that autoscale on GPU utilization (target 80%), with fast scale-up enabled.

import os
from dotenv import load_dotenv
load_dotenv()

from simplismart import DeploymentCreate, Simplismart

client = Simplismart()
deployment = client.create_deployment(
    DeploymentCreate(
        model_repo=os.getenv("MODEL_REPO_ID", "model-repo-uuid"),
        org=os.getenv("ORG_ID"),
        gpu_id="nvidia-h100",
        name="vision-private-deploy",
        min_pod_replicas=1,
        max_pod_replicas=2,
        autoscale_config={"targets": [{"metric": "gpu", "target": 80}]},
        env_variables={"KEY": "value"},
        healthcheck={"path": "/", "port": 8000},
        ports={"http": {"port": 8000}},
        metrics_path=["/v1/chat/completions"],
        fast_scaleup=True,
        deployment_tag="v1.0",
        auth_enabled=False,
        extra_details={"is_websocket_enabled": False},
    )
)

DeploymentCreate

Parameter	Type	Description	Required
`model_repo`	`str`	Model repository UUID	Yes
`org`	`str`	Organization UUID (`org_id`)	Yes
`gpu_id`	`str`	GPU type identifier. Examples: `nvidia-h100`, `nvidia-a10`, `nvidia-l4`	Yes
`name`	`str`	Deployment name (3-255 chars)	Yes
`min_pod_replicas`	`int`	Minimum pod replicas (≥ 0). When using `cronScaling`, set to `0` to scale to zero outside the window	Yes
`max_pod_replicas`	`int`	Maximum pod replicas (≥ 1)	Yes
`autoscale_config`	`AutoscaleConfig`	Autoscaling configuration. Required unless `min_pod_replicas` and `max_pod_replicas` are both `1`	Conditional
`env_variables`	`dict \| None`	Environment variables	No
`deployment_custom_configuration`	`dict \| None`	Custom deployment config	No
`healthcheck`	`dict \| None`	Health check configuration	No
`ports`	`dict \| None`	Port mappings	No
`metrics_path`	`list \| None`	Metrics paths	No
`persistent_volume_claims`	`dict \| list \| None`	PVC configurations	No
`fast_scaleup`	`bool \| None`	Enable fast scale up	No
`deployment_tag`	`str \| None`	Deployment tag label	No
`scale_to_zero_enabled`	`bool`	Traffic-based scale-to-zero (scales down on idle traffic). Default `false`	No
`async_deployment_type`	`str \| None`	One of `SYNC`, `ASYNC`	No
`auth_enabled`	`bool \| None`	Enable authentication on the deployment endpoint	No
`extra_details`	`dict \| None`	Extra container details, e.g. `{"is_websocket_enabled": False}`	No
`deployment_input_files`	`list \| None`	Input file mounts, e.g. `[{"name": "weights", "path": "/mnt/weights"}]`	No

A deployment scales using one of two approaches, and they cannot be combined:

Traffic-based (scale_to_zero_enabled=True): scales down when the deployment is idle.
Cron-based / schedule-based (cronScaling): runs on a fixed schedule. Set min_pod_replicas=0 if you also want it to scale to zero outside the scheduled window.

AutoscaleConfig

autoscale_config = {
    "targets": [
        {
            "metric": "gpu",      # Required
            "target": 80,          # Required (number)
            "percentile": 95      # Optional, only for latency metric
        }
    ]
}

Metric Option	Description
`concurrency`	Number of concurrent requests
`cpu`	CPU utilization percentage
`gpu`	GPU utilization percentage
`gram`	GPU memory utilization
`latency`	Request latency (supports percentiles 50, 75, 90, 95)
`ram`	RAM utilization
`throughput`	Requests per second

The percentile field is only supported when metric is set to latency.

These are the same scaling metrics you set when creating a deployment in the Model Suite. For what each metric measures and how thresholds trigger scaling, see Add Scaling Metrics.

Cron-based Scaling

Cron-based scaling (called schedule-based scaling on the Simplismart platform) runs your deployment on a fixed schedule. Use it when traffic is predictable: for example, keep the deployment up during weekday business hours and shut it down outside that window. Add a cronScaling config to autoscale_config, and set min_pod_replicas=0 if you want it to scale to zero outside the scheduled window.

deployment = client.create_deployment(
    DeploymentCreate(
        model_repo=os.getenv("MODEL_REPO_ID", "model-repo-uuid"),
        org=os.getenv("ORG_ID"),
        gpu_id="nvidia-h100",
        name="my-deployment-cron",
        min_pod_replicas=0,
        max_pod_replicas=2,
        autoscale_config={
            "targets": [{"metric": "gpu", "target": 80}],
            "cronScaling": [
                {"timezone": "UTC", "start": "0 9 * * 1,2,3,4,5", "end": "0 18 * * 1,2,3,4,5", "desiredReplicas": 2}
            ],
        },
    )
)

The schedule above runs 2 pods (desiredReplicas) on weekdays 9am to 6pm UTC, and because min_pod_replicas=0 it scales to zero outside that window.

CronScalingRule fields

Each entry in cronScaling is validated against this shape. Unknown keys are rejected.

Field	Type	Required	Description
`timezone`	`str`	Yes	IANA timezone, e.g. `UTC`
`start`	`str`	Yes	Cron expression for when the active window starts
`end`	`str`	Yes	Cron expression for when the active window ends
`desiredReplicas`	`int`	No	Replicas to run inside the window (default `1`, minimum `1`)

`list_deployments`

Lists deployments with optional filtering.

import os
from dotenv import load_dotenv
load_dotenv()

from simplismart import Simplismart

client = Simplismart()
deployments = client.list_deployments(
    model_repo_id=os.getenv("MODEL_REPO_ID"),  # Optional
    status="DEPLOYED",
    offset=0,
    count=20,
)
print(deployments)

Expected output — list of deployment summary objects:

[
  {
    "deployment_id": "deployment-uuid",
    "deployment_name": "speechbrain-v3",
    "model_repo_id": "model-repo-uuid",
    "model_repo_name": "speechbrain",
    "model_type": "unknown",
    "accelerator_type": ["nvidia-l40s"],
    "accelerator_count": 1,
    "status": "DEPLOYED"
  }
]

Deployment Status Options

Value	Description
`DEPLOYED`	Deployment is running
`PENDING`	Deployment is being created
`FAILED`	Deployment failed
`STOPPED`	Deployment is stopped
`DELETED`	Deployment has been deleted

`list_model_deployments`

Lists all model deployments for an organization.

deployments = client.list_model_deployments(org_id="org-uuid")

`get_model_deployment`

Gets deployment details by ID. Set DEPLOYMENT_ID in env or use an id from list_deployments.

deployment = client.get_model_deployment(deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"))

print(deployment)

Expected output — deployment object with uuid, name, status, model_repo, org, autoscale_config, healthcheck, ports, min_pod_replicas, max_pod_replicas, etc.

`get_deployment`

Get deployment details by ID.

deployment = client.get_deployment(deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"))

`update_deployment`

Updates deployment configuration.

updated = client.update_deployment(
    deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"),
    payload={
        "min_pod_replicas": 1,
        "max_pod_replicas": 2,
        "autoscale_config": {"targets": [{"metric": "gpu", "target": 80}]},
    },
)

`stop_deployment`

Stops a running deployment.

result = client.stop_deployment(deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"))

`start_deployment`

Starts a stopped deployment.

result = client.start_deployment(deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"))

`restart_deployment`

Restarts a deployment.

result = client.restart_deployment(
    deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"),
)

`fetch_deployment_health`

Gets deployment health status.

health = client.fetch_deployment_health(deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"))

print(health)

Expected output

{
  "data": "Healthy",
  "messages": [
    {
      "message": "Ready to use, the model is running and available for inference.",
      "severity": "info"
    }
  ],
  "pods": { "ready": 1, "not_ready": 0 }
}

`update_deployment_autoscaling`

Updates the autoscaling configuration of a live deployment.

cronScaling, targets, scaleDownBehavior, and scaleUpBehavior are top-level fields here — unlike create_private_deployment / update_deployment, where they nest inside autoscale_config. Two rules are enforced client-side before the request, so you get a clear ValueError instead of a backend 400:

min_replicas=0 is only allowed together with cron_scaling.
scale_to_zero and cron_scaling cannot both be set.

Parameter	Type	Description	Required
`deployment_id`	`str`	Deployment UUID	Yes
`min_replicas`	`int`	Minimum replicas (≥ 0). `0` requires `cron_scaling`	Yes
`max_replicas`	`int`	Maximum replicas (≥ 1, ≥ `min_replicas`)	Yes
`scale_to_zero`	`bool`	Traffic-based scale-to-zero. Cannot combine with `cron_scaling`	No
`cron_scaling`	`list[CronScalingRule]`	Schedule-based scaling windows	No
`cooldown_period`	`int`	KEDA cooldown (seconds)	No
`initial_cooldown_period`	`int`	KEDA initial cooldown (seconds)	No
`targets`	`list[AutoscaleTarget]`	KEDA metric targets (`metric`, `target`, optional `percentile`)	No
`scale_up_behavior`	`HPAScalingBehavior`	HPA scale-up behavior	No
`scale_down_behavior`	`HPAScalingBehavior`	HPA scale-down behavior	No

# Plain min/max replicas
client.update_deployment_autoscaling(
    deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"),
    min_replicas=1,
    max_replicas=3,
)

# Traffic-based scale-to-zero with a cooldown
client.update_deployment_autoscaling(
    deployment_id="<DEPLOYMENT_ID>",
    min_replicas=1, max_replicas=3,
    scale_to_zero=True, cooldown_period=30,
)

from simplismart import (
    AutoscaleTarget,
    CronScalingRule,
    HPAScalingBehavior,
    Simplismart,
)

client = Simplismart()

# Cron window — min_replicas=0, run only weekdays 8am–6pm UTC
client.update_deployment_autoscaling(
    deployment_id="<DEPLOYMENT_ID>",
    min_replicas=0, max_replicas=2,
    cron_scaling=[
        CronScalingRule(timezone="UTC", start="0 8 * * 1-5", end="0 18 * * 1-5", desiredReplicas=1)
    ],
)

# Metric targets + both HPA behaviors
# Scale on p95 latency; ramp up fast (4 pods / 15s), scale down gently (25% / 60s).
client.update_deployment_autoscaling(
    deployment_id="<DEPLOYMENT_ID>",
    min_replicas=1, max_replicas=8,
    targets=[AutoscaleTarget(metric="latency", target=200, percentile=95)],
    scale_up_behavior=HPAScalingBehavior(
        stabilizationWindowSeconds=0,
        selectPolicy="Max",
        policies=[{"type": "Pods", "value": 4, "periodSeconds": 15}],
    ),
    scale_down_behavior=HPAScalingBehavior(
        stabilizationWindowSeconds=300,
        selectPolicy="Min",
        policies=[{"type": "Percent", "value": 25, "periodSeconds": 60}],
    ),
)

AutoscaleTarget and HPAScalingBehavior / HPAScalingPolicy validate locally before the request: percentile is only valid for the latency metric and must be one of 50, 75, 90, 95; HPA policy type is Pods or Percent, value must be a positive integer (≤ 100 for Percent), periodSeconds ∈ [1, 1800], and stabilizationWindowSeconds ∈ [0, 3600].

`delete_deployment`

Deletes a deployment.

result = client.delete_deployment(
    deployment_id=os.getenv("DEPLOYMENT_ID", "deployment-uuid"),
)

Error Handling

The SDK raises SimplismartError for all API errors.

from simplismart import Simplismart, SimplismartError

client = Simplismart()
try:
    deployment = client.get_deployment(deployment_id="00000000-0000-0000-0000-000000000000")
except SimplismartError as e:
    print("Status:", e.status_code)
    print("Message:", e)
    print("Payload:", e.payload)

Expected output (for invalid or missing deployment):

Caught SimplismartError:
  status_code: 404
  message: No ModelDeployment matches the given query. (status=404)
  payload: {'detail': 'No ModelDeployment matches the given query.'}

SimplismartError Attributes

Attribute	Type	Description
`status_code`	`int`	HTTP status code
`payload`	`dict`	Full error response payload
`message`	`str`	Error message from backend

BYOC Deployment

Create a BYOC deployment with a payload (cluster, nodegroup, etc.). See Bring your own compute and Deploy on imported cluster. create_byoc_deployment takes a raw dict (no typed model). BYOC scheduling fields such as nodegroups and cluster are intentionally not part of DeploymentCreate.

from simplismart import Simplismart

client = Simplismart()

resp = client.create_byoc_deployment({
    "model_repo": "<MODEL_REPO_ID>",
    "org": "<YOUR_ORG_UUID>",
    "name": "my-byoc-deploy",
    "min_pod_replicas": 1,
    "max_pod_replicas": 1,
    "nodegroups": ["<NODEGROUP_ID>"],
})

print(resp)

Python SDK Reference

CLI Reference

`create_deployment`

DeploymentCreate

AutoscaleConfig

Cron-based Scaling

CronScalingRule fields

`list_deployments`

Deployment Status Options

`list_model_deployments`

`get_model_deployment`

`get_deployment`

`update_deployment`

`stop_deployment`

`start_deployment`

`restart_deployment`

`fetch_deployment_health`

`update_deployment_autoscaling`

`delete_deployment`

Error Handling

SimplismartError Attributes

BYOC Deployment

​create_deployment

​DeploymentCreate

​AutoscaleConfig

​Cron-based Scaling

CronScalingRule fields

​list_deployments

​Deployment Status Options

​list_model_deployments

​get_model_deployment

​get_deployment

​update_deployment

​stop_deployment

​start_deployment

​restart_deployment

​fetch_deployment_health

​update_deployment_autoscaling

​delete_deployment

​Error Handling

​SimplismartError Attributes

​BYOC Deployment

`create_deployment`

DeploymentCreate

AutoscaleConfig

Cron-based Scaling

`list_deployments`

Deployment Status Options

`list_model_deployments`

`get_model_deployment`

`get_deployment`

`update_deployment`

`stop_deployment`

`start_deployment`

`restart_deployment`

`fetch_deployment_health`

`update_deployment_autoscaling`

`delete_deployment`

Error Handling

SimplismartError Attributes

BYOC Deployment