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

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=sandbox. docker inspect returns only:

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

Set DOCKER_RT_INSPECT_MODE=standard to keep the standard Docker inspect fields as well.

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. Non-running containers can be removed directly with docker rm NAME; running containers need -f / --force. When using the docker-rt wrapper, a running docker rm without -f asks for confirmation first. 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. Use docker run -d for a background sandbox or 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 only contains sandbox fields. Set DOCKER_RT_INSPECT_MODE=standard to keep standard Docker inspect 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 build
docker buildx build
docker compose build
docker compose up --build
docker logs
docker events

They depend on a real Docker daemon / BuildKit container lifecycle. Build the image with normal Docker/BuildKit first and push it to a registry, then use docker run with that image. 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.

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

Project Structure

pyromind_sdk/
├── client/                          # API clients
│   ├── base.py                      # Base HTTP client
│   ├── client.py                    # PyroMindAPIClient (unified entry)
│   ├── async_client.py              # PyroMindAsyncAPIClient (async entry)
│   ├── 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
├── common/                          # Shared utilities
│   ├── constants.py
│   └── node_sdk.py
├── cli.py                           # CLI entry points
├── python_function_to_yaml_cli.py   # Python → YAML CLI tool
├── examples/                        # Usage examples
│   └── openapi/                     # API usage examples
└── tests/                           # Test suite

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 .