Skip to main content

Python client for Run:ai REST API

Project description

runapy

Run:ai platform streamlines AI workload orchestration, enabling organizations to efficiently manage and scale their machine learning tasks while optimizing resource utilization.

This project provides a Python client SDK to interact with the Run:ai REST API.

Core Capabilities:

  • A single class interface to perform all API actions
  • Body schema validation on compilation (with Pydantic)
  • Static type checks
  • Retry mechanism for resiliency on intermittent network errors
  • Debug messages flag
  • Automatic API token refresh

Table of Contents

  1. Requirements
  2. Installation
  3. Client Usage
  4. Controllers
  5. Examples
  6. Using CLIv2 Token
  7. Warranty
  8. License

Requirements

  • Run:ai control-plane version >= 2.18: The SDK requires Run:ai control-plane version 2.18 or higher for compatibility with its API features
  • Python version >= 3.11: Compatibility with libraries and language features
  • Run:ai Client Application: A client application is needed to generate the client_id and client_secret credentials required for API access. Create a client application here.

Note on token and permissions

Ensure the application token has the required role and scope permissions for the necessary API actions. Some API calls may fail with a 403 error if the token lacks sufficient permissions.

Installation

runapy is available in PyPi and can be downloaded directly as a python package

pip3 install runapy

We recommend using a Python virtual environment to avoid package conflicts.

python3 -m venv myenv
source myenv/bin/activate
pip3 install runapy

Client

RunaiClient is the only class required to interact with the Run:ai REST API

from runai.client import RunaiClient

client = RunaiClient(
            client_id="API",
            client_secret="clientsecret",
            runai_base_url="https://myorg.run.ai",
            cluster_id="513423qx-127t-4yk6-979g-5po843g37e2b",
            retries=3,
    )
Parameter Type Description
client_id string Required: The Run:ai application client ID, usually representing the application name
client_secret string Required: The client secret associated with the Run:ai application, acting as a password
runai_base_url string Required: The base URL for the Run:ai instance your organization uses. Example: https://myorg.run.ai
bearer_token string Optional: The API bearer token. Used for CLIv2 compatibility
retries int Optional: Number of retries to attempt on each failed API call for 5xx errors. Default is 1
cluster_id string Optional: The ID of the cluster. Default is None
debug bool Optional: Debug mode output. Default is False

If you don't have the cluster_id, it can be obtained with:

clusters = client.clusters.all()
for cluster in clusters:
    cluster_id = cluster["uuid"]

Note - If you have more than one cluster, make sure to save the ids to cluster_ids_list, and select the relevant cluster_id

Then, configure the client with the cluster id:

client.config_cluster_id(cluster["uuid"])

Note - The cluster_id must be present in order to use endpoints that have cluster_id required in payload according to Run:ai REST API.
So make sure to configure the cluster_id before using them.

Note on Controllers

The RunaiClient exposes object controllers, which provide a convenient way to interact with specific resources on the Run:ai platform. For example, to access projects:

from runai.client import RunaiClient

client = RunaiClient(
            client_id="API",
            client_secret="clientsecret",
            runai_base_url="https://myorg.run.ai",
            cluster_id="513423qx-127t-4yk6-979g-5po843g37e2b",
            retries=3,
    )

client.projects.all()

client.projects.all() returns a list of all projects in a given cluster according to the cluster id of the RunaiClient.

Currently supported controllers:

client.projects
client.node_pools
client.departments
client.access_rules
client.roles
client.users

client.workloads
client.workspace
client.training
client.inference
client.distributed

client.assets.pvc
client.assets.s3
client.assets.git
client.assets.nfs
client.assets.credentials.access_key
client.assets.credentials.password
client.assets.credentials.docker_registry_secret

Each controller exposes the function options() so you can see which methods are currently availalble for a given controller.
For example:

client.roles.options()
-> 
['all', 'get', 'get_roles_name_to_id_map']

Controller methods are documented.
Hover on the method parentheses to see the required and optional fields to pass to the function.

Examples

Check the examples section here for common API interactions, such as:

  • Create, list, patch projects/departments resources in a cluster
  • Create Nvidia nim llama inference workload
  • Create, Delete, Stop and Resume training and interactive workloads
  • Creating and modifying access rules and user roles
  • Managing PVC, S3, NFS, Git Run:ai assets
  • And more

Feel free to copy and run them as is, modify them as needed, or use them as a reference.

CLIv2 token

CLIv2 is Run:ai’s command-line interface version 2, which allows users to authenticate via the runai login command.
The package supports making API calls with the same user entity defined in the authentication.json file, generated by runai login.
Before executing the code below, ensure that CLIv2 is installed, runai login has been executed, and a successful login has been completed.\

You can run the following code to authenticate with the CLI user:

from runai.client import RunaiClient
from runai.cliv2_config_loader import CLIv2Config

config = CLIv2Config(cliv2_config_path="/path/to/.runai")

config.load()

token = config.token
runai_base_url = config.control_plane_url
cluster_id = config.cluster_uuid

client = RunaiClient(
    cluster_id=cluster_id,
    bearer_token=token,
    runai_base_url=runai_base_url
)

The example is also documented here with added instructions.

Warranty

This package is an open-source project maintained by the Run:ai Professional Services team.
While it is not an official project of the Run:ai product, it is actively maintained with a commitment to continued development.

In the future, the project is planned to become community-driven, inviting contributions and collaboration from users and the broader open-source community.

If you experience any issues or have feature requests, please submit them via the repository’s issue tracker.
Your feedback is highly appreciated and will help guide the project's future direction.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

runapy-0.7.1.tar.gz (21.3 kB view details)

Uploaded Source

Built Distribution

runapy-0.7.1-py3-none-any.whl (21.0 kB view details)

Uploaded Python 3

File details

Details for the file runapy-0.7.1.tar.gz.

File metadata

  • Download URL: runapy-0.7.1.tar.gz
  • Upload date:
  • Size: 21.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.6 Darwin/23.5.0

File hashes

Hashes for runapy-0.7.1.tar.gz
Algorithm Hash digest
SHA256 ccb64fc8c679807ee715d18cbaf66fe0e951d9aa63127f99f3d7dd9689bc7c3f
MD5 ae954795eed89198bb097981e91a37cb
BLAKE2b-256 72c5cc99501f11145eadd9d1bcdae3d1f9f87263d429b8b7fccb7fdfda84dad0

See more details on using hashes here.

File details

Details for the file runapy-0.7.1-py3-none-any.whl.

File metadata

  • Download URL: runapy-0.7.1-py3-none-any.whl
  • Upload date:
  • Size: 21.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.6 Darwin/23.5.0

File hashes

Hashes for runapy-0.7.1-py3-none-any.whl
Algorithm Hash digest
SHA256 8be3e462c02e2741928396a32cefa85538d0b8c9cf546585cf015741e42aec9f
MD5 d9cf0c7c0bdbaf1c3e6ce80bdf423eae
BLAKE2b-256 48ed6ac91fd972221ed2d350d20a1c3c9e72e2ea4cbd142fc62f992a18aae33b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page