PyroMind SDK

Lightweight Python SDK for the PyroMind AI Platform API — manage training workflows, Jupyter instances, inference jobs, EchoMind and more.

Installation

pip install pyromind-sdk

Requires Python >= 3.8.

Quick Start

from pyromind_sdk import PyroMindAPIClient
from pyromind_sdk.client.models import TrainingTaskCreateRequest

client = PyroMindAPIClient(api_key="your-api-key")

# Create and run a studio task
task = client.studio.create(
    TrainingTaskCreateRequest(
        name="my-workflow",
        workflow={"nodes": [...]}
    )
)
print(f"Created task: {task.task_id}")

Docker CLI over Kubernetes (docker-rt)

pyromind_sdk.docker_rt is an embedded Docker Engine API facade: it listens on a Unix socket (or TCP), translates docker commands into Kubernetes Pod operations, and exposes KubeEnvironment as the SDK-side adapter.

pip install -e .

# start the daemon (Docker Desktop / any reachable cluster)
docker-rt
# underscore alias also works
# docker_rt
# same daemon, via the unified SDK CLI
# pyromind docker-rt

# SDK defaults: kube-context=docker-desktop, namespace=default,
# node-selector=disabled. Override any of them with DOCKER_RT_* env vars.

# background daemon
pyromind docker-rt --daemon
# pyromind docker-rt --daemon --log-file /tmp/docker-rt.log --pid-file /tmp/docker-rt.pid

# point the Docker CLI at it
docker-rt-context
# docker-rt backs up the current Docker context, switches to docker-rt, and
# on exit (including kill -9) a watcher restores the backup, then exits
# manual fallback if needed:
docker-rt-context --restore

docker version
docker run -d --name demo busybox:1.36 sleep 300
docker ps
docker exec demo echo hello

Docker CLI is required before starting docker-rt; if it is missing the daemon refuses to start. On Linux you can install the static binary:

curl -fsSL https://download.docker.com/linux/static/stable/x86_64/docker-27.5.1.tgz \
  | tar -xz -C /tmp
sudo mv /tmp/docker/docker /usr/local/bin/docker
chmod +x /usr/local/bin/docker

For other systems, see: https://docs.docker.com/desktop/

docker-rt checks the local ~/.pyromind/bin/docker wrapper at startup. If it is missing it asks to install it (or installs automatically in non-interactive shells), and it refreshes the wrapper when the SDK version changes. Declining the install stops docker-rt from starting. Run pyromind-docker-uninstall to remove the wrapper and its PATH entry.

pyromind docker-rt parameters

pyromind docker-rt \
  --daemon \
  --sock /tmp/docker-rt.sock \
  --log-file /tmp/docker-rt.log \
  --pid-file /tmp/docker-rt.pid

Use environment variables, or pass credentials directly:

export PYROMIND_API_KEY=XXXXXXXXX
export PYROMIND_BASE_URL=https://pre-api.pyromind.ai/api/v1
export PYROMIND_CLUSTER='us-west-1#pre'
pyromind docker-rt --daemon

# or
pyromind docker-rt --daemon --apikey XXXXXXXXX --cluster 'us-west-1#pre'

docker-rt environment variables

Env vars needed to push from the Shanghai cluster (cn-east-1)

