Python SDK (clore-ai)

Этот clore-ai пакет является официальным Python SDK для Clore.ai маркетплейса GPU. Он оборачивает весь REST API в чистый, типобезопасный интерфейс со встроенным ограничением частоты запросов, автоматическими повторными попытками и структурированной обработкой ошибок — так что вы можете сосредоточиться на аренде GPU, а не на HTTP-обвязке.

---

Установка

pip install clore-ai

Требования: Python 3.9+

Пакет устанавливает как Python SDK, так и clore CLI.

---

Аутентификация

Получите ваш API-ключ в панели управления Clore.ai → API разделе.

Вариант 1: переменная окружения (рекомендуется)

export CLORE_API_KEY=your_api_key_here

SDK читает CLORE_API_KEY автоматически — изменения кода не требуются.

Вариант 2: конфигурационный файл CLI

clore config set api_key YOUR_API_KEY

Это сохраняет ключ в ~/.clore/config.json.

Вариант 3: передайте напрямую в коде

from clore_ai import CloreAI

client = CloreAI(api_key="your_api_key_here")

⚠️ Важно: API Clore.ai использует auth заголовок для аутентификации, не Authorization: Bearer. SDK обрабатывает это автоматически.

---

Быстрый старт

from clore_ai import CloreAI

client = CloreAI()
servers = client.marketplace(gpu="RTX 4090", max_price_usd=5.0)
for s in servers:
    print(f"Сервер {s.id}: {s.gpu_model} — ${s.price_usd:.4f}/ч")

---

Синхронный клиент (CloreAI)

Конструктор

CloreAI(
    api_key: str | None = None,       # Берет CLORE_API_KEY из env / config
    base_url: str | None = None,       # По умолчанию: https://api.clore.ai/v1
    timeout: float = 30.0,             # Таймаут запроса в секундах
    max_retries: int = 3               # Попытки повторного запроса при ограничении частоты / сетевых ошибках
)

Клиент поддерживает контекстные менеджеры для автоматической очистки:

with CloreAI() as client:
    wallets = client.wallets()
    # client.close() вызывается автоматически

---

wallets()

Получите балансы ваших кошельков и адреса для пополнения.

wallets = client.wallets()

for wallet in wallets:
    print(f"{wallet.name}: {wallet.balance:.8f}")
    if wallet.deposit:
        print(f"  Пополнение: {wallet.deposit}")

Возвращает: List[Wallet]

Поле	Тип	Описание
name	str	Название валюты (например, "bitcoin", "CLORE-Blockchain", "USD-Blockchain")
balance	float | None	Текущий баланс
deposit	str | None	Адрес пополнения
withdrawal_fee	float | None	Комиссия за вывод

---

marketplace()

Поиск по GPU-маркетплейсу с необязательными фильтрами на стороне клиента.

# Все доступные серверы
servers = client.marketplace()

# Фильтр по модели GPU и максимальной цене
servers = client.marketplace(
    gpu="RTX 4090",
    max_price_usd=5.0
)

# Много-GPU сборки с большим объемом RAM
servers = client.marketplace(
    min_gpu_count=4,
    min_ram_gb=128.0
)

Параметры:

Параметр	Тип	По умолчанию	Описание
gpu	str | None	None	Фильтр по модели GPU (регистронезависимое совпадение по подстроке)
min_gpu_count	int | None	None	Минимальное количество GPU
min_ram_gb	float | None	None	Минимальный объем RAM в ГБ
max_price_usd	float | None	None	Максимальная цена в час в USD
available_only	bool	True	Возвращать только серверы, доступные для аренды

Возвращает: List[MarketplaceServer]

Каждый MarketplaceServer предоставляет удобные свойства для наиболее распространенных полей, а также доступ к полным вложенным данным:

Свойство	Тип	Описание
id	int	Уникальный ID сервера
gpu_model	str | None	Описание основной GPU (например, "1x NVIDIA GeForce RTX 4090")
gpu_count	int	Количество GPU (из gpu_array)
ram_gb	float | None	RAM в ГБ
price_usd	float | None	Цена по требованию в USD
spot_price_usd	float | None	Спотовая цена в USD
available	bool	Доступен ли сервер (не арендован)
location	str | None	Код страны из сетевых характеристик

Для продвинутых сценариев вы можете получить доступ к полной вложенной структуре:

