Simplismart Python SDK

Official Python SDK and CLI for the Simplismart MLOps platform. Deploy and manage AI/ML models and containers with an idiomatic Python client and a full-featured CLI.

Features

• Model repos - List, create (Bring Your Own Container), create private compile jobs, get, profile lookup, delete
• Deployments - Create private or BYOC deployments; list, update, start, stop, scale, delete; health checks and autoscaling
• Secrets - Create and manage registry credentials (e.g. Docker Hub) for secure image pulls
• Usage analytics - Query cost and usage data per plan type, with optional filtering by deployment / training job / model repo
• CLI - Same capabilities from the terminal with simplismart for scripts and CI/CD

Requirements

• Python 3.9+
• A Simplismart Playground token (PG token) and organization ID

Installation

pip install simplismart-sdk

Authentication

export SIMPLISMART_PG_TOKEN="<YOUR_PG_TOKEN>"
export ORG_ID="<YOUR_ORG_UUID>"

# Optional
export SIMPLISMART_BASE_URL="https://api.app.simplismart.ai"
export SIMPLISMART_TIMEOUT="300"

Configuration Reference

Variable	Required	Default	Description
SIMPLISMART_PG_TOKEN	Yes*	-	Playground API token
ORG_ID	Recommended	-	Organization UUID used in create/list examples
SIMPLISMART_BASE_URL	No	https://api.app.simplismart.ai	API base URL
SIMPLISMART_TIMEOUT	No	300	Optional request timeout in seconds
SIMPLISMART_TRACE_ID	No	(none)	Default trace ID value; if unset, SDK auto-generates one per request

* Required unless passed in constructor (Simplismart(pg_token=...)).

Quick Start (Python)

from simplismart import ModelRepoListParams, Simplismart

client = Simplismart()  # uses SIMPLISMART_PG_TOKEN from environment

repos = client.list_model_repos(
    ModelRepoListParams(
        org_id="<YOUR_ORG_UUID>",
        offset=0,
        count=5,
    )
)

print(repos)

Explicit Client Constructor

Use explicit parameters instead of environment variables when needed. Trace IDs are set per request. If you don't pass trace_id, the SDK auto-generates one.

from simplismart import Simplismart

client = Simplismart(
    pg_token="<YOUR_PG_TOKEN>",
    base_url="https://api.app.simplismart.ai",  # optional
    timeout=300,                                  # optional
)

Tracing (Trace ID)

Every request sends an X-Trace-Id header.

• Python: pass trace_id=... on the SDK method call.
• CLI: pass --trace-id ... once per CLI invocation.
• Optional: set SIMPLISMART_TRACE_ID to define a default trace ID when you don't pass trace_id.
• If omitted, the SDK generates a new trace ID per request.

repo = client.get_model_repo(model_id="<MODEL_REPO_ID>", trace_id="my-correlation-id")
print(repo)

simplismart --trace-id my-correlation-id model-repos get --model-id "<MODEL_REPO_ID>"

Model Repositories

List and Get

CLI

# List
simplismart model-repos list --org-id "$ORG_ID" --offset 0 --count 5

# Print only model repo IDs
simplismart model-repos list --org-id "$ORG_ID" | jq -r '.results[].uuid'
# Note: `jq` is optional. If you don't have it installed, remove the pipe and inspect the JSON output.

# Get one model repo
simplismart model-repos get --model-id "<MODEL_REPO_ID>"

# Model profiles
simplismart model-repos profiles --type hf --path "meta-llama/Llama-3.2-1B-Instruct"
# Optional: pass a secret if the source requires it
simplismart model-repos profiles --type hf --path "meta-llama/Llama-3.2-1B-Instruct" --secret-id "<SECRET_ID>"

Python

from simplismart import ModelRepoListParams, Simplismart

client = Simplismart()

data = client.list_model_repos(ModelRepoListParams(org_id="<YOUR_ORG_UUID>", count=5))
print(data)

one = client.get_model_repo(model_id="<MODEL_REPO_ID>")
print(one)

Create Container (Bring Your Own Container)

Use this flow when you already have an image in a supported registry.

CLI

simplismart model-repos create-container \
  --name "byom-1" \
  --source-type "docker_hub" \
  --source-secret "<SECRET_ID>" \
  --registry-path "my-org/my-image" \
  --docker-tag "latest" \
  --runtime-gpus 0

