Metadata-Version: 2.4
Name: ZBoost
Version: 1.0.6
Summary: HP Z Boost CLI Library
Author-email: James Dunne <james.dunne@hp.com>
License: MIT
Project-URL: Homepage, https://www.hp.com/boost
Project-URL: Repository, https://github.com/hpi-main/solution-boost-cli-library
Project-URL: Issues, https://github.com/hpi-main/solution-boost-cli-library/issues
Project-URL: Documentation, https://github.com/hpi-main/solution-boost-cli-library/docs
Project-URL: Changelog, https://github.com/hpi-main/solution-boost-cli-library/blob/main/CHANGELOG.md
Keywords: boost,cli,library
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: apscheduler>=3.11.0
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Boost CLI Python Library

[![Version](https://img.shields.io/pypi/v/zboost.svg)](https://pypi.org/project/zboost/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)

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](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Scheduled Workload Execution](#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

```bash
pip install zboost
```

### Using uv

```bash
uv add zboost
```

## Quick Start

```python
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.

```python
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.