Поле	Тип	Описание
specs	ServerSpecs | None	Полные аппаратные характеристики (specs.gpu, specs.ram, specs.cpu, specs.disk, specs.net, и т. д.)
price	ServerPrice | None	Полный объект цены (price.usd.on_demand_usd, price.usd.spot, price.on_demand, и т. д.)
rented	bool | None	Находится ли сервер сейчас в аренде
reliability	float | None	Оценка надежности сервера
rating	ServerRating | None	Рейтинг сервера (rating.avg, rating.cnt)

Примечание: Этот marketplace() эндпоинт открыт — он работает без API-ключа.

---

my_servers()

Список серверов, которые вы предоставляете на маркетплейс Clore.ai.

my_servers = client.my_servers()

for server in my_servers:
    print(f"{server.name}: {server.gpu_model} [{server.status}]")

Возвращает: List[MyServer]

Свойство	Тип	Описание
id	int	ID сервера
name	str | None	Имя сервера
gpu_model	str | None	Описание основной GPU
ram_gb	float | None	RAM в ГБ
status	str	Читаемый статус: "Онлайн", "Офлайн", "Отключен", или "Не работает"
connected	bool | None	Подключен ли сервер
online	bool | None	В сети ли сервер
visibility	str | None	"public" или "private"

---

server_config(server_name)

Получите конфигурацию конкретного сервера, который вы хостите.

config = client.server_config("MyGPU")

print(f"Сервер: {config.name}")
print(f"GPU: {config.gpu_model}")
print(f"Минимальная аренда: {config.mrl}h")
print(f"По требованию: ${config.on_demand_price}")
print(f"Спот: ${config.spot_price}")

Параметры:

Параметр	Тип	Описание
server_name	str	Имя сервера

Возвращает: ServerConfig

Свойство	Тип	Описание
name	str | None	Имя сервера
gpu_model	str | None	Описание основной GPU
mrl	int | None	Максимальная длительность аренды в часах
on_demand_price	float | None	Первая доступная цена по требованию в USD
spot_price	float | None	Первая доступная спотовая цена в USD
specs	ServerSpecs | None	Полные аппаратные спецификации
connected	bool | None	Подключен ли сервер
visibility	str | None	"public" или "private"

---

my_orders(include_completed)

Получите ваши текущие заказы, при необходимости включая выполненные/истекшие.

# Только активные заказы
orders = client.my_orders()

# Включить выполненные заказы
all_orders = client.my_orders(include_completed=True)

for order in orders:
    print(f"Заказ {order.id}: {order.type} — {order.status}")
    if order.pub_cluster:
        print(f"  IP: {order.pub_cluster}")
    if order.tcp_ports:
        print(f"  Порты: {order.tcp_ports}")

Параметры:

Параметр	Тип	По умолчанию	Описание
include_completed	bool	False	Включать выполненные/истекшие заказы

Возвращает: List[Order]

Поле	Тип	Описание
id	int	Уникальный ID заказа
server_id	int | None	ID сервера
type	str	"on-demand" или "spot"
status	str | None	Статус заказа
image	str | None	Docker-образ
currency	str | None	Валюта оплаты
price	float | None	Цена заказа в день
pub_cluster	str | None	Публичное имя хоста/IP для доступа
tcp_ports	dict | None	Сопоставления TCP-портов

---

spot_marketplace(server_id)

Просмотрите спотовые предложения рынка для конкретного сервера.

spot = client.spot_marketplace(server_id=6)

if spot.offers:
    for offer in spot.offers:
        print(f"Заказ {offer.order_id}: ${offer.price}/день (сервер {offer.server_id})")

if spot.currency_rates_in_usd:
    for coin, rate in spot.currency_rates_in_usd.items():
        print(f"  {coin}: ${rate}")

Параметры:

Параметр	Тип	Описание
server_id	int	ID сервера для проверки

Возвращает: SpotMarket

Поле	Тип	Описание
offers	List[SpotOffer] | None	Список спотовых предложений (order_id, price, server_id)
server	SpotServerInfo | None	Информация о сервере (минимальная цена, видимость, статус онлайн)
currency_rates_in_usd	Dict[str, float] | None	Курсы обмена валют в USD

---

create_order(...)

Создайте новый заказ по требованию или спотовый заказ. Так вы арендуете GPU.

Заказ по требованию

order = client.create_order(
    server_id=123,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",
    currency="bitcoin",
    ssh_password="MySecurePass123",
    ports={"22": "tcp", "8888": "http"}
)

print(f"Заказ создан: {order.id}")
print(f"Подключение: {order.pub_cluster}")

Спотовый заказ