Nodes there cannot reach index.docker.io (DNS is poisoned to unrelated company IPs and TCP 443 never connects — measured inside the sandbox: index.docker.io:443 dns=80.87.199.46 tcp=fail, while the cluster's own ACR does connect). So the push target has to be that ACR. Set these on the daemon — one per line — and restart docker-rt afterwards (they are read at startup):

DOCKER_RT_BUILD_REGISTRY=pyromind-registry-vpc.cn-shanghai.cr.aliyuncs.com/pyromind
DOCKER_RT_REGISTRY_USERNAME=<ACR username>
DOCKER_RT_REGISTRY_PASSWORD=<ACR password / temporary token>

⚠️ The prefix must carry a namespace (the trailing /pyromind above — any namespace you have rights on will do). An ACR path is <host>/<namespace>/<repo>; with the host alone ACR reads the repo name as a namespace, finds nothing, and answers the push with a bare 401 Unauthorized (after the whole build has run). The daemon refuses a host-only prefix before building.

The namespace always comes from the parameter — nothing is appended for you. The prefix in DOCKER_RT_BUILD_REGISTRY is used verbatim; if you leave it unset and let the cluster profile derive it, use DOCKER_RT_REGISTRY_NAMESPACE to pick the namespace instead.

(Credentials are either/or and neither is mandatory: the last two lines above give an account; or leave those out and point at a dockerconfig.json you are already logged in with —

DOCKER_RT_REGISTRY_DOCKERCONFIG=<path to that file>

— and if even that is unset, the default /etc/docker-image/.dockerconfigjson is used when it exists. Precedence: DOCKER_RT_REGISTRY_USERNAME + _PASSWORD (both nonempty) > explicit dockerconfig > the default file.)

Archive only, do not push:

DOCKER_RT_BUILD_PUSH=false

Skip this reachability check and build anyway:

DOCKER_RT_BUILD_PUSH_CHECK=warn

Without these the build is stopped before it starts (DOCKER_RT_BUILD_PUSH_CHECK defaults to fail), and the error prints exactly the lines above.

There is also a separate group: when the ACR repository does not exist yet, these let the daemon pre-create it before the build. The names are spelled out in full — do not abbreviate them:

DOCKER_RT_ACR_ACCESS_KEY_ID=<AccessKey ID>
DOCKER_RT_ACR_ACCESS_KEY_SECRET=<AccessKey Secret>
DOCKER_RT_ACR_INSTANCE_ID=cri-xxxxxxxxxxxx

⚠️ DOCKER_RT_ACR_SECRET does not exist (the real name is DOCKER_RT_ACR_ACCESS_KEY_SECRET). A misspelled variable is silently ignored — the pre-creation step is skipped, and ACR answers a push to a nonexistent repository with 401 UNAUTHORIZED: authentication required too, which is easy to misread as a credential problem. Skip this group if the repository was created by hand.

Repository names are normalized automatically. ACR's rules are stricter than the general Docker ones (length 2–120, only lowercase letters/digits and _ - . /, no separator at either end and no two in a row), so the name is normalized when the build composes the push ref (__→_, …) and the same function runs on docker create/run, so the original name still resolves. Only applies to this cluster's ACR — Docker Hub and generic registries are left untouched.

DOCKER_RT_READY_TIMEOUT / --ready-timeout controls the docker-rt server's sandbox readiness wait. It does not change the Docker client's HTTP timeout. Python clients must create the Docker client with a suitable timeout, for example docker.from_env(timeout=600).

For the default k8s-middleware backend, docker-rt checks PYROMIND_API_KEY and PYROMIND_CLUSTER; missing values are prompted one by one. After a successful connection it prints the active parameters in color and syncs the sandbox list once during startup.

Supported Docker commands

docker inspect output

Default DOCKER_RT_INSPECT_MODE=standard, which keeps the standard Docker inspect fields used by the Python Docker SDK:

{
  "Id": "sb-94d290262ee8",
  "Name": "/test-for-doc",
  "State": {"Status": "Stopped"}
}

Set DOCKER_RT_INSPECT_MODE=sandbox to return only the compact sandbox fields:

{
  "id": "sb-94d290262ee8",
  "name": "test-for-doc",
  "type": "custom",
  "status": "Stopped",
  "configuration": {},
  "resources": {},
  "created_at": "",
  "updated_at": "",
  "image": "",
  "volume_mounts": [],
  "port_mappings": []
}

GPU card via Docker flags

docker run --gpus passes the GPU count. To specify the GPU card model without setting DOCKER_RT_GPU_CARD, use the docker-rt.gpu-card label:

docker create \
  --name gpu-demo \
  --cpus 4 \
  --memory 8g \
  --gpus 1 \
  --label docker-rt.gpu-card=L40S \
  swebench/swesmith.x86_64.oauthlib_1776_oauthlib.1fd52536

To use the shorter --gpu-card L40S syntax, run pyromind docker-rt once. Every pyromind docker-rt run asks for confirmation, installs ~/.pyromind/bin/docker, and adds it to your shell PATH. Declining the prompt still starts docker-rt, but --gpu-card shorthand is unavailable; use --label docker-rt.gpu-card=L40S or DOCKER_RT_GPU_CARD instead. You can also install it manually:

pyromind docker-install

Before pip uninstall pyromind-sdk, remove the wrapper manually:

pyromind docker-uninstall
# or
pyromind-docker-uninstall

pip uninstall has no uninstall hook, so this explicit command deletes ~/.pyromind/bin/docker and removes the PATH line from your shell rc file.

After installation, open a new terminal and use:

docker create \
  --name gpu-demo \
  --gpus 1 \
  --gpu-card L40S \
  busybox:1.36 sleep 300

docker ps only shows Running sandboxes by default; use docker ps -a to see Stopped sandboxes too. docker ps shows CUSTOM sandboxes only. To include OSWorld instances, use: docker ps shows CUSTOM sandboxes only. Filter by type using label.type (default CUSTOM, osworld for OSWorld, all for both):

docker ps --filter label.type=osworld
docker ps --filter label.type=custom
docker ps --filter label.type=all

Standard Docker filters are passed to the docker-rt server and applied there:

docker ps --filter name=test-sdk-1
docker ps --filter id=sb-94d290
docker ps --filter status=running
docker ps --filter ancestor=swebench
docker ps --filter label.type=custom

The legacy --filter label=docker-rt.type=<type> syntax is still supported.

This is the correct way to search on the server side. docker ps | grep XXXX is client-side filtering: grep runs after the daemon has returned output, so the docker-rt server never receives XXXX. Standard Docker protocol does not provide a cross-field substring filter; use the explicit filter that matches the field you know (name, id, status, ancestor, or label).

When the docker wrapper is active, docker ps uses the custom header: CONTAINER ID / IMAGE / COMMAND / CREATED / STATUS / PORTS / NAMES, matching standard Docker. Column widths are adaptive to the terminal and long values are truncated; CREATED is computed in standard Docker style (e.g. About a minute ago, 3 days ago). The STATUS column shows only the state keyword (running shows Up, stopped shows Exited, pending shows Created, failed shows Dead, without a duration), while --filter status= still matches the internal state (running / stopped / pending / failed).

Docker command reference

docker run / docker create

docker run creates and starts a sandbox; docker create only creates a local record; docker start actually creates/starts the sandbox (Pending -> Running).

Example:

docker create \
  --name gpu-demo \
  --cpus 4 \
  --memory 8g \
  --gpus 1 \
  --label docker-rt.gpu-card=L40S \
  -p 8080:80 \
  -v /workspace:/data:ro \
  busybox:1.36 sleep 300

docker start gpu-demo

Minimal create / run / remove example:

docker create --name test-sdk-1 swebench/swesmith.x86_64.oauthlib_1776_oauthlib.1fd52536
docker start test-sdk-1
docker ps
docker exec -it test-sdk-1 bash
docker rm -f test-sdk-1

--name is required when you want to use a custom name. Without it, docker create test-sdk-1 IMAGE treats test-sdk-1 as the image name. After creating with --name, docker start test-sdk-1 and docker rm -f test-sdk-1 work by name. docker rm NAME and docker rm -f NAME have the same behavior; running containers are paused before deletion. If you see No such container: NAME, run docker ps -a to check the actual container name — it is only registered when create used --name. With the k8s-middleware backend, docker run IMAGE without -d or -it returns after the sandbox is Running with a hint, because foreground attach is not supported yet. docker run -d and docker start also wait until the sandbox is Running before returning, so a following docker exec cannot race Pod creation. The command itself keeps running in the background. Use docker run -it IMAGE bash for an interactive terminal.

For the k8s-middleware backend, omitting --cpus, --memory and --gpus uses 1 CPU / 2Gi memory and no GPU.

docker ps / docker ps -a

docker ps      # Running only
docker ps -a   # Running + Stopped

With the wrapper active, the header is:

CONTAINER ID  IMAGE  COMMAND  CREATED  STATUS  PORTS  NAMES

Long values are truncated with ...; use docker inspect for full details.

docker inspect

docker inspect gpu-demo
docker inspect gpu-demo --format '{{json .resources}}'

The default response contains standard Docker inspect fields. Set DOCKER_RT_INSPECT_MODE=sandbox to return only compact sandbox fields.

docker exec

docker exec gpu-demo echo hello
docker exec -w /workspace gpu-demo ls -la

Non-interactive exec is supported; docker exec -it <name> reuses the k8s_middleware /sandboxes/{id}/terminal WebSocket and opens an interactive shell. The original pyromind terminal <sandbox-id> subcommand keeps its existing parameters and logic. --cluster and --api-key can be supplied as flags or environment variables, but at least one source for each is required; --base-url is optional.

docker logs

docker logs gpu-demo
docker logs -f gpu-demo

The k8s_middleware backend does not expose /logs yet.

docker cp

docker cp gpu-demo:/etc/os-release /tmp/os-release
docker cp /tmp/file.txt gpu-demo:/workspace/file.txt

docker stop / docker start

docker stop gpu-demo
docker start gpu-demo

With the k8s_middleware backend, stop maps to pause and start maps to resume.

docker restart

docker restart gpu-demo

Maps to pause then resume.

docker rename

docker rename gpu-demo gpu-demo-2

With the k8s_middleware backend, name-only changes skip the StatefulSet rollout.

docker rm

docker rm -f gpu-demo

With the k8s_middleware backend, it pauses before deleting.

docker port

docker port gpu-demo

Ports come from k8s_middleware port_mappings. With the PyromindSDK backend, docker-rt only shows port mappings; local access is not supported yet and would require an adapter to k8s_middleware port-forward / NodePort.

docker events

docker events is not supported by the k8s-middleware backend. Use docker ps and docker inspect to check container state.

Unsupported Docker commands

After starting docker-rt, these commands are not supported:

docker buildx build
docker compose build
docker compose up --build
docker logs
docker events

docker build is supported (see "Image builds" below): it builds with kaniko inside a throwaway sandbox in the cluster, pushes the image to a registry and archives a tarball to /workspace/docker_images/, so it needs neither a local Docker daemon nor any privilege. buildx build / compose build are not wired up yet — use docker build or plain Docker for now. docker logs is not supported by the k8s-middleware backend; use docker exec -it <container> bash to view logs inside the container.

Chain: Docker CLI -> docker-rt daemon -> KubeEnvironment -> Kubernetes API. The current implementation uses the official Kubernetes Python SDK directly; a future adapter can replace that hop with the k8s_middleware HTTP API.

Image builds

docker build is supported: it builds with kaniko inside a throwaway sandbox in the cluster. It needs neither a local Docker daemon nor any privilege (buildx build / compose build are not wired up yet). Every build has two outputs:

1. a push to a registry (the default, DOCKER_RT_BUILD_PUSH=true);
2. an image tarball in your workspace: /workspace/docker_images/<tag>.tar (see "Artifact archive" below).

Before you start: these must be set

Set them before starting the daemon — a running daemon does not pick up new variables; stop it (pyromind docker-rt --stop) and start it again. When something from the second group is missing, docker-rt rejects the build before creating a sandbox and names the variable, instead of burning a build.

① Platform connection — needed by every docker-rt command, builds included:

② Build-specific:

③ Platform side: the directory /workspace/docker_images must already exist in the user's workspace — it is the mount source for the artifact archive. Without it the build sandbox cannot be created.

④ What you do not need (common misconception): docker login credentials, ~/.docker/config.json and system credential helpers are never read, and no local Docker daemon takes part in the build.

Minimal working example

# ① platform connection
export PYROMIND_API_KEY=XXXXXXXXX
export PYROMIND_BASE_URL=https://pre-api.pyromind.ai/api/v1
export PYROMIND_CLUSTER='us-west-1#pre'

# ② build-specific (the prompt keeps the password out of shell history)
export DOCKER_RT_BUILD_IMAGE="your-registry.example.com/builders/kaniko:v1.24.0-debug"
export DOCKER_RT_BUILD_REGISTRY="docker.io/your-namespace"
export DOCKER_RT_REGISTRY_USERNAME="your-dockerhub-user"
export DOCKER_RT_REGISTRY_PASSWORD="$(python3 -c 'import getpass; print(getpass.getpass("Registry password/token: "))')"

pyromind docker-rt --daemon
docker-rt-context                      # point the Docker CLI at docker-rt

docker build -t myapp:latest .          # build
ls /workspace/docker_images             # → myapp_latest.tar and friends (see "Artifact archive")

This pushes to docker.io/your-namespace/myapp:latest. For another registry, set DOCKER_RT_BUILD_REGISTRY to its registry-host/namespace and supply that registry's username and password/token.

Registry authentication: two options

Option 1: registry username + password/token (this is what the minimal example above does). Docker Hub, ACR and similar registries require the target registry's account and password, or a token with push permission; anonymous pulls do not imply anonymous pushes. PYROMIND_API_KEY authenticates the Sandbox platform API and cannot replace registry credentials. When both credential variables are nonempty, they take precedence over the dockerconfig file.

Option 2: an existing dockerconfig file. Choose this instead of the username/password variables before starting the daemon:

unset DOCKER_RT_REGISTRY_USERNAME DOCKER_RT_REGISTRY_PASSWORD
export DOCKER_RT_REGISTRY_DOCKERCONFIG="/absolute/path/to/dockerconfig.json"

• The variable must contain a file path on the daemon's machine, not JSON or a base64 string. File contents may be JSON or base64-encoded JSON; auths must contain the registry's auth or username/password credentials.
• The default mounted file is /etc/docker-image/.dockerconfigjson. Even when using this file, explicitly set DOCKER_RT_REGISTRY_DOCKERCONFIG to pass the current credential precheck for short-tag builds.
• Builds do not automatically consume docker login authentication headers, ~/.docker/config.json, or system credential helpers. A config containing only credsStore / credHelpers or identitytoken is insufficient; the explicitly selected file must include the auths credentials described above.
• The docker-rt daemon reads these variables, so configure them before startup. If it is already running, stop it with pyromind docker-rt --stop and restart it from the configured shell. Setting variables only on the docker build command does not update an existing daemon's environment.
• ACR repository creation uses separate DOCKER_RT_ACR_ACCESS_KEY_ID, DOCKER_RT_ACR_ACCESS_KEY_SECRET, and DOCKER_RT_ACR_INSTANCE_ID settings; these do not replace registry push credentials.

Do not commit real passwords, tokens, or dockerconfig files, or copy them into a Dockerfile or build context. Base64 is not encryption; restrict access to credential files.

Build flow and limitations

How docker build -t myapp . works:

wrapper exports DOCKER_BUILDKIT=0
  → the classic builder POSTs the context tar to docker-rt's /build
  → a throwaway CUSTOM sandbox is created from DOCKER_RT_BUILD_IMAGE,
    with your /workspace/docker_images mounted (for the artifact archive)
  → the context is uploaded as a single gzipped file
  → exec kaniko --context=tar://… --destination=… --tar-path=/workspace/docker_images/<tag>.tar --digest-file=…
  → read the digest, register the short-tag alias, delete the sandbox
docker run myapp   → a normal sandbox pulls the image that was just pushed

Four things worth knowing:

1. The build sandbox must be disposable and cannot be the container the user already has: kaniko unpacks the FROM image's rootfs into its own container root ("may overwrite anything already there"), so it can only ever run in a throwaway container.
2. The builder image must be kaniko's -debug variant (e.g. gcr.io/kaniko-project/executor:v1.24.0-debug): the default executor image is FROM scratch — no sleep, no shell — while the sandbox template pins command: ["sleep", "infinity"]. Also, gcr.io is unreachable from some clusters, so mirror it into a registry the cluster can pull and point DOCKER_RT_BUILD_IMAGE at the mirror. See pyromind_sdk/docker_rt/builder-image/kaniko/README.md.
3. The push target differs per cluster: west pushes to Docker Hub, Shanghai pushes to Aliyun ACR Enterprise Edition and requires the repository to exist first (docker-rt creates it before spending a sandbox; missing AccessKey / instance id is a skip-with-warning). Short tags need DOCKER_RT_BUILD_REGISTRY (or a cluster profile plus DOCKER_RT_REGISTRY_NAMESPACE); when it cannot be resolved the build is rejected rather than guessed.
4. The legacy-builder deprecation banner is stripped by the wrapper. Forcing DOCKER_BUILDKIT=0 (which is what routes the build to POST /build) makes the real docker CLI print DEPRECATED: The legacy builder is deprecated … on stderr. That notice is about docker's own builder — not a docker-rt problem — and docker ships no switch to silence it, so the wrapper pipes the CLI's stderr through a filter that drops exactly that banner. stdout, every other stderr line and the CLI's exit code pass through untouched.

kaniko does not implement BuildKit-only features: RUN --mount=type=cache/secret/ssh, heredocs, --cache-to/from, true multi-platform builds. BuildKit-only flags such as --platform / --secret / --ssh are rejected by the wrapper instead of being silently ignored.

Artifact archive: /workspace/docker_images/<tag>.tar

Besides pushing, every build leaves a tarball of the image in your workspace, so you can use it without a registry or hand it around:

# load it wherever the workspace is visible (Jupyter, or a machine with it mounted);
# the tag comes back with it
docker load -i /workspace/docker_images/myapp_latest.tar

• /workspace/docker_images inside the sandbox is that workspace directory — the mount's source and target are the same string, so there is only one path to reason about.
• The file name comes from the first -t: pyromind-console:dev → pyromind-console_dev.tar (anything outside [A-Za-z0-9._-] becomes _). The image name inside the tarball is that tag. Rebuilding the same tag replaces that tag's archive; other tags keep theirs.
• Prerequisite: the directory must already exist (it is the mount source — see "③ Platform side" above).
• A failed push does not lose the artifact: the build runs first, the tarball is written, and only then is the image pushed (every build carries --skip-push-permission-check — without it kaniko's push-permission probe runs before the build and produces nothing at all). On a push failure the log gains a The image was archived to … line. An unwritable directory still wastes the whole build before it fails.
• The build log prints ==> This image is also archived to …; docker build --quiet hides it.

To run through k8s_middleware OpenAPI instead:

PYROMIND_API_KEY=your-key \
PYROMIND_BASE_URL=https://api.pyromind.ai/api/v1 \
PYROMIND_CLUSTER=us-west-2 \
pyromind docker-rt

In this mode docker-rt uses the PyromindSDK adapter, which reads the current sandbox, merges changed fields, and submits the full sandbox update. The backend is fixed to k8s-middleware. Local port forwarding is not supported for the PyromindSDK backend yet. k8s_middleware skips the StatefulSet rollout when only the sandbox name changes.

Common issues

Configuration

Client parameters

* api_key can be provided as a parameter or via PYROMIND_API_KEY environment variable.

Environment variables

Streaming sandbox exec

Use exec_command_stream for long-running commands. Output arrives as raw stdout/stderr byte chunks without the one-shot HTTP timeout:

import sys

with PyroMindAPIClient() as client:
    for chunk in client.sandboxes.exec_command_stream(
        "sb-xxxx",
        "python train.py",
        cwd="/workspace",
    ):
        if chunk.type == "stdout":
            sys.stdout.buffer.write(chunk.data)
        elif chunk.type == "stderr":
            sys.stderr.buffer.write(chunk.data)
        elif chunk.type == "exit":
            print(f"exit={chunk.returncode}")

The async client supports async for chunk in client.sandboxes.exec_command_stream(...). Pass tty=True when the command needs a pseudo-terminal for its output.

Project Structure

pyromind_sdk/
├── __init__.py                      # Package exports
├── client/                          # Sync and async API clients
│   ├── base.py / async_base.py      # Base HTTP clients
│   ├── client.py / async_client.py  # Unified sync/async entries
│   ├── sandbox.py / async_sandbox.py # Sandbox instances
│   ├── studio.py / async_studio.py  # Studio / training tasks
│   ├── jupyterLab.py / async_jupyterlab.py # Jupyter instances
│   ├── inference.py / async_inference.py   # Inference jobs
│   ├── echomind.py / async_echomind.py     # EchoMind instances
│   ├── storage.py                   # File storage
│   ├── profile.py                   # User profile & SSH keys
│   ├── models.py                    # Pydantic models
│   └── workflow/                    # Workflow validation & conversion
├── nodes/                           # Custom node SDK
│   ├── function_call_wrapper.py     # Python function → node
│   ├── python_function_executor.py  # Python node executor
│   ├── python_to_yaml.py            # Convert Python to YAML
│   ├── yaml_loader.py               # YAML node loader
│   ├── node_validator.py            # Node validation
│   ├── command_executor.py          # Command template execution
│   └── type_converter.py            # Node type conversion
├── common/                          # Shared utilities
│   ├── constants.py
│   └── node_sdk.py
├── docker_rt/                       # Docker-compatible Kubernetes runtime
│   ├── api/                         # Docker Engine API endpoints
│   ├── backend/                     # Runtime, build, storage & K8s adapters
│   ├── scripts/                     # Context registration helpers
│   ├── builder-image/               # Kaniko builder assets
│   ├── server.py / aio_server.py    # Sync/async daemon entry points
│   └── tests/                       # docker-rt test suite
├── cli.py                           # Unified CLI entry
├── python_function_to_yaml_cli.py   # Python → YAML CLI tool
├── test_run_workflow_cli.py         # Workflow submission CLI
├── exec_stream.py                   # Sandbox exec streaming helpers
├── terminal.py                      # Interactive sandbox terminal
├── examples/                        # Usage examples
│   ├── nodes/                       # YAML node examples
│   └── openapi/                     # API usage examples
└── tests/                           # SDK test suite
    ├── pytest/                      # Unit and integration tests
    └── test_yaml_nodes.py           # YAML node validation helper

Services

Studio (client.studio)

Training workflow management — create, monitor, and manage workflow tasks.

TrainingTaskCreateRequest parameters:

WorkflowRunRequest parameters:

Example:

from pyromind_sdk.client.models import TrainingTaskCreateRequest, WorkflowRunRequest

# Create a training task
task = client.studio.create(
    TrainingTaskCreateRequest(
        name="my-workflow",
        workflow={"nodes": [...]}
    )
)
print(f"Task ID: {task.task_id}")

# List tasks
tasks = client.studio.list()

# Run workflow with params
result = client.studio.run_with_params(
    WorkflowRunRequest(workflow_name="my-workflow", primitive_node_map={"key": "value"})
)

# Wait for completion
status = client.studio.wait_for_task_completion(task.task_id, timeout=600)
print(f"Final status: {status}")

Jupyter (client.jupyter)

Jupyter instance management.

JupyterRequest parameters:

Example:

from pyromind_sdk.client.models import JupyterRequest, ResourceConfig

# Create Jupyter instance
jupyter = client.jupyter.create(
    JupyterRequest(
        name="my-notebook",
        resources=ResourceConfig(cpu="4", memory="16Gi", gpu="1")
    )
)
print(f"Jupyter ID: {jupyter.id}, URL: {jupyter.url}")

Inference (client.inference)

Inference job management.

InferenceJobRequest parameters:

Example:

from pyromind_sdk.client.models import InferenceJobRequest, ResourceConfig

# List available frameworks and images
frameworks = client.inference.get_framework()
images = client.inference.get_inf_image(frameworks[0])

# Create inference job
job_id = client.inference.create(
    InferenceJobRequest(
        model_path="/path/to/model",
        inference_framework=frameworks[0],
        resources=ResourceConfig(cpu="8", memory="32Gi", gpu="1", gpu_card="H100"),
        startup_args=[{"--trust-remote-code": None}],
        name="my-inference"
    )
)
print(f"Job ID: {job_id}")

# Get job details
job = client.inference.get_job(job_id)
print(f"Status: {job.status}")

EchoMind (client.echomind)

EchoMind instance lifecycle management.

EchoMindJobRequest parameters:

Example:

from pyromind_sdk.client.models import EchoMindJobRequest, ResourceConfig

# Create EchoMind instance
job_id = client.echomind.create(
    EchoMindJobRequest(
        name="my-echomind",
        resources=ResourceConfig(cpu="4", memory="16Gi")
    )
)
print(f"EchoMind ID: {job_id}")

# List instances
instances = client.echomind.list()

# Cleanup
client.echomind.delete(job_id)

Storage (client.storage)

MinIO/S3-compatible file storage. Requires minio package (pip install minio).

Storage init parameters:

Example:

from pyromind_sdk.client.storage import StorageClient

storage = StorageClient()

# List files
files = storage.list_files(folder_path="documents/")
for f in files:
    print(f"{f['object_name']} ({f['size']} bytes)")

# Upload file
storage.upload_file("local/file.txt", "remote/file.txt")

# Download file
storage.download_file("remote/file.txt", "downloaded/file.txt")

# Check existence
if storage.file_exists("remote/file.txt"):
    print("File exists")

Profile (client.profile)

User profile and SSH keys.

Example:

# Get user info
user = client.profile.get_user_info()
print(f"User: {user.username}")

# Get storage info
storage_info = client.profile.get_storage_info()
print(f"Used: {storage_info.human_used_size} / Total: {storage_info.human_total_size}")

# SSH key management
from pyromind_sdk.client.models import UserPubKeyRequest

client.profile.add_key(UserPubKeyRequest(key="ssh-ed25519 AAAA..."))
keys = client.profile.list_keys()

Async Support

All services have async counterparts via PyroMindAsyncAPIClient:

from pyromind_sdk import PyroMindAsyncAPIClient

async with PyroMindAsyncAPIClient(api_key="your-api-key") as client:
    tasks = await client.studio.list()
    task = await client.studio.create(request)

Async clients (same method set as sync):

• client.studio → AsyncStudioClient
• client.instances → AsyncJupyterLabClient
• client.inference → AsyncInferenceClient
• client.echomind → AsyncEchoMindClient

Error Handling

All API calls raise PyroMindAPIError (sync) or PyroMindAsyncAPIError (async) on failure:

from pyromind_sdk.client.base import PyroMindAPIError

try:
    task = client.studio.get_task("invalid-id")
except PyroMindAPIError as e:
    print(f"Error {e.status_code}: {e.message}")
    if e.response:
        print(f"Response: {e.response}")

Key Response Models

Each service returns structured Pydantic model objects. Key fields:

TrainingTaskResponse (Studio)

JupyterResponse (Jupyter)

InferenceJobResponse (Inference)

EchoMindJobResponse (EchoMind)

Workflow Validation & Conversion

The client/workflow/ module provides workflow validation and format conversion:

from pyromind_sdk.client import validate_workflow, ValidationError

# Validate a workflow structure
try:
    validate_workflow(workflow_dict)
    print("Workflow is valid")
except ValidationError as e:
    print(f"Invalid workflow: {e}")

CLI Tools

Custom Node SDK

Beyond YAML definitions, the SDK provides programmatic node creation tools:

Wrap a Python function as a custom node:

from pyromind_sdk.nodes.function_call_wrapper import create_node_from_function

# Decorate any function to become a node definition
@create_node_from_function(
    name="my_custom_node",
    description="Processes input data",
    category="data-processing"
)
def process_data(input_text: str, threshold: float = 0.5) -> dict:
    # Your logic here
    return {"result": "processed", "value": len(input_text)}

Execute Python functions as nodes at runtime:

from pyromind_sdk.nodes.python_function_executor import execute_python_node

result = execute_python_node(
    source_code="print('hello')",
    node_type="python"
)

Convert Python functions to YAML config:

from pyromind_sdk.nodes.python_to_yaml import python_function_to_yaml_config

def my_func(input: str) -> str:
    return input.upper()

yaml_config = python_function_to_yaml_config(my_func)
# yaml_config can be saved to a .yaml file and registered via studio.create_node()

Validate and load YAML node definitions:

from pyromind_sdk.nodes.yaml_loader import load_yaml_node
from pyromind_sdk.nodes.node_validator import validate_node_config

node_config = load_yaml_node("path/to/node.yaml")
validate_node_config(node_config)

Testing

pytest

Examples

Development

Install from source

git clone https://github.com/pyromind/pyromind-sdk.git
cd pyromind-sdk
pip install -e .