Python SDK - Avala Documentation

Python SDK требует Python 3.9+.

Установка

pip install avala

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

from avala import Client

client = Client(api_key="your-api-key")

# List all datasets
datasets = client.datasets.list()
for dataset in datasets:
    print(dataset.name, dataset.uid)

Создание аккаунта

Функция signup создаёт новый аккаунт Avala и возвращает API-ключ. Аутентификация не требуется.

from avala import signup

result = signup(
    email="dev@acme.com",
    password="SecurePass123!",
    first_name="Jane",       # optional
    last_name="Doe",         # optional
)

print(f"User: {result.user.email}")
print(f"API Key: {result.api_key}")

Также доступен асинхронный вариант:

from avala import async_signup

result = await async_signup(email="dev@acme.com", password="SecurePass123!")

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

SDK аутентифицируется с помощью API-ключа Avala, который передаётся через заголовок X-Avala-Api-Key в каждом запросе. Вы можете передать ключ напрямую или позволить SDK прочитать его из переменной окружения. Вариант 1: Передача ключа напрямую

from avala import Client

client = Client(api_key="your-api-key")

Вариант 2: Использование переменной окружения

export AVALA_API_KEY="your-api-key"

from avala import Client

# Automatically reads AVALA_API_KEY from the environment
client = Client()

Асинхронная поддержка

SDK поставляется с полностью асинхронным клиентом на основе httpx. Используйте AsyncClient для неблокирующего ввода-вывода в асинхронных приложениях.

import asyncio
from avala import AsyncClient

async def main():
    client = AsyncClient(api_key="your-api-key")

    datasets = await client.datasets.list()
    for dataset in datasets:
        print(dataset.name)

    # Always close the client when done, or use it as a context manager
    await client.close()

asyncio.run(main())

Использование асинхронного контекстного менеджера:

import asyncio
from avala import AsyncClient

async def main():
    async with AsyncClient() as client:
        datasets = await client.datasets.list()
        for dataset in datasets:
            print(dataset.name)

asyncio.run(main())

Работа с наборами данных

Python SDK в настоящее время работает только на чтение для наборов данных — вы можете получать списки, просматривать и исследовать элементы, но не создавать и не удалять наборы данных. Для загрузки и мутаций используйте REST API.

Список наборов данных

datasets = client.datasets.list()

for dataset in datasets:
    print(f"{dataset.name} ({dataset.uid})")
    print(f"  Items: {dataset.item_count}")
    print(f"  Created: {dataset.created_at}")

Получение набора данных

dataset = client.datasets.get("550e8400-e29b-41d4-a716-446655440000")

print(dataset.name)
print(dataset.slug)
print(dataset.item_count)

Работа с проектами

Список проектов

projects = client.projects.list()

for project in projects:
    print(f"{project.name} ({project.uid})")
    print(f"  Status: {project.status}")
    print(f"  Created: {project.created_at}")

Получение проекта

project = client.projects.get("770a9600-a40d-63f6-c938-668877660000")

print(project.name)
print(project.status)

Работа с задачами

Список задач

tasks = client.tasks.list(project="770a9600-a40d-63f6-c938-668877660000", status="pending")

for task in tasks:
    print(f"{task.uid} — {task.name} ({task.status})")

Получение задачи

task = client.tasks.get("990c1800-b62f-85a8-e150-880099880000")

print(task.name)
print(task.status)

Работа с экспортами

Python SDK поддерживает полные CRUD-операции для агентов, вебхуков, конфигураций хранилища, провайдеров инференса, целей качества, конфигурации консенсуса и организаций. Наборы данных и проекты в настоящее время доступны только для чтения — для мутаций используйте REST API.

Создание экспорта

export = client.exports.create(project="770a9600-a40d-63f6-c938-668877660000")

print(f"Export started: {export.uid}")
print(f"Status: {export.status}")

Ожидание завершения

import time

export = client.exports.create(project="770a9600-a40d-63f6-c938-668877660000")

while export.status != "completed":
    time.sleep(2)
    export = client.exports.get(export.uid)
    print(f"Status: {export.status}")

print(f"Download: {export.download_url}")

Работа с организациями

Список организаций

orgs = client.organizations.list()
for org in orgs:
    print(f"{org.name} ({org.slug})")

Создание организации

org = client.organizations.create(name="My Team", visibility="private", industry="technology")
print(f"Created: {org.name} ({org.uid})")

Управление участниками

members = client.organizations.list_members("my-team")
for member in members:
    print(f"{member.full_name} - {member.role}")

Работа со срезами

Список срезов

slices = client.slices.list("my-org")
for s in slices:
    print(f"{s.name}: {s.item_count} items")

Просмотр элементов набора данных

Список элементов в наборе данных

items = client.datasets.list_items("my-org", "my-dataset")
for item in items:
    print(f"{item.uid}: {item.key}")

Список последовательностей

sequences = client.datasets.list_sequences("my-org", "my-dataset")
for seq in sequences:
    print(f"{seq.uid}: {seq.key} ({seq.number_of_frames} frames)")