Python

from simplismart import ModelRepoCreate, Simplismart

client = Simplismart()

resp = client.create_model_repo(
    ModelRepoCreate(
        name="byom-1",
        source_type="docker_hub",
        source_secret="<SECRET_ID>",
        registry_path="my-org/my-image",
        docker_tag="latest",
        runtime_gpus=0,
    )
)

print(resp)

Create Private Compile Model Repo

Use this flow when Simplismart should compile/optimize and package the model.

Notes:

• This method always sends use_simplismart_infrastructure=true.
• org is optional in payload for compile flow because backend can infer it from PG token.
• You should pass full JSON for model_config, optimisation_config, and pipeline_config.

CLI

simplismart model-repos create-private-compile \
  --name "llama-model" \
  --description "llama-model - A model deployed using Simplismart" \
  --avatar-url "https://ui-avatars.com/api/?background=f3f3f3&color=000000&name=llama-model" \
  --source-type "huggingface" \
  --source-url "meta-llama/Llama-3.2-1B-Instruct" \
  --model-class "LlamaForCausalLM" \
  --accelerator-type "nvidia-h100" \
  --accelerator-count 0 \
  --cloud-account "<CLOUD_ACCOUNT_UUID>" \
  --model-config '{"architectures":["LlamaForCausalLM"],"model_type":"llama","hidden_size":2048}' \
  --optimisation-config '{"model_type":"llm","quantization":"float16","tensor_parallel_size":2}' \
  --pipeline-config '{"type":"llm","mode":"chat","extra_params":{}}'

You can also pass JSON via files using the @path.json form:

simplismart model-repos create-private-compile \
  --name "llama-model" \
  --avatar-url "https://ui-avatars.com/api/?background=f3f3f3&color=000000&name=llama-model" \
  --source-type "huggingface" \
  --source-url "meta-llama/Llama-3.2-1B-Instruct" \
  --model-class "LlamaForCausalLM" \
  --accelerator-type "nvidia-h100" \
  --cloud-account "<CLOUD_ACCOUNT_UUID>" \
  --model-config @model_config.json \
  --optimisation-config @optimisation_config.json \
  --pipeline-config @pipeline_config.json

Python

from simplismart import (
    ModelRepoCompileAvatar,
    ModelRepoCompileCreate,
    Simplismart,
)

client = Simplismart()

resp = client.create_model_repo_private_compile(
    ModelRepoCompileCreate(
        name="llama-model",
        description="llama-model - A model deployed using Simplismart",
        avatar=ModelRepoCompileAvatar(
            image_url="https://ui-avatars.com/api/?background=f3f3f3&color=000000&name=llama-model"
        ),
        source_type="huggingface",
        source_url="meta-llama/Llama-3.2-1B-Instruct",
        model_class="LlamaForCausalLM",
        accelerator_type="nvidia-h100",
        accelerator_count=0,
        cloud_account="<CLOUD_ACCOUNT_UUID>",
        model_config_data={
            "architectures": ["LlamaForCausalLM"],
            "model_type": "llama",
            "hidden_size": 2048,
        },
        optimisation_config={
            "model_type": "llm",
            "quantization": "float16",
            "tensor_parallel_size": 2,
        },
        pipeline_config={
            "type": "llm",
            "mode": "chat",
            "extra_params": {},
        },
    )
)

print(resp)

Delete

simplismart model-repos delete --model-id "<MODEL_REPO_ID>"

Deployments

Create Private Deployment

CLI

simplismart deployments create-private --model-repo <MODEL_REPO_ID> --org "$ORG_ID" \
  --gpu-id nvidia-h100 --name my-deploy --min-pod-replicas 1 --max-pod-replicas 2 \
  --autoscale-config '{"targets":[{"metric":"gpu","target":80}]}' \
  --fast-scaleup \
  --async-deployment-type ASYNC \
  --auth-enabled

# Cron scale-to-zero (min-pod-replicas=0, pods stop outside the cron window)
simplismart deployments create-private --model-repo <MODEL_REPO_ID> --org "$ORG_ID" \
  --gpu-id nvidia-h100 --name my-deploy --min-pod-replicas 0 --max-pod-replicas 2 \
  --autoscale-config '{"targets":[{"metric":"gpu","target":80}],"cronScaling":[{"timezone":"UTC","start":"0 8 * * 1-5","end":"0 18 * * 1-5","desiredReplicas":1}]}'

