Metadata-Version: 2.4
Name: cloudru-ml-cli
Version: 1.0.0
Summary: Библиотека для работы с api Cloud.ru MLSpace
Author-email: Максим Налимов <msnalimov@cloud.ru>
License-File: LICENSE
Keywords: cloud.ru
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <4,>=3.10
Requires-Dist: click>=8.3.3
Requires-Dist: cryptography==49.0.0
Requires-Dist: gitpython<4.0.0,>=3.1.51
Requires-Dist: h11==0.16.0
Requires-Dist: jinja2<4.0.0,>=3.1.6
Requires-Dist: keyrings-alt<6.0.0,>=5.0.2
Requires-Dist: pycryptodome<4.0.0,>=3.21.0
Requires-Dist: python-gitlab==6.5.0
Requires-Dist: responses<0.26.0,>=0.25.6
Requires-Dist: setuptools<83.0.0,>=82.0.1
Requires-Dist: tabulate<0.10.0,>=0.9.0
Requires-Dist: types-pyyaml<7.0.0.0,>=6.0.12.20241230
Requires-Dist: types-requests<3.0.0.0,>=2.32.0.20241016
Requires-Dist: types-tabulate<0.10.0.0,>=0.9.0.20241207
Provides-Extra: dev
Requires-Dist: check-manifest; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: lint
Requires-Dist: pre-commit; extra == 'lint'
Provides-Extra: release
Requires-Dist: hatch; extra == 'release'
Requires-Dist: hatchling; extra == 'release'
Requires-Dist: python-semantic-release; extra == 'release'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Description-Content-Type: text/markdown

# О пакетах

