# Загрузка задач оценки агентов

Набор данных [Harbor](https://harborframework.com/docs) представляет собой коллекцию *задач*, используемую для оценки ИИ-агентов: каждая задача предоставляет агенту инструкцию, изолированную среду для работы и верификатор, который оценивает его работу.

В отличие от табличных наборов данных, набор данных Harbor не является файлом, в котором каждая строка соответствует одному примеру: **каждая задача представляет собой каталог**. Сборщик `harbor` читает такой репозиторий и возвращает по одной строке на задачу, благодаря чему бенчмарк можно исследовать, фильтровать и передавать так же, как и любой другой набор данных:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("harborframework/terminal-bench")
>>> dataset
DatasetDict({
    test: Dataset({
        features: ['name', 'instruction', 'description', 'keywords', 'schema_version', 'config', 'metadata', 'files', 'location'],
        num_rows: 66
    })
})
```

> [!TIP]
> Загрузка набора данных Harbor только *читает* задачи: она никогда не запускает агента, не собирает образ и не выполняет верификатор, а также не требует установки Harbor. Для фактического запуска задач используйте библиотеку [Harbor](https://harborframework.com/docs).

> [!WARNING]
> Конфигурации задач Harbor представляют собой файлы в формате TOML. Python 3.11 и более поздние версии читают их с помощью стандартной библиотеки (`tomllib`); в Python 3.10 необходимо установить парсер TOML как дополнительную зависимость. Ознакомьтесь с руководством по [установке](./installation#harbor), чтобы узнать, как это сделать.

## Структура репозитория

Каталог задачи определяется двумя файлами, `task.toml` и `instruction.md`, и обычно также содержит определение окружения, верификатор и эталонное решение:

```text
my-harbor-dataset/
├── README.md
└── tasks/
    ├── task-a/
    │   ├── task.toml          # configuration: metadata, resources, timeouts...
    │   ├── instruction.md     # what the agent is asked to do
    │   ├── README.md          # optional human-readable description
    │   ├── environment/       # Dockerfile / docker-compose.yaml + files of the sandbox
    │   ├── tests/             # verifier
    │   └── solution/          # oracle solution
    └── task-b/
        └── ...
```

Каталог распознаётся как датасет Harbor, как только один из его подкаталогов, независимо от глубины вложенности, является каталогом задачи (файлы `task.toml` и `instruction.md` находятся рядом): задачи обнаруживаются автоматически, без необходимости перечислять файлы.

## Загрузка задач

Поскольку наборы данных Harbor состоят из каталогов, а не из файлов данных, они загружаются по *пути* — аргумент `data_files` не требуется:

```py
>>> from datasets import load_dataset

>>> # a dataset repository on the Hub
>>> dataset = load_dataset("harborframework/terminal-bench")
>>> # a local directory of tasks
>>> dataset = load_dataset("/path/to/my-harbor-dataset")
>>> # the tasks of a repository that are in a sub-directory
>>> dataset = load_dataset("harborframework/terminal-bench", data_dir="tasks")
```

Явная передача `data_files` также поддерживается, при условии, что шаблон включает файлы `task.toml` и `instruction.md` — одна пара совпавших файлов даёт одну строку:

```py
>>> dataset = load_dataset(
...     "/path/to/my-harbor-dataset",
...     data_files={"test": ["my-tasks-dir/*/task.toml", "my-tasks-dir/*/instruction.md"]},
... )
```

## Столбцы

Каждая строка описывает одну задачу:

| Столбец | Тип | Описание |
|--------|------|-------------|
| `name` | `string` | `[task].name` из `task.toml` (обычно `org/name`) или имя каталога задачи. |
| `description` | `string` | `[task].description` в `task.toml`. |
| `instruction` | `string` | Содержимое `instruction.md`: что должен сделать агент. |
| `keywords` | `list` из `string` | `[task].keywords` в `task.toml`. |
| `schema_version` | `string` | `schema_version`, объявленная в `task.toml`. |
| `config` | `dict` | Весь `task.toml` в виде объекта JSON: `[task]`, `[metadata]`, `[verifier]`, `[agent]`, `[environment]`, `[steps]`... |
| `metadata` | `dict` | Свободная секция `[metadata]` в файле `task.toml`. |
| `files` | `list` из `string` | Все файлы задачи, с путями, относительными к каталогу задачи. |
| `location` | `string` | Расположение каталога задачи в наборе данных. |

```py
>>> dataset = load_dataset("harborframework/terminal-bench", split="test")
>>> dataset[0]["name"]
'terminal-bench/atrx-vep-crispr'
>>> dataset[0]["instruction"][:90]
'You are provided with a region of genomic DNA representing the human ATRX locus plus sequence'
>>> dataset[0]["config"]["task"]["authors"]
[{'name': 'ScaleAI', 'email': 'tbench@scale.com'}]
>>> dataset[0]["metadata"]["category"]
'Science'
>>> dataset[0]["config"]["environment"]
{'build_timeout_sec': 1800.0, 'cpus': 2, 'memory_mb': 4096, 'storage_mb': 10240, 'gpus': 0}
>>> dataset[0]["files"][:4]
['LICENSE.md', 'README.md', 'environment/Dockerfile', 'environment/data/CDS-information.txt']
>>> dataset[0]["location"]
'tasks/atrx-vep-crispr'
```

Весь `task.toml` доступен в `config`, поэтому ничего не теряется, если задача использует поля, которые не вынесены в отдельные столбцы:

```py
>>> dataset = dataset.map(lambda task: {"timeout_min": task["config"]["verifier"]["timeout_sec"] / 60})
>>> sorted(set(dataset["timeout_min"]))[:6]
[1.0, 2.0, 3.0, 4.0, 5.0, 7.0]
```

## Фильтрация бенчмарка

Поскольку метаданные задачи загружаются в виде словаря, бенчмарк можно исследовать с помощью стандартных методов [filter()](/docs/datasets/main/ru/package_reference/main_classes#datasets.Dataset.filter) и [map()](/docs/datasets/main/ru/package_reference/main_classes#datasets.Dataset.map):

```py
>>> security_tasks = dataset.filter(lambda task: task["metadata"].get("category") == "Security")
>>> [task["name"] for task in security_tasks]
['terminal-bench/formal-crypto', 'terminal-bench/html-js-filter', 'terminal-bench/interleaved-vigenere', 'terminal-bench/shadow-relay', 'terminal-bench/uefi-bootkit']
```

Столбец `files` перечисляет всё, что входит в состав задачи, что удобно для изучения того, как задача проверяется:

```py
>>> pytest_verifiers = dataset.filter(lambda task: any(f.startswith("tests/") and f.endswith(".py") for f in task["files"]))
>>> pytest_verifiers.num_rows
63
```

## Чтение других файлов задачи

Загружаются только инструкция и конфигурация задачи в виде столбцов: файлы окружения, верификатора и решения перечислены в столбце `files` в виде путей, относительных к каталогу задачи. Соедините `task_id` и `files`, чтобы открыть любой из них с помощью `fsspec`:

```py
>>> from huggingface_hub import hffs
>>> dataset_path = "hf://datasets/harborframework/terminal-bench"
>>> with hffs.open(f"{dataset_path}/tasks/cumulative-layout-shift/environment/Dockerfile", "r") as f:
...     print(f.read()[:20])
'# harbor-canary GUID
```

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

[HarborConfig](/docs/datasets/main/ru/package_reference/loading_methods#datasets.packaged_modules.harbor.HarborConfig) принимает несколько аргументов в дополнение к стандартным для `load_dataset`:

- `strip_canary` (по умолчанию `True`): удаляет начальные строки с комментарием «benchmark data canary» из инструкций, так же, как это делает Harbor при отправке их агенту. Установите `False`, чтобы сохранить исходное содержимое файла.
- `include_files` (по умолчанию `True`): перечисляет все файлы каждой задачи в столбце `files`. Установите значение `False`, чтобы пропустить перечисление каталогов задач; это быстрее, если датасет находится на удалённой файловой системе или содержит тысячи файлов на задачу.

Задачи также можно загружать потоково, что позволяет избежать скачивания всего бенчмарка заранее:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("harborframework/terminal-bench", streaming=True)
>>> for task in dataset["test"]:
...     print(task["name"])
```

## См. также

- Справочная документация по [Harbor](/docs/datasets/main/ru/package_reference/loading_methods#datasets.packaged_modules.harbor.Harbor) и [HarborConfig](/docs/datasets/main/ru/package_reference/loading_methods#datasets.packaged_modules.harbor.HarborConfig).
- Документация [Harbor](https://harborframework.com/docs) о том, как *запускать* задачи бенчмарка с агентами и верификаторами.