# Update (payload from file)
simplismart deployments update --deployment-id <DEPLOYMENT_ID> --payload @edit-payload.json

Python

from simplismart import DeploymentCreate, Simplismart

client = Simplismart()

# Metric-based autoscaling
resp = client.create_private_deployment(
    DeploymentCreate(
        model_repo="<MODEL_REPO_ID>",
        org="<YOUR_ORG_UUID>",
        gpu_id="nvidia-h100",
        name="my-deployment",
        min_pod_replicas=1,
        max_pod_replicas=2,
        autoscale_config={"targets": [{"metric": "gpu", "target": 80}]},
        # Scaling knobs
        fast_scaleup=True,
        async_deployment_type="ASYNC",  # "SYNC" or "ASYNC"
        # Container config
        auth_enabled=False,
        extra_details={"is_websocket_enabled": False},
        deployment_input_files=[{"name": "weights", "path": "/mnt/weights"}],
    )
)

# Cron-based scale-to-zero (weekdays 8am–6pm UTC, off overnight)
resp = client.create_private_deployment(
    DeploymentCreate(
        model_repo="<MODEL_REPO_ID>",
        org="<YOUR_ORG_UUID>",
        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 8 * * 1-5", "end": "0 18 * * 1-5", "desiredReplicas": 1}
            ],
        },
    )
)

print(resp)

BYOM sidecars

Attach up to 3 egress-only sidecar containers to a BYOM private deployment via DeploymentCreate.sidecars. Each sidecar references a BYOM model_repo and optional runtime config (env_variables, healthcheck, command, resources). Use secrets to bind env vars from an org Secret ({"secret": "<uuid>", "key": "ENV_NAME"}) and privileged_access=True when the sidecar needs NET_ADMIN (e.g. a VPN client).

from simplismart import DeploymentCreate, SidecarCreate, Simplismart

client = Simplismart()

resp = client.create_private_deployment(
    DeploymentCreate(
        model_repo="<MAIN_BYOM_MODEL_REPO_ID>",
        org="<YOUR_ORG_UUID>",
        gpu_id="nvidia-h100",
        name="byom-with-sidecar",
        min_pod_replicas=1,
        max_pod_replicas=1,
        sidecars=[
            SidecarCreate(
                model_repo="<SIDECAR_BYOM_MODEL_REPO_ID>",
                env_variables={"QUEUE_URL": "https://example.com/queue"},
                resources={"requests": {"cpu": "250m", "memory": "512Mi"}},
            )
        ],
    )
)

CLI: pass --sidecars as a JSON array (or @file.json) on deployments create-private.

Create BYOC Deployment

CLI

simplismart deployments create-byoc --payload '{
  "model_repo": "<MODEL_REPO_ID>",
  "org": "<YOUR_ORG_UUID>",
  "name": "my-byoc-deploy",
  "min_pod_replicas": 1,
  "max_pod_replicas": 1,
  "nodegroups": ["<NODEGROUP_ID>"]
}'

# Or from a file
simplismart deployments create-byoc --payload @byoc-payload.json

Python

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)

---

Update Autoscaling

Updates the autoscaling configuration of an existing deployment.

Note: cronScaling, targets, scaleDownBehavior, and scaleUpBehavior are all top-level fields here (unlike create/edit, where they nest inside autoscale_config). Two rules apply, validated client-side before the request: min_replicas=0 is only allowed with a cron window, and scale_to_zero cannot be combined with cron_scaling. AutoscaleTarget and HPAScalingBehavior/HPAScalingPolicy validate the metric/percentile and HPA policy rules locally (e.g. Percent value ≤ 100, periodSeconds ∈ [1, 1800]) so you get a clear error instead of a backend 400.

CLI

# Plain min/max replicas
simplismart deployments scale --deployment-id "<DEPLOYMENT_ID>" --min-replicas 1 --max-replicas 3

# Scale to zero with a cooldown (no cron window)
simplismart deployments scale --deployment-id "<DEPLOYMENT_ID>" \
  --min-replicas 1 --max-replicas 3 --scale-to-zero --cooldown-period 30

