> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Avala + Hugging Face

> Load Avala annotations as a Hugging Face Dataset

This guide shows how to export annotations from Avala and load them into a [Hugging Face `Dataset`](https://huggingface.co/docs/datasets/) for fine-tuning or evaluation.

## Prerequisites

```bash theme={null}
pip install avala datasets pillow
```

## Export and Load

```python theme={null}
from avala import Client
from datasets import Dataset, Features, Value, Sequence, Image
import json
import time

client = Client()  # reads AVALA_API_KEY

# Export annotations
export = client.exports.create(project="proj_abc123")
while export.status != "completed":
    time.sleep(2)
    export = client.exports.get(export.uid)

# Download the export
import requests
resp = requests.get(export.download_url)
annotations = resp.json()
```

## Convert to Hugging Face Dataset

```python theme={null}
def avala_to_hf_dataset(annotations: list, images_dir: str) -> Dataset:
    """Convert Avala export to a Hugging Face Dataset."""
    records = []
    for ann in annotations:
        boxes = []
        labels = []
        for obj in ann.get("annotations", []):
            if obj["type"] == "bounding_box":
                c = obj["coordinates"]
                boxes.append([c["x"], c["y"], c["x"] + c["width"], c["y"] + c["height"]])
                labels.append(obj["label"])

        records.append({
            "image": f"{images_dir}/{ann['file_name']}",
            "boxes": boxes,
            "labels": labels,
        })

    return Dataset.from_list(records).cast_column("image", Image())

dataset = avala_to_hf_dataset(annotations, "./images")
print(dataset)
# Dataset({
#     features: ['image', 'boxes', 'labels'],
#     num_rows: 1200
# })
```

## Use with a Hugging Face Trainer

```python theme={null}
from transformers import AutoModelForObjectDetection, TrainingArguments, Trainer

model = AutoModelForObjectDetection.from_pretrained(
    "facebook/detr-resnet-50",
    num_labels=len(label_names),
    ignore_mismatched_sizes=True,
)

training_args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=10,
    per_device_train_batch_size=4,
    learning_rate=1e-5,
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=dataset,
)

trainer.train()
```

## Classification Datasets

For image classification projects, the conversion is simpler:

```python theme={null}
def avala_classification_to_hf(annotations: list, images_dir: str) -> Dataset:
    """Convert classification annotations to HF Dataset."""
    records = []
    for ann in annotations:
        label = ann.get("annotations", [{}])[0].get("label", "unknown")
        records.append({
            "image": f"{images_dir}/{ann['file_name']}",
            "label": label,
        })

    return Dataset.from_list(records).cast_column("image", Image())

dataset = avala_classification_to_hf(annotations, "./images")

# Split into train/test
split = dataset.train_test_split(test_size=0.2, seed=42)
train_dataset = split["train"]
test_dataset = split["test"]
```

## Push to Hugging Face Hub

Share your annotated dataset with your team or the community:

```python theme={null}
dataset.push_to_hub("your-org/annotated-dataset", private=True)
```

<Warning>
  The SDK is currently read-only for datasets. Use the REST API or Mission Control to upload images before exporting annotations. See [File Uploads](/docs/sdks/rest-api#file-uploads).
</Warning>

## Next Steps

* [Python SDK reference](/docs/sdks/python) for all available methods
* [Avala + PyTorch](/docs/resources/frameworks/pytorch) for native PyTorch integration
* [Avala + LangChain](/docs/resources/frameworks/langchain) for LLM-powered annotation workflows