ZBoost 1.0.6

HP Z Boost CLI Library

Boost CLI Python Library

A Python wrapper library for the HP Z Boost CLI tool that provides a programmatic interface for managing and executing workloads on distributed GPU resources. The library simplifies interaction with HP Z Boost infrastructure through Python, enabling automated workload scheduling, resource management, and GPU utilisation.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Scheduled Workload Execution

Overview

The Boost CLI Python Library (boost) wraps the boost binary in a clean Python API. It provides two layers of access:

• BoostCli (boost.cli.wrapper) - thin subprocess wrapper; every CLI command has a corresponding method.
• boost.core.* - named abstraction functions that compose BoostCli with logging, for use in production code.

Command groups covered: login/logout, m2m, gpu, pool, session, agent/agent service, agent provision/agent query, release, release admin, config, context, client service, debug, organization, user, help, run.

Features

• Authentication management: login, login_m2m_token, M2M token create/list/remove
• Resource discovery: GPU list/query, pool list
• Workload execution: run applications on distributed GPU resources
• Agent management: list, info, run, provision, query, service lifecycle
• Session control: request, list, release, add/list/remove paths
• Release management: list, download, admin create/list/update
• Configuration: get, set, list, unset per active context
• Context management: activate, list, remove
• Client service (Windows): install, uninstall, start, stop, restart, status, enable, disable
• Debug utilities: gather-logs, flags
• Organization listing
• Task scheduling: built-in APScheduler-based scheduler with automatic retry on failure
• Error handling: @handle_exceptions decorator returns None on any exception

Installation

Prerequisites

• Python 3.12 or higher
• HP Z Boost CLI (boost binary) installed and available on PATH

Note: The library calls sys.exit(1) at import if the boost binary is not found on PATH.

Using pip

pip install zboost

Using uv

uv add zboost

Quick Start

from boost.cli.wrapper import BoostCli
from boost.core.m2m.m2m_login import m2m_login
from boost.core.gpu.gpu_list import gpu_list
from boost.utils.envar import read_env_var

# Initialise the client.
boost_client = BoostCli()

# Authenticate using an M2M token stored in the environment.
token = read_env_var("token")
m2m_login(boost_client, token, task_id="quick_start")

# List available GPUs.
resources = gpu_list(boost_client, task_id="quick_start")
print(resources)

Scheduled Workload Execution

The scheduler automatically discovers an available GPU, runs the workload, and re-schedules 1 minute later if it fails.

import os
from boost.utils.envar import read_env_var
from boost.common.global_ import lib_log as log
from boost.scheduling.scheduler import Scheduler
from boost.scheduling.add_task import add_runtime_task
from boost.scheduling.decorators import add_task_before_runtime


def build_scheduler() -> Scheduler:
    scheduler = Scheduler()
    token = read_env_var("token")
    workload = ["python", "your_script.py"]

    @add_task_before_runtime(scheduler, task_id="boost_task_01")
    async def boost_task_01() -> None:
        if token is None:
            return log.error("Set the 'token' environment variable.")
        task_id = boost_task_01.task_id  # type: ignore
        await add_runtime_task(token, workload, scheduler, task_id)

    return scheduler


def main() -> None:
    log.info(f"Working directory: {os.getcwd()}")
    scheduler = build_scheduler()
    scheduler.start()


if __name__ == "__main__":
    main()

License

MIT License.