# Carregar tarefas de avaliação de agentes

Um conjunto de dados [Harbor](https://harborframework.com/docs) é uma coleção de *tarefas* usadas para avaliar agentes de IA: cada tarefa fornece ao agente uma instrução, um ambiente sandbox para trabalhar e um verificador que pontua seu trabalho.

Diferentemente de datasets tabulares, um dataset Harbor não é um arquivo com uma linha por exemplo: **cada tarefa é um diretório**. O builder `harbor` lê esse repositório e gera uma linha por tarefa, de modo que um benchmark pode ser explorado, filtrado e compartilhado como qualquer outro dataset:

```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]
> Carregar um dataset do Harbor apenas *lê* as tarefas: ele nunca executa um agente, constrói uma imagem ou executa um verificador, e não requer que o Harbor esteja instalado. Use a biblioteca [Harbor](https://harborframework.com/docs) para executar as tarefas de fato.

> [!WARNING]
> As configurações de tarefas do Harbor são arquivos TOML. O Python 3.11 e versões posteriores os leem com a biblioteca padrão (`tomllib`); no Python 3.10, é necessário instalar um parser TOML como dependência extra. Consulte o guia de [instalação](./installation#harbor) para saber como instalá-lo.

## Estrutura do repositório

Um diretório de tarefa é identificado por dois arquivos, `task.toml` e `instruction.md`, e geralmente também contém a definição do ambiente, o verificador e uma solução oracle:

```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/
        └── ...
```

Um diretório é reconhecido como um conjunto de dados do Harbor assim que um de seus subdiretórios, independentemente da profundidade, for um diretório de tarefa (um arquivo `task.toml` e um arquivo `instruction.md` lado a lado): as tarefas são encontradas automaticamente, sem a necessidade de listar nenhum arquivo.

## Carregar tarefas

Como os conjuntos de dados do Harbor são compostos por diretórios em vez de arquivos de dados, eles são carregados por *caminho* — sem o argumento `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")
```

Passar `data_files` explicitamente também é suportado, desde que o padrão inclua os arquivos `task.toml` e `instruction.md` — um par de arquivos correspondentes gera uma linha:

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

## Colunas

Cada linha descreve uma tarefa:

| Coluna | Tipo | Descrição |
|--------|------|-------------|
| `name` | `string` | `[task].name` de `task.toml` (geralmente `org/name`), ou o nome do diretório da tarefa. |
| `description` | `string` | `[task].description` de `task.toml`. |
| `instruction` | `string` | Conteúdo de `instruction.md`: o que o agente deve fazer. |
| `keywords` | `list` de `string` | `[task].keywords` de `task.toml`. |
| `schema_version` | `string` | `schema_version` declarado por `task.toml`. |
| `config` | `dict` | O arquivo `task.toml` completo, como um objeto JSON: `[task]`, `[metadata]`, `[verifier]`, `[agent]`, `[environment]`, `[steps]`... |
| `metadata` | `dict` | A seção de `[metadata]` livre do `task.toml`. |
| `files` | `list` de `string` | Todos os arquivos da tarefa, com caminhos relativos ao diretório da tarefa. |
| `location` | `string` | Local do diretório da tarefa no conjunto de dados. |

```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'
```

O arquivo `task.toml` completo está disponível em `config`, portanto, nada é perdido quando uma tarefa usa campos que não são promovidos para sua própria coluna:

```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]
```

## Filtrar um benchmark

Como os metadados da tarefa são carregados como um dicionário, um benchmark pode ser explorado com os métodos usuais [filter()](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Dataset.filter) e [map()](/docs/datasets/v5.2.0/pt/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']
```

A coluna `files` lista tudo o que a tarefa inclui, o que é útil para verificar como uma tarefa é validada:

```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
```

## Leia os outros arquivos de uma tarefa

Apenas a instrução e a configuração de uma tarefa são carregadas como colunas: seus arquivos de ambiente, verificador e solução são listados na coluna `files`, como caminhos relativos ao diretório da tarefa. Combine `task_id` e `files` para abrir qualquer um deles com `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
```

## Configuração

[HarborConfig](/docs/datasets/v5.2.0/pt/package_reference/loading_methods#datasets.packaged_modules.harbor.HarborConfig) aceita alguns argumentos além dos habituais de `load_dataset`:

- `strip_canary` (padrão `True`): remove as linhas de comentário iniciais "benchmark data canary" das instruções, da mesma forma que o Harbor faz ao enviá-las a um agente. Defina como `False` para manter o conteúdo original do arquivo.
- `include_files` (padrão `True`): lista todos os arquivos de cada tarefa na coluna `files`. Defina como `False` para pular a listagem dos diretórios das tarefas, o que é mais rápido quando o conjunto de dados está em um sistema de arquivos remoto ou possui milhares de arquivos por tarefa.

As tarefas também podem ser transmitidas em streaming, o que evita o download de todo o benchmark antecipadamente:

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

## Veja também

- A documentação de referência de [Harbor](/docs/datasets/v5.2.0/pt/package_reference/loading_methods#datasets.packaged_modules.harbor.Harbor) e [HarborConfig](/docs/datasets/v5.2.0/pt/package_reference/loading_methods#datasets.packaged_modules.harbor.HarborConfig).
- A [documentação do Harbor](https://harborframework.com/docs) para *executar* as tarefas de um benchmark com agentes e verificadores.