> ## 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.

# Failure ingestion

> Send rollouts and failures to Avala, and how Avala turns them into a failure taxonomy and a gap report

The loop starts with what your robots actually do. You send rollouts, including the failures and the interventions. Avala reads them, finds the patterns and tells you what data is missing.

## Formats

| Format | How it arrives |
| - | - |
| MCAP | Fleet recording upload, or `avala import folder --data-type mcap` |
| ROS bags (`.bag`, `.db3`) | `avala import rosbag`, or convert to MCAP and upload as a fleet recording |
| LeRobot datasets | `avala import lerobot` from the Hugging Face Hub or a local directory |
| Video with logs | Video through `avala import folder --data-type video`. Avala aligns the logs with the video as part of the program. |
| Inspect Robots eval logs | `avala import inspect-robots`. See [Import evaluation logs](#import-evaluation-logs). |

MCAP keeps every topic, so it gives the most complete picture. The ROS bag importer converts camera topics (`sensor_msgs/Image` and `sensor_msgs/CompressedImage`) and carries joint states and other numeric or text topics. Point clouds and other binary payloads are skipped. Send MCAP when you need every topic preserved.

## Send rollouts as fleet recordings

Each upload goes into an existing fleet recording. Avala provisions recordings for your registered devices when the program starts. List them to find the recording UID.

```python Python theme={null}
from avala import Client

client = Client()  # reads AVALA_API_KEY

page = client.fleet.recordings.list(device_id="<device-uid>", limit=20)
for recording in page:
    print(recording.uid, recording.status, recording.started_at)

# Upload a local directory of rollout files into one recording.
session = client.fleet.uploads.upload_recording(
    "<recording-uid>",
    "./rollouts/2026-09-29",
)
print(session.uid, session.status)
```

```bash CLI theme={null}
# Preview what will be uploaded
avala fleet recordings upload \
  --source ./rollouts/2026-09-29 \
  --recording <recording-uid> \
  --dry-run

# Upload and wait for server-side processing
avala fleet recordings upload \
  --source ./rollouts/2026-09-29 \
  --recording <recording-uid> \
  --wait
```

`upload_recording` resumes an interrupted upload of the same source. A completed call means processing is queued. Check `client.fleet.recordings.get(uid).status` until it reads `ready`.

## Mark failures and interventions as events

Fleet events put a label on a moment in a recording. Mark each failure and each intervention so Avala can find it fast. Use `type` for the event class and `metadata` for anything your stack logs, such as the model version and the task.

```python Python theme={null}
from avala import Client

client = Client()

event = client.fleet.events.create(
    recording="<recording-uid>",
    device="<device-uid>",
    type="anomaly",
    label="Plate slipped during placement",
    timestamp="2026-09-29T14:03:12Z",
    severity="warning",
    duration_ms=1800,
    tags=["failure", "regrasp"],
    metadata={"model_version": "your-policy@2026-09-20", "task": "load_dishwasher"},
)
print(event.uid)

# Many events at once
created = client.fleet.events.create_batch(
    events=[
        {
            "recording": "<recording-uid>",
            "device": "<device-uid>",
            "type": "state_change",
            "label": "Operator took over",
            "timestamp": "2026-09-29T14:03:15Z",
            "tags": ["intervention"],
        },
    ]
)
print(created)
```

```typescript TypeScript theme={null}
import Avala from "@avala-ai/sdk";

const avala = new Avala(); // reads AVALA_API_KEY

const event = await avala.fleet.events.create({
  recording: "<recording-uid>",
  device: "<device-uid>",
  type: "anomaly",
  label: "Plate slipped during placement",
  timestamp: "2026-09-29T14:03:12Z",
  severity: "warning",
  durationMs: 1800,
  tags: ["failure", "regrasp"],
  metadata: { model_version: "your-policy@2026-09-20", task: "load_dishwasher" },
});
console.log(event.uid);
```

```bash CLI theme={null}
avala fleet events create \
  --recording <recording-uid> \
  --device <device-uid> \
  --type anomaly \
  --label "Plate slipped during placement" \
  --timestamp 2026-09-29T14:03:12Z \
  --severity warning
```

Event `type` is one of `error`, `warning`, `info`, `state_change`, `anomaly` or `custom`. `severity` is one of `info`, `warning`, `error` or `critical`. You can also create events automatically with [recording rules](/docs/visualization/fleet/recording-rules.md).

## Import ROS bags and LeRobot datasets

When rollouts live outside the fleet, import them as a dataset. Install the extra for the format first.

```bash theme={null}
pip install "avala[rosbag]"
avala import rosbag ./rollout_0412.bag --name "Rollouts 0412" --slug rollouts-0412 --wait

pip install "avala[lerobot]"
avala import lerobot --repo-id your-hf-user/your-rollouts --name "Rollouts" --slug rollouts --wait
```

The LeRobot importer is described in detail in [Exports](/docs/fleet-learning/exports.md#import-a-lerobot-dataset).

## Import evaluation logs

If you evaluate your policy with [Inspect Robots](https://github.com/robocurve/inspect-robots), an open-source evaluation tool, import its JSON eval log. Each trial, one scene in one epoch, labels one sequence with an [outcome label](/docs/fleet-learning/sequence-metadata.md). Failed trials become sequences you can filter, review and turn into collection work.

```bash theme={null}
pip install "avala[inspect]"

# Preview the trial-to-outcome mapping. Reads the log only.
avala import inspect-robots logs/load-dishwasher_1a2b3c4d.json --dataset your-org/dishwasher-eval --dry-run

# Label the sequences that already exist in the dataset, one per trial
avala import inspect-robots logs/load-dishwasher_1a2b3c4d.json --dataset your-org/dishwasher-eval

# Or create the dataset from each trial's recorded actions, plus camera frames if the run stored them
avala import inspect-robots logs/load-dishwasher_1a2b3c4d.json --dataset your-org/dishwasher-eval --create
```

| Inspect Robots trial | Outcome |
| - | - |
| Success score at or above `--success-threshold`, grading score at or above `--expert-threshold` | `expert_success` |
| Success score at or above `--success-threshold`, grading score below `--expert-threshold` | `partial_success` |
| Success score below `--success-threshold` | `failure` |
| Trial errored or was cancelled | `aborted` |
| Success scorer produced no value | Not labeled |

Every imported label has `source` set to `imported`, `evaluation_membership` set to `held_out_eval` and `autonomy_level` set to `autonomous`. `model_version` is the run's policy. The run's task becomes one subtask that spans the trial. Labels written by a person or a model are kept unless you pass `--overwrite`. The full option list is in the [CLI reference](/docs/sdks/cli.md#inspect-robots-evaluation-logs).

## Inspect recordings and events with the MCP server

The MCP server reads fleet data. Ask your assistant about recent failures, or call the tools directly:

* `fleet_list_recordings` and `fleet_get_recording` for recordings
* `fleet_list_events` filtered by `recording`, `device`, `type` or `severity`
* `get_fleet_health` for a fleet-wide summary

Uploads and event creation go through the SDK or the CLI. See [Use Avala with AI](/docs/getting-started/mcp.md) to connect.

## What Avala does with the rollouts

The steps below are a service Avala performs as part of the program. There is no API to call for them.

1. **Segmentation.** Avala splits each rollout into sequences and subtasks at state changes. Your events anchor the failure moments.
2. **Labeling.** Each sequence gets both axes of its [sequence metadata](/docs/fleet-learning/sequence-metadata.md): a technical validity check and an outcome label.
3. **Clustering.** Avala groups failures by what went wrong and under which conditions. Clusters map to a versioned failure taxonomy for your program. New clusters extend the taxonomy.
4. **Gap analysis.** Avala compares the failure clusters with the coverage of your existing training data and the evaluation cohorts.

## The gap report

Avala delivers a gap report for each batch of rollouts.

| Section | Contents |
| - | - |
| Scope | Recordings, time range, model versions and taxonomy version. |
| Failure taxonomy | Each failure mode, its definition and example sequences. |
| Distribution | Failure counts and rates per mode, per model version and per coverage cell. |
| Missing coverage | The [coverage cells](/docs/fleet-learning/coverage.md#coverage-cells) behind each failure mode that your training data lacks or holds too thinly. |
| Proposed experiments | One draft [capability experiment](/docs/fleet-learning/capability-experiments.md) per priority failure condition, with a hypothesis and target cells. |

You review the gap report and choose priorities. The approved experiments become the next collection brief.