Avala Python SDK

Official Python SDK for the Avala API — the open Physical AI Data Platform. Programmatically manage sensor datasets (MCAP, LiDAR, video), annotation projects, exports, tasks, and fleet devices.

Note: This repository is a read-only mirror. To report bugs or request features, please open an issue. See CONTRIBUTING.md for details.

Installation

pip install avala

Requires Python 3.9+.

Quick Start

from avala import Client  # or: from avala import Avala

client = Client()  # reads AVALA_API_KEY env var

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

# Get a specific dataset
dataset = client.datasets.get("dataset-uid")

# Create an export and wait for completion
export = client.exports.create(project="project-uid")
finished = client.exports.wait(export.uid)  # polls until done
print(finished.download_url)

# List tasks with filters
tasks = client.tasks.list(project="project-uid", status="completed")

Load Public Dataset Revisions

Published Physical AI datasets with open-download rights can be loaded without an Avala account or API key. References resolve to immutable dataset and manifest digests; object bytes are fetched lazily and verified against their declared size and SHA-256.

import avala

with avala.load("owner/dataset") as dataset:  # defaults to the "main" revision alias
    episode = dataset.episodes[0]
    with episode.open() as raw_mcap:  # verified seekable spool; large objects stay off-heap
        magic = raw_mcap.read(8)
    print(dataset.canonical_reference, episode.sha256, episode.size_bytes, magic)

Pin a reproducible revision with owner/dataset@<revision-digest> or its returned avala://datasets/<uid>@<revision-digest> canonical reference. Async code uses async with await avala.async_load(...) as dataset:, episode = await dataset.episodes[0], and content = await episode.open() (close the returned file after consuming it). Use read() only for deliberately bounded, small objects.

Authentication

The client reads your API key from the AVALA_API_KEY environment variable by default:

export AVALA_API_KEY="avk_your_api_key"

Or pass it explicitly:

client = Client(api_key="avk_your_api_key")

Async Support

from avala import AsyncClient

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

Pagination

All .list() methods return a CursorPage that supports iteration:

page = client.datasets.list(limit=20)

for dataset in page:
    print(dataset.name)

# Manual pagination
if page.has_more:
    next_page = client.datasets.list(cursor=page.next_cursor)

Error Handling

from avala.errors import AvalaError, NotFoundError, RateLimitError, AuthenticationError

try:
    dataset = client.datasets.get("nonexistent")
except NotFoundError:
    print("Dataset not found")
except RateLimitError:
    print("Rate limited")
except AuthenticationError:
    print("Invalid API key")
except AvalaError as e:
    print(f"API error: {e}")

CLI Tool

Install the CLI with one command:

curl -fsSL https://avala.ai/install.sh | bash

Or install directly with pip:

pip install avala[cli]

avala configure                       # Interactive API key setup + validation
avala status                          # Organization dashboard overview
avala datasets list                   # List datasets
avala projects list                   # List projects
avala exports create --project <uid>  # Create an export
avala exports wait <uid>              # Poll until export completes
avala fleet devices list              # List fleet devices
avala -o json datasets list | jq .    # JSON output for scripting
avala shell-completion zsh >> ~/.zshrc # Enable tab completion
avala --version                       # Show CLI version

Available Resources

Resource	Methods	Description
client.datasets	list(), get(uid)	Browse and inspect datasets
client.projects	list(), get(uid)	Browse and inspect projects
client.exports	list(), get(uid), create(), wait(uid)	Create, poll, and manage annotation exports
client.tasks	list(), get(uid)	Browse tasks with project/status filters
client.storage_configs	list(), create(), test(), delete()	Manage cloud storage connections
client.agents	list(), get(), create(), update(), delete(), list_executions(), test()	Manage automation agents
client.inference_providers	list(), get(), create(), update(), delete(), test()	Manage inference providers
client.auto_label_jobs	list(), get(), create()	Batch auto-labeling jobs
client.quality_targets	list(), get(), create(), update(), delete(), evaluate()	Project quality targets
client.consensus	get_summary(), list_scores(), compute(), get_config(), update_config()	Consensus scoring
client.webhooks	list(), get(), create(), update(), delete(), test()	Manage webhook subscriptions
client.webhook_deliveries	list(), get()	Inspect webhook delivery logs

Documentation

• Python SDK Guide
• API Reference
• Quickstart
• Examples

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT - see LICENSE for details.