Репозиторий содержит инструменты разработчика для работы с [Cloud.ru Distributed Train](https://cloud.ru/docs/aicloud/mlspace/index.html):
- `mls` — CLI-утилита, которая позволяет запускать некоторые сервисы Distributed Train из терминала.
- `mls-core` — Python-библиотека с открытым исходным кодом для использования некоторых сервисов Distributed Train в своих проектах (SDK).

# Установка

Чтобы установить `mls` на локальную машину, в терминале выполните:

```bash
pip install cloudru-ml-cli==1.0.0
Зеркало: 
pip install --index-url https://gitverse.ru/api/packages/cloudru/pypi/simple/ --extra-index-url https://pypi.org/simple --trusted-host gitverse.ru mls==1.0.0
```
![GIF Установка](https://raw.githubusercontent.com/cloud-ru/ml-cli/refs/heads/master/install.gif)

`mls-core` установится автоматически.

# Перед началом работы

Выполните:

```bash
mls configure
```
![GIF Установка](https://raw.githubusercontent.com/cloud-ru/ml-cli/refs/heads/master/%D0%A1%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA%20CLI/static/QS6.png)

# Примеры использования

## Получение списка задач

```Bash
mls job list
```
![GIF Получение списка задач](https://raw.githubusercontent.com/cloud-ru/ml-cli/refs/heads/master/list.gif)

## Просмотр логов задачи

```Bash
mls job logs
```
![GIF Просмотр логов задачи](https://raw.githubusercontent.com/cloud-ru/ml-cli/refs/heads/master/logs.gif)

## Запуск задачи через библиотеку

```python
import logging
from mls.utils.common import read_profile
from mls_core import AllocationApi, DTSApi, QueueApi, TensorboardApi, TrainingJobApi, JupyterServerApi
from pydantic.v1 import BaseSettings


class Settings(BaseSettings):
    key_id: str
    key_secret: str
    x_workspace_id: str
    x_api_key: str
    region: str
    output: str
    endpoint_url: str


class ManagerApi:
    """Управляющий фасад для доступа ко всем API-сервисам."""

    def __init__(self, settings: Settings, logger: logging.Logger = None):
        client_kwargs = dict(
            endpoint_url=settings.endpoint_url,
            client_id=settings.key_id,
            client_secret=settings.key_secret,
            x_workspace_id=settings.x_workspace_id,
            x_api_key=settings.x_api_key,
            backoff_factor=10,
            connect_timeout=10 * 60,
            read_timeout=10 * 60,
            debug=False
        )
        if logger is not None:
            client_kwargs['logger'] = logger

        self.job = TrainingJobApi(**client_kwargs)
        self.dts = DTSApi(**client_kwargs)
        self.allocation = AllocationApi(**client_kwargs)
        self.queue = QueueApi(**client_kwargs)
        self.jupyter_server = JupyterServerApi(**client_kwargs)
        self.tensorboard = TensorboardApi(**client_kwargs)


if __name__ == "__main__":
    # 1. инициализация logger (1 раз на всё приложение)
    logger = logging.getLogger("my_mlspace_api")
    logger.setLevel(logging.INFO)
    if not logger.handlers:  # чтобы не добавить дважды, если модуль импортируют
        logger.addHandler(logging.StreamHandler())

    # 2. загрузка профиля и создание фасада
    env = read_profile('any_profile_name')
    settings = Settings(**env)
    api = ManagerApi(settings, logger=logger)

    # 3. примеры вызовов:
    print(api.job.run_job(
        payload={
            'script': '/home/jovyan/hello_world.py',
            'base_image': 'cr.ai.cloud.ru/hello_world:latest',
            'instance_type': 'a100.1gpu.40',
            'region': settings.region,
            'type': 'pytorch2',
            'n_workers': 1,
            'job_desc': 'Привет, мир'
        }
    ))
    print(api.dts.transfer_list())
    print(api.dts.conn_sources())
    print(api.allocation.get_list_allocations())
    print(api.queue.get_list_queues_by_allocation_id('00000000-0000-0000-0000-000000000000'))
    print(api.jupyter_server.get_jupyter_servers_list())
    print(api.tensorboard.get_tensorboards_list())

```
## Файловая структура 
####  Файловая структура не является финальной

```
├── README.md                   # Основная документация проекта.
├── LICENSE                     # Лицензионные условия.
├── install.gif                 # Анимация установки.
├── list.gif                    # Анимация списка.
├── logs.gif                    # Анимация логов.
├── mls
│   ├── cli.py                  # Вход в CLI.
│   ├── manager                 # Логика CLI.
│   │   ├── allocation          # Подкоманда: mls allocation.
│   │   │   ├── cli.py          # Работа с allocation.
│   │   │   └── help.py         # Помощь для allocation.
│   │   ├── configure           # Подкоманда: mls configure.
│   │   │   ├── cli.py          # Настройка профиля.
│   │   │   ├── help.py         # Помощь для configure.
│   │   │   └── utils.py        # Утилиты профиля.
│   │   ├── dts                 # Подкоманда: mls transfer и connector.
│   │   │      ├── connector_cli.py # Работа с connector .
│   │   │      ├── custom_types.py  # Константы и датаклассы .
│   │   │      ├── decorators.py    # Декораторы.
│   │   │      ├── help.py          # Помощь для transfer и connector.
│   │   │      ├── table.py         # Табличное отображение   .
│   │   │      ├── transfer_cli.py  # Работа с transfer. 
│   │   │      └── utils.py         # Утилиты connector и transfer.
│   │   ├── job                  # Подкоманда: mls job.
│   │   │    ├── cli.py          # Управление задачами ML.
│   │   │    ├── constants.py    # Константы   
│   │   │    ├── custom_types.py # Типы задач ML.
│   │   │    ├── dataclasses.py  # Дата-классы задач.
│   │   │    ├── help.py         # Помощь для job.
│   │   │    └── utils.py        # Утилиты задач ML.
│   │   ├── queue               # Подкоманда: mls queue.
│   │        ├── cli.py         # Работа с queue.
│   │        └── help.py        # Помощь для queue.
│   │   └── jupyter_server      # Подкоманда: mls js (Jupyter Server); mls js autoshutdown (get/set/delete).
│   │        ├── cli.py         # Команды Jupyter Server и группа autoshutdown.
│   │        ├── constants.py   # Константы Jupyter Server.
│   │        ├── help.py        # Справка Jupyter Server и autoshutdown.
│   │        └── utils.py       # Утилиты Jupyter Server.
│   │   └── tensorboard         # Подкоманда: mls tensorboard.
│   │        ├── cli.py         # Команды TensorBoard.
│   │        ├── constants.py   # Константы TensorBoard.
│   │        ├── create_cli_options.py # Опции create.
│   │        ├── dataclasses.py # Payload DTO TensorBoard.
│   │        ├── help.py        # Помощь для tensorboard.
│   │        ├── resume_cli_options.py # Опции resume.
│   │        ├── utils.py       # Утилиты TensorBoard.
│   │        └── yaml_contract.py # YAML-контракт create.
│   │   └── workspace           # Команда: mls ws.
│   │        ├── cli.py         # Просмотр workspaces.
│   │        └── help.py        # Помощь для workspace.
│   └── utils                   # Поддержка CLI.
│       ├── cli_entrypoint_help.py # Помощь CLI.
│       ├── common.py           # Общая логика.
│       ├── client.py           # Обобщение клиента cli (queue и allocation). 
│       ├── common.py           # Общие для cli методы. 
│       ├── common_types.py     # Пользовательские типы.
│       ├── execption.py        # Исключения.
│       ├── fomatter.py         # Форматирование справки.
│       ├── openssl.py          # Поддержка шифрования. 
│       ├── settings.py         # Настройки приложения.
│       └── style.py            # Стили CLI.
├── mls_core                    # SDK ядро.
│   ├── allocation
│   │    └── client.py          # Выделенный клиент allocation. 
│   ├── queue
│   │    └── client.py          # Выделенный клиент queue.
│   ├── jupyter_server
│   │    └── client.py          # Выделенный клиент Jupyter Server (в т.ч. workspace autoshutdown).
│   ├── tensorboard
│   │    └── client.py          # Выделенный клиент tensorboard.
│   ├── client.py               # Клиенты SDK.
│   ├── exeptions.py            # Исключения SDK.
│   └── setting.py              # Настройки SDK.
├── samples
│   ├── template.binary.yaml             # Шаблон бинарных задач.
│   ├── template.binary_exp.yaml         # Тестовый шаблон (Нестабильный). TODO 
│   ├── template.horovod.yaml            # Шаблон Horovod.
│   ├── template.pytorch.yaml            # Шаблон PyTorch. (Используйте pytorch2)
│   ├── template.pytorch2.yaml           # Шаблон PyTorch2.(минорно отличается от pytorch)
│   ├── template.tensorboard.create.yaml # Шаблон создания tensorboard.
│   └── template.pytorch_elastic.yaml    # Шаблон PyTorch Elastic.
└── Руководство cli
    ├── FAQ.md                  # FAQ.
    ├── Быстрый старт.md        # Быстрый старт.
    ├── Запуск задачи.md        # Запуск задач.
    ├── Jupyter Servers примеры.md # Примеры команд Jupyter Server (CLI).
    ├── Работа переменных окружений.md
    ├── Сокрытие credentials.md
    ├── Настройка автокомплитера.md # Автозаполнение.
    └── TensorBoard YAML-примеры.md # Примеры YAML для tensorboard команд.

```

# Автокомплитер Zsh

Пользователям Zsh доступна автозаполнение в CLI.
Чтобы использовать опцию, добавьте скрипт ниже в Zsh-профиль:

```bash

_mls_completion() {
    autocomplete "${COMP_WORDS[@]}"
}
complete -F _mls_completion mls

```

Примеры 
> binary YAML  [binary](https://github.com/cloud-ru/ml-cli/blob/master/samples/template.binary.yaml).
> 
> pytorch2 YAML  [pytorch2](https://github.com/cloud-ru/ml-cli/blob/master/samples/template.pytorch2.yaml).
> 
> pytorch_elastic YAML  [pytorch_elastic](https://github.com/cloud-ru/ml-cli/blob/master/samples/template.pytorch_elastic.yaml).

# Jupyter servers в CLI

В CLI добавлены команды управления Jupyter Server:

```bash
mls js list
mls js config
mls ws list
mls js create --namespace default --name my-js --image-name cr.ai.cloud.ru/aicloud-jupyter/jupyter-server \
  --image-tag 0.0.95 --image-type datahub --instance-type free.0gpu
mls js modify 11111111-1111-4111-8111-111111111111 --shutdown-in 3600
mls js pause 11111111-1111-4111-8111-111111111111
mls js delete 11111111-1111-4111-8111-111111111111
mls js get 11111111-1111-4111-8111-111111111111
mls js resume --namespace default --region SR006 --instance-type free.0gpu 11111111-1111-4111-8111-111111111111
mls js autoshutdown get 00000000-0000-4000-8000-000000000000
mls js autoshutdown set 00000000-0000-4000-8000-000000000000 --shutdown-in 3600
mls js autoshutdown delete 00000000-0000-4000-8000-000000000000
```

Параметры create / resume можно задавать через CLI или YAML `--config`; явно переданные CLI-опции переопределяют YAML. Доступные регионы, instance types и образы для Jupyter берутся из `mls js config`. Подробнее в `Справочник CLI/Jupyter Servers примеры.md`.

docs: .gitlab-ci.yml rules