# Cron window — min-replicas=0, pods run only weekdays 8am-6pm UTC
simplismart deployments scale --deployment-id "<DEPLOYMENT_ID>" \
  --min-replicas 0 --max-replicas 2 \
  --cron-scaling '[{"timezone":"UTC","start":"0 8 * * 1-5","end":"0 18 * * 1-5","desiredReplicas":1}]'

# Latency-based metric target
simplismart deployments scale --deployment-id "<DEPLOYMENT_ID>" \
  --min-replicas 1 --max-replicas 8 \
  --targets '[{"metric":"latency","target":200,"percentile":95}]'

# Both HPA behaviors — ramp up fast (4 pods / 15s), scale down gently (25% / 60s)
simplismart deployments scale --deployment-id "<DEPLOYMENT_ID>" \
  --min-replicas 1 --max-replicas 8 \
  --scale-up-behavior '{"stabilizationWindowSeconds":0,"selectPolicy":"Max","policies":[{"type":"Pods","value":4,"periodSeconds":15}]}' \
  --scale-down-behavior '{"stabilizationWindowSeconds":300,"selectPolicy":"Min","policies":[{"type":"Percent","value":25,"periodSeconds":60}]}'

# Behaviors can also be read from a file with @ (handy for large JSON)
simplismart deployments scale --deployment-id "<DEPLOYMENT_ID>" \
  --min-replicas 1 --max-replicas 8 --scale-up-behavior @scale_up.json

Python

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

client = Simplismart()

# Plain min/max replicas
client.update_deployment_autoscaling(
    deployment_id="<DEPLOYMENT_ID>", min_replicas=1, max_replicas=3
)

# 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,
)

# Cron window — min_replicas=0, scale up 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}],
    ),
)

---

Common Deployment Commands

simplismart deployments list --offset 0 --count 20
simplismart deployments get --deployment-id "<DEPLOYMENT_ID>"
simplismart deployments stop --deployment-id "<DEPLOYMENT_ID>"
simplismart deployments start --deployment-id "<DEPLOYMENT_ID>"
simplismart deployments scale --deployment-id "<DEPLOYMENT_ID>" --min-replicas 1 --max-replicas 3
simplismart deployments delete --deployment-id "<DEPLOYMENT_ID>"

Secrets

Create, List, Get

CLI

simplismart secrets create \
  --org-id "$ORG_ID" \
  --name "dockerhub-secret" \
  --secret-type "docker_hub" \
  --data '{"username":"my-user","token":"my-token"}'

simplismart secrets list --org-id "$ORG_ID"
simplismart secrets get --secret-id "<SECRET_ID>"

# Secret config schema from PG token context
simplismart secrets config

Python

from simplismart import SecretCreate, Simplismart

client = Simplismart()

resp = client.create_secret(
    SecretCreate(
        org="<YOUR_ORG_UUID>",
        name="dockerhub-secret",
        secret_type="docker_hub",
        data={"username": "my-user", "token": "my-token"},
    )
)

print(resp)

Usage Analytics

Query cost and usage data for the org behind your PG token. Supports six plan types and optional filtering by deployment, training job, or model repo.

Fetch usage stats

CLI

simplismart usage stats \
  --plan-type private \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY

# Multiple deployments by slug — pass a comma-separated list
simplismart usage stats \
  --plan-type private \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --deployment-slug my-deploy,another-deploy,yet-another

# Multiple deployments by id (plan-type ∈ private/byoc/reserved)
simplismart usage stats \
  --plan-type private \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --deployment-id 54360212-2263-44c6-afaf-133354485487,9a8b6c54-7f3e-41a9-9b22-5e7e0bce9f12

# Combine deployment ids and slugs in one call — results are the union
simplismart usage stats \
  --plan-type private \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --deployment-id   54360212-2263-44c6-afaf-133354485487,9a8b6c54-7f3e-41a9-9b22-5e7e0bce9f12 \
  --deployment-slug my-deploy,another-deploy

# Shared plan filters by model name only (no ids/slugs).
# Shared usage events expose only the model name (e.g. "DeepSeek-R1"),
# not a per-org deployment id, so use --model-name.
simplismart usage stats \
  --plan-type shared \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --model-name DeepSeek-R1,Llama-3

# Training jobs by name (plan-type=training only)
simplismart usage stats \
  --plan-type training \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --training-job-name finetune-llama-3,finetune-mistral-7b