order = client.create_order(
    server_id=123,
    image="cloreai/pytorch",
    type="spot",
    currency="bitcoin",
    spot_price=0.000005,
    ssh_password="MySecurePass123",
    ports={"22": "tcp"}
)

Параметры:

Параметр	Тип	Обязательно	Описание
server_id	int	Да	ID сервера для аренды
image	str	Да	Docker-образ (например, "cloreai/ubuntu22.04-cuda12")
type	str	Да	"on-demand" или "spot"
currency	str	Да	Валюта оплаты (например, "bitcoin")
ssh_password	str	Нет	Пароль SSH (буквенно-цифровой, максимум 32 символа)
ssh_key	str	Нет	Публичный ключ SSH (максимум 3072 символа)
ports	dict	Нет	Сопоставления портов, например, {"22": "tcp", "8888": "http"}
env	dict	Нет	Переменные окружения
jupyter_token	str	Нет	Токен Jupyter Notebook (максимум 32 символа)
command	str	Нет	Команда shell для выполнения после запуска контейнера
spot_price	float	Только для спота	Цена в день для спотовых заказов
required_price	float	Нет	Зафиксировать конкретную цену (только по требованию)
autossh_entrypoint	str	Нет	Использовать SSH entrypoint Clore.ai
gpu_count	int	Нет	Арендуйте только N GPU на серверах с частичной арендой (только по требованию); опустите, чтобы арендовать весь риг
gpu_indices	list[int]	Нет	Точные слоты GPU из partial_gpu_rental.free_indices; длина должна равняться gpu_count; опустите для автоматического выбора

Возвращает: сырой ответ API ({"code": 0} при успехе); получите созданный заказ через my_orders()

Ограничение частоты запросов: create_order имеет специальную 5-секундную паузу между вызовами. SDK обеспечивает это автоматически.

---

cancel_order(order_id, issue)

Отменить активный заказ или spot-предложение. При желании сообщите о проблеме с сервером.

# Простая отмена
client.cancel_order(order_id=38)

# Отмена с сообщением о проблеме
client.cancel_order(
    order_id=38,
    issue="GPU #1 перегревался и снижал частоты"
)

Параметры:

Параметр	Тип	Обязательно	Описание
order_id	int	Да	ID заказа для отмены
issue	str	Нет	Причина отмены / сообщение о проблеме (макс. 2048 символов)

Возвращает: Dict[str, Any]

---

set_server_settings(...)

Обновить настройки сервера, который вы размещаете на маркетплейсе.

client.set_server_settings(
    name="MyGPU",
    availability=True,
    mrl=96,
    on_demand=0.0001,
    spot=0.00000113
)

Параметры:

Параметр	Тип	Обязательно	Описание
name	str	Да	Имя сервера
availability	bool	Нет	Может ли сервер быть арендован
mrl	int	Нет	Максимальная длительность аренды в часах
on_demand	float	Нет	Цена по требованию в день
spot	float	Нет	Минимальная spot-цена в день

Возвращает: Dict[str, Any]

---

set_spot_price(order_id, price)

Обновить цену вашего spot-предложения на рынке.

client.set_spot_price(order_id=39, price=0.000003)

Параметры:

Параметр	Тип	Описание
order_id	int	ID spot-заказа/предложения
price	float	Новая цена в день

Возвращает: Dict[str, Any]

Примечание: Вы можете понижать spot-цены только раз в 600 секунд и только на ограниченный шаг. API возвращает code: 6 с подробностями, если вы превысите эти лимиты.

---

Асинхронный клиент (AsyncCloreAI)

Этот AsyncCloreAI клиент предоставляет те же методы, что и CloreAI, но все они возвращают корутины. Используйте его, когда вам нужны параллельные вызовы API или вы работаете в асинхронном приложении.

Базовое использование

import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI(api_key="your_key") as client:
        wallets = await client.wallets()
        for w in wallets:
            print(f"{w.name}: {w.balance:.8f}")

asyncio.run(main())

Параллельные операции

Запускайте несколько вызовов API параллельно с asyncio.gather:

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # Одновременно ищем несколько моделей GPU
        rtx4090, rtx3090, a100 = await asyncio.gather(
            client.marketplace(gpu="RTX 4090"),
            client.marketplace(gpu="RTX 3090"),
            client.marketplace(gpu="A100"),
        )

        for name, servers in [("RTX 4090", rtx4090), ("RTX 3090", rtx3090), ("A100", a100)]:
            if servers:
                cheapest = min(s.price_usd or float('inf') for s in servers)
                print(f"{name}: {len(servers)} доступно, самое дешёвое ${cheapest:.4f}/ч")
            else:
                print(f"{name}: нет доступных")