Аннотации типов

SDK полностью типизирован. Все объекты ответов — это модели Pydantic с полными аннотациями типов, что обеспечивает автодополнение и проверку типов из коробки.

from avala.types import Dataset, Project, Export, Task

def process_dataset(dataset: Dataset) -> None:
    print(dataset.name)        # str
    print(dataset.uid)         # str
    print(dataset.item_count)  # int
    print(dataset.created_at)  # Optional[datetime]

def process_task(task: Task) -> None:
    print(task.uid)            # str
    print(task.name)           # Optional[str]
    print(task.status)         # Optional[str]
    print(task.project)        # Optional[str]

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

SDK выбрасывает типизированные исключения для точной обработки различных типов ошибок.

from avala import Client
from avala.errors import (
    AvalaError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

client = Client()

try:
    dataset = client.datasets.get("nonexistent")
except NotFoundError as e:
    print(f"Dataset not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
    for detail in e.details:
        print(f"  - {detail}")
except AvalaError as e:
    # Catch-all for any other Avala API error
    print(f"API error ({e.status_code}): {e.message}")

Исключение	Описание
`AvalaError`	Базовое исключение для всех ошибок Avala API.
`AuthenticationError`	Недействительный или отсутствующий API-ключ (HTTP 401).
`NotFoundError`	Запрошенный ресурс не существует (HTTP 404).
`RateLimitError`	Превышен лимит запросов API (HTTP 429). Содержит атрибут `retry_after`.
`ValidationError`	Тело запроса не прошло валидацию (HTTP 400/422). Содержит атрибут `details` с ошибками по полям.
`ServerError`	Сервер вернул внутреннюю ошибку (HTTP 5xx).

Пагинация

Методы списков возвращают объект CursorPage. Вы можете итерировать по элементам напрямую или управлять пагинацией вручную.

# Iterate through items on the current page
for dataset in client.datasets.list():
    print(dataset.name)

# Manual pagination — control page size and access cursor
page = client.datasets.list(limit=10)
for dataset in page.items:
    print(dataset.name)

# Fetch the next page
if page.has_more:
    next_page = client.datasets.list(limit=10, cursor=page.next_cursor)

Управление парком

Управление парком находится в предварительном доступе. Описанные API могут измениться.

Пространство имён fleet предоставляет доступ к реестру устройств, записям, событиям, правилам и оповещениям.

# List online devices
devices = client.fleet.devices.list(status="online")

# Create a timeline event on a recording
event = client.fleet.events.create(
    recording_id="rec_abc123",
    timestamp="2026-01-15T10:30:00Z",
    type="anomaly",
    label="Gripper force spike",
    metadata={"force_n": 45.2}
)

# Create a recording rule
rule = client.fleet.rules.create(
    name="High Latency Alert",
    condition={"type": "threshold", "topic": "/diagnostics/latency", "field": "data.value", "operator": "gt", "value": 100},
    actions=[{"type": "tag", "value": "high-latency"}, {"type": "notify", "channel_id": "ch_your_channel_id"}]
)

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

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

Вы можете настроить поведение клиента при инициализации.

from avala import Client

client = Client(
    api_key="your-api-key",
    base_url="https://api.avala.ai/api/v1",  # Default
    timeout=60,        # Request timeout in seconds (default: 30)
    max_retries=3,     # Number of retries on transient errors (default: 2)
)

Параметр	Тип	По умолчанию	Описание
`api_key`	`str`	Переменная окружения `AVALA_API_KEY`	Ваш API-ключ Avala.
`base_url`	`str`	`https://api.avala.ai/api/v1`	Базовый URL API.
`timeout`	`float`	`30`	Таймаут запроса в секундах.
`max_retries`	`int`	`2`	Количество автоматических повторов при временных ошибках (5xx, таймауты).

SDKs

​Установка

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

​Создание аккаунта

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

​Асинхронная поддержка

​Работа с наборами данных

​Список наборов данных

​Получение набора данных

​Работа с проектами

​Список проектов

​Получение проекта

​Работа с задачами

​Список задач

​Получение задачи

​Работа с экспортами

​Создание экспорта

​Ожидание завершения

​Работа с организациями

​Список организаций

​Создание организации

​Управление участниками

​Работа со срезами

​Список срезов

​Просмотр элементов набора данных

​Список элементов в наборе данных

​Список последовательностей

​Аннотации типов

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

​Пагинация

​Управление парком

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

Установка

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

Создание аккаунта

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

Асинхронная поддержка

Работа с наборами данных

Список наборов данных

Получение набора данных

Работа с проектами

Список проектов

Получение проекта

Работа с задачами

Список задач

Получение задачи

Работа с экспортами

Создание экспорта

Ожидание завершения

Работа с организациями

Список организаций

Создание организации

Управление участниками

Работа со срезами

Список срезов

Просмотр элементов набора данных

Список элементов в наборе данных

Список последовательностей

Аннотации типов

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

Пагинация

Управление парком

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