# Combine training-job ids and names in one call — results are the union
simplismart usage stats \
  --plan-type training \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --training-job-id   a1f2c3d4-5678-90ab-cdef-1234567890ab \
  --training-job-name finetune-llama-3,finetune-mistral-7b

# Compiled model repos by id (plan-type=compilation only)
simplismart usage stats \
  --plan-type compilation \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --model-repo-id 54360212-2263-44c6-afaf-133354485487,9a8b6c54-7f3e-41a9-9b22-5e7e0bce9f12

# Combine model-repo ids and names in one call — results are the union
simplismart usage stats \
  --plan-type compilation \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --model-repo-id   54360212-2263-44c6-afaf-133354485487 \
  --model-repo-name llama-3-8b-int4,mistral-7b-int8

# Reserved plan + --group-by accelerator automatically gets you the pooled
# reservation commitment breakdown: total_cost becomes the real
# commitment-adjusted account total, and the response gains
# reservation_commitment (per-GPU-type daily overage/true-up). No flag
# needed, and --plan-type private works the same - see "Grouping" below for
# why --group-by deployment never gets it.
simplismart usage stats \
  --plan-type reserved \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --group-by accelerator

How filters work:

• Each filter flag takes a single value or a comma-separated list (a,b,c). All values must be passed in one invocation.
• Passing the same flag twice (e.g. --deployment-slug a --deployment-slug b) is rejected with a CLI error — use --deployment-slug a,b instead.
• Pick whichever flag fits — id or slug/name. A single flag with N values is the typical case.
• Multiple values combine with OR (union). A record is included if it matches any of the supplied values.
• Filters only ever match records visible to your org for the given plan_type. Unknown values return a 400 listing exactly which entries didn't resolve.

Restricting by status:

Use --statuses to restrict results to exactly the given resource statuses. If omitted, no restriction is applied — every status is included by default.

Plan type	--statuses values	Default (flag omitted)
private / byoc / reserved / shared	Deployment statuses, e.g. DEPLOYED, STOPPED, DELETED, FAILED	Every status included
compilation	Model repo statuses, e.g. SUCCESS, FAILED	Every status included
training	Not applicable — always ignored	Always ignored

Important: When filtering by specific names or IDs, resources with any status are matched by default now. Pass --statuses to narrow that down if needed — a value that doesn't resolve returns a 400 listing what didn't match.

Reservation commitment breakdown (plan_type=reserved or private):

For plan_type="reserved" (and "private" with group_by="accelerator"), the response always accounts for continuity and, depending on how you group it, includes the full reservation commitment breakdown too — no flag needed:

• Continuity across a plan migration: if your org moved from a private plan to a reserved plan, usage from before that migration is included alongside your current reserved usage, so you get one continuous view instead of a gap at the migration date. "private" likewise includes usage from a reservation that has ended.
• Whenever the request is sourceless/pooled — group_by="accelerator", or group_by omitted entirely — the response additionally gets total_cost as the real, commitment-adjusted account total (what your org is actually billed under its reservation, not sum(items[].total_cost)), and a reservation_commitment field: one entry per GPU type, with is_reserved and a daily array of {timestamp, overage_amount, true_up_amount} — overage_amount is usage billed above the committed quantity (or with no commitment), true_up_amount is reserved capacity paid for but not used that window.
• A sourced/per-deployment request (group_by="deployment", or any deployment_ids/deployment_slugs filter) never gets this breakdown — overage/true-up cost is pooled across your whole account and is never attributable to a single deployment, so a pooled, account-wide breakdown next to a per-deployment cost list would be misleading. The model-suite dashboard itself never shows them together for exactly this reason: its per-deployment view never shows the breakdown at all, only the accelerator view does.
• None of the above applies to any other plan_type — this is specific to "reserved" and "private".

# Private plan, restricted to DEPLOYED/STOPPED deployments only
simplismart usage stats \
  --plan-type private \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --statuses DEPLOYED,STOPPED

# Shared plan + specific model
simplismart usage stats \
  --plan-type shared \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --model-name DeepSeek-R1

# Multiple deployments by ID
simplismart usage stats \
  --plan-type private \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY \
  --deployment-id uuid1,uuid2,uuid3

# Training plan (statuses filter is a no-op here)
simplismart usage stats \
  --plan-type training \
  --start-time 2025-02-04T00:00:00+00:00 \
  --end-time   2025-05-05T00:00:00+00:00 \
  --window-size DAY

# SDK Examples
from simplismart import Simplismart, UsageStatsParams

client = Simplismart()

# Basic usage - private plan
data = client.get_usage_stats(
    UsageStatsParams(
        plan_type="private",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
    )
)

# Restrict to specific statuses
data = client.get_usage_stats(
    UsageStatsParams(
        plan_type="private",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        statuses=["DEPLOYED", "STOPPED"],
    )
)

# Filter by specific deployments
data = client.get_usage_stats(
    UsageStatsParams(
        plan_type="private",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        deployment_ids=["uuid1", "uuid2"],
    )
)

# Reserved plan + group_by="accelerator" automatically gets the reservation
# commitment breakdown - no flag needed. See "Grouping" below for why
# group_by="deployment" never gets it.
data = client.get_usage_stats(
    UsageStatsParams(
        plan_type="reserved",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        group_by="accelerator",
    )
)
print(data["total_cost"])  # real, commitment-adjusted total
for entry in data.get("reservation_commitment", []):
    print(entry["name"], entry["is_reserved"], entry["daily"])

# Reserved plan, filtered to specific deployments - group_by can be omitted
# here too: deployment_ids/deployment_slugs auto-correct an omitted group_by
# to the per-deployment shape (no reservation_commitment either way).
data = client.get_usage_stats(
    UsageStatsParams(
        plan_type="reserved",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        deployment_ids=["uuid1", "uuid2"],
    )
)

Python

from simplismart import Simplismart, UsageStatsParams

client = Simplismart()

resp = client.get_usage_stats(
    UsageStatsParams(
        plan_type="private",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        deployment_slugs=["my-deploy", "another-deploy"],
    )
)

# Combine ids and slugs — results are the union
resp = client.get_usage_stats(
    UsageStatsParams(
        plan_type="private",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        deployment_ids=["54360212-2263-44c6-afaf-133354485487"],
        deployment_slugs=["my-deploy", "another-deploy"],
    )
)

# Training jobs — combine ids and names
resp = client.get_usage_stats(
    UsageStatsParams(
        plan_type="training",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        training_job_ids=["a1f2c3d4-5678-90ab-cdef-1234567890ab"],
        training_job_names=["finetune-llama-3"],
    )
)

# Compilation — combine model-repo ids and names
resp = client.get_usage_stats(
    UsageStatsParams(
        plan_type="compilation",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        model_repo_ids=["54360212-2263-44c6-afaf-133354485487"],
        model_repo_names=["llama-3-8b-int4"],
    )
)

# Shared — filter by model name only (plan-type=shared)
resp = client.get_usage_stats(
    UsageStatsParams(
        plan_type="shared",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        model_names=["DeepSeek-R1", "Llama-3"],
    )
)

print(resp["total_cost"])
for item in resp["items"]:
    print(item["source"], item["total_cost"])

UsageStatsParams validates filter scope before the request is sent — e.g. passing training_job_ids with plan_type="private" raises ValidationError. Filter values are auto-trimmed and de-duplicated.

Grouping — deployment vs accelerator:

Pass group_by="accelerator" for a pooled per-GPU/CPU-type breakdown instead of per-deployment — the same toggle as the dashboard's Group By dropdown. Only valid for plan_type in private/reserved (that dropdown only ever appears on the Private tab). Omit it (or pass "deployment", the default) for the usual per-deployment breakdown.

data = client.get_usage_stats(
    UsageStatsParams(
        plan_type="private",
        start_time="2025-02-04T00:00:00+00:00",
        end_time="2025-05-05T00:00:00+00:00",
        window_size="DAY",
        group_by="accelerator",
    )
)

For plan_type="reserved", omitting group_by defaults to "accelerator", not "deployment" - unless deployment_ids/deployment_slugs is set, in which case it defaults to "deployment" instead (the filter itself implies that intent). group_by="accelerator" (or an omitted group_by with no deployment filter) automatically gets you the reservation commitment breakdown — no flag needed. group_by="deployment" never gets it, since overage/true-up is pooled account-wide and can't be attributed to a single deployment.

deployment_ids/deployment_slugs can't be combined with an explicit group_by="accelerator" for plan_type="reserved" - that's the one genuine contradiction UsageStatsParams rejects (ValidationError). Omitting group_by alongside a deployment filter is fine and auto-corrects to "deployment".

This SDK authenticates via PG token and never sends sources directly — the backend auto-resolves them, but only when the request needs per-deployment grouping; group_by="accelerator" skips that resolution and queries account-wide instead.

Each point in items[] also carries computed_commitment_utilized_amount, computed_overage_amount, and computed_true_up_amount when group_by="accelerator" — they add up to the point's cost, with usage that has no commitment counted as overage. This is the only grouping where they're meaningful:

group_by	Use
"accelerator"	items[].points[].computed_overage_amount / computed_true_up_amount, per time bucket
"deployment"	Never carries these fields - use "accelerator" for that data instead

Continuity across a billing plan migration:

For plan_type in private/byoc/reserved/training, if a deployment's billing classification changes mid-window (e.g. a private→reserved migration converts its event name from 1-x-nvidia-h100 to nvidia-h100), the SDK combines that deployment's items back into a single entry — same source, summed total_cost/total_usage, and a merged points timeline — instead of surfacing it as two separate, seemingly-unrelated line items. This matches how the model-suite dashboard displays a migrated deployment as one continuous row.

CLI Reference

Global Options

Option	Description
--pg-token	Override SIMPLISMART_PG_TOKEN
--base-url	Override SIMPLISMART_BASE_URL
--timeout	Optional request timeout in seconds
--trace-id	Optional trace/correlation ID (auto-generated if omitted)

Command Groups

Group	Purpose
model-repos	List/get/create/delete model repositories
deployments	Create/update/list/manage deployments
secrets	Create/list/get secrets and list secret config schemas
usage	Fetch usage analytics; supports per-deployment / training-job / model-repo filters

Use:

simplismart <group> --help
simplismart <group> <command> --help

Python API Reference

Area	Methods
Model repos	list_model_repos, get_model_repo, create_model_repo, create_model_repo_private_compile, get_model_repo_profiles, delete_model_repo
Deployments	create_private_deployment, create_deployment (alias), list_deployments, list_model_deployments, create_byoc_deployment, get_model_deployment, get_deployment (alias), update_deployment, stop_deployment, start_deployment, restart_deployment, fetch_deployment_health, update_deployment_autoscaling, delete_deployment, delete_model_deployment (alias)
Secrets	create_secret, list_secrets, get_secret, list_secret_configs
Usage	get_usage_stats

Exported request models:

• ModelRepoListParams
• ModelRepoCreate
• ModelRepoCompileCreate
• ModelRepoCompileAvatar
• ModelRepoProfilesRequest
• DeploymentCreate
• SidecarCreate — one BYOM sidecar on DeploymentCreate.sidecars (max 3)
• SidecarSecretRef — {secret, key} env binding for a sidecar
• CronScalingRule — cron window for update_deployment_autoscaling / autoscale_config
• AutoscaleTarget — KEDA metric target (metric, target, optional percentile)
• HPAScalingBehavior — HPA scaleUpBehavior / scaleDownBehavior block
• HPAScalingPolicy — one policy inside an HPAScalingBehavior
• SecretCreate
• UsageStatsParams

Error Handling

The SDK raises SimplismartError for non-2xx responses.

from simplismart import Simplismart, SimplismartError

client = Simplismart()

try:
    client.get_model_repo("<MODEL_REPO_ID>")
except SimplismartError as exc:
    print(exc.message)
    print(exc.status_code)
    print(exc.payload)

CLI errors are printed as JSON.

Security Notes

• Do not hardcode tokens or cloud credentials in source code.
• Use environment variables or a secret manager in CI/CD.
• Rotate credentials immediately if exposed.

Troubleshooting

• Missing or invalid token: Ensure SIMPLISMART_PG_TOKEN is set (or pass pg_token to Simplismart(...)). Get your Playground token from the Simplismart dashboard.
• Wrong base URL: Use https://api.app.simplismart.ai (no trailing slash) unless you have a custom endpoint.
• 4xx/5xx errors: Check SimplismartError.status_code and SimplismartError.payload for details; refer to the API docs for required fields.

License

Proprietary. See your Simplismart agreement for terms.