asyncio.run(compare_gpus())

Доступные методы

AsyncCloreAI поддерживает все те же методы, что и CloreAI:

Метод	Описание
await wallets()	Получить балансы кошельков
await marketplace(...)	Поиск на маркетплейсе
await my_servers()	Список ваших размещённых серверов
await server_config(name)	Получить конфигурацию сервера
await my_orders(...)	Список ваших заказов
await spot_marketplace(server_id)	Получить spot-предложения на рынке
await create_order(...)	Создать новый заказ
await cancel_order(...)	Отменить заказ
await set_server_settings(...)	Обновить настройки сервера
await set_spot_price(...)	Обновить spot-цену

---

Обработка ошибок

SDK предоставляет структурированные классы исключений для каждого кода ошибки API.

from clore_ai import CloreAI
from clore_ai.exceptions import (
    CloreAPIError,      # Базовый класс для всех ошибок API
    AuthError,          # Код 3 — неверный API-ключ
    RateLimitError,     # Код 5 — превышено ограничение частоты запросов
    InvalidInputError,  # Код 2 — неверные данные запроса
    DBError,            # Код 1 — ошибка базы данных
    InvalidEndpointError,  # Код 4 — неверная конечная точка
    FieldError,         # Код 6 — ошибка в конкретном поле
)

client = CloreAI()

try:
    order = client.create_order(
        server_id=123,
        image="cloreai/ubuntu22.04-cuda12",
        type="on-demand",
        currency="bitcoin",
    )
except AuthError:
    print("Неверный API-ключ. Проверьте ваш CLORE_API_KEY.")
except RateLimitError:
    print("Ограничение частоты запросов. SDK повторяет автоматически, но вы достигли максимального числа повторов.")
except InvalidInputError as e:
    print(f"Неверный запрос: {e}")
except FieldError as e:
    # Ошибки кода 6 включают подробности в ответе
    print(f"Ошибка поля: {e} (подробности: {e.response})")
except CloreAPIError as e:
    print(f"Ошибка API: {e} (код: {e.code})")

Коды ошибок

Код	Исключение	Описание
0	—	Успех
1	DBError	Ошибка базы данных
2	InvalidInputError	Неверные входные данные
3	AuthError	Неверный API-токен
4	InvalidEndpointError	Неверная конечная точка
5	RateLimitError	Превышено ограничение частоты запросов
6	FieldError	Ошибка в конкретном поле (см. error поле в ответе)

Все классы исключений наследуются от CloreAPIError и включают:

• e.code — числовой код ошибки

• e.response — полный словарь ответа API (если доступен)

---

Ограничение частоты запросов

SDK включает встроенный ограничитель частоты запросов, который автоматически соблюдает лимиты Clore.ai:

Конечная точка	Лимит
Большинство конечных точек	1 запрос/секунду
create_order	1 запрос/5 секунд

Когда API возвращает ошибку ограничения частоты запросов (код 5), SDK применяет экспоненциальную задержку и повторяет попытку до max_retries раз (по умолчанию: 3). Вам не нужно добавлять time.sleep() между вызовами.

Как это работает

1. Перед каждым запросом ограничитель частоты ждёт, пока истечёт минимальный интервал.

2. create_order вызовы имеют дополнительную 5-секундную паузу.

3. При ошибках ограничения частоты SDK делает экспоненциальный откат: 1с → 2с → 4с → ...

4. После max_retries неудачных попыток RateLimitError вызывается

Настроить поведение повторных попыток

client = CloreAI(
    max_retries=5,    # Больше повторов для долгих скриптов
    timeout=60.0      # Более долгий таймаут для медленных соединений
)

---

Конфигурация

Файл конфигурации

CLI хранит конфигурацию в ~/.clore/config.json:

{
  "api_key": "your_api_key_here"
}

Порядок разрешения

SDK определяет API-ключ в следующем порядке:

1. api_key аргумент, переданный конструктору

2. CLORE_API_KEY переменная окружения

3. api_key поле в ~/.clore/config.json

Переменные окружения

Переменная	Описание
CLORE_API_KEY	API-ключ для аутентификации

---

Дальше

• Справочник CLI — Используйте Clore.ai из вашего терминала

• REST API — Сырая документация API для кастомных интеграций

• On-Demand vs Spot — Поймите модели ценообразования

• Доступные Docker-образы — Предсобранные образы для GPU-нагрузок