simplismart-sdk 0.1.0

Python SDK scaffold for Simplismart API

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
• 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" \
  --org-id "$ORG_ID" \
  --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",
        org_id="<YOUR_ORG_UUID>",
        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}]}'

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

Python

from simplismart import DeploymentCreate, Simplismart

client = Simplismart()

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}]},
    )
)

print(resp)

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)

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

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

Exported request models:

• ModelRepoListParams
• ModelRepoCreate
• ModelRepoCompileCreate
• ModelRepoCompileAvatar
• ModelRepoProfilesRequest
• DeploymentCreate
• SecretCreate

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.