Preparation

Every upload is prepared after it lands. The prepare run sorts the takes into tasks (task discovery) and gives each task a Task: a published one it matched, or a draft. It also splits takes into pieces and reads the task names the dataset’s own metadata gives. Everything it does is a proposal or a flag: nothing is removed and no Task is published. client.preparation reads and changes what the dataset page’s Tasks tab shows.

Every method takes a dataset id, its full name (accounts/{account}/datasets/{dataset}) or the preparation’s name (.../preparation). A merged dataset or a mixture has no run of its own: its uploads are prepared one by one, so get answers state NONE. Nothing here starts a run.

Read what preparation found

from qualia import Qualia

client = Qualia()

prep = client.preparation.get(dataset_id)
print(prep.state, prep.run_id, prep.error)
for warning in prep.warnings:
    print("warning:", warning)

found = prep.discovery  # None on runs from before discovery
for task in found.tasks if found else []:
    # task_id: the matched Task or the draft; "" when no draft was made
    print(task.name, task.episode_count, task.health_flag, task.task_id)
    print("  references:", task.reference_episode_ids)

names = prep.task_strings  # the dataset's own task names
for c in names.candidates if names else []:
    print(c.key, c.text, c.episode_count, c.blocked_reason, c.confirmation)

state is NONE, QUEUED, RUNNING, SUCCEEDED, FAILED or SKIPPED. discovery.status is RUNNING, DONE, FAILED or FALLBACK (one task for the whole dataset). A run discovery did not split has its one Task in task_match instead.

A found task with a task_id is a Task you can read, edit and publish with client.tasks. One without a Task can become one:

task = client.tasks.create(
    found.tasks[0].name[:32],
    references=[
        {"role": "SUCCESS", "episode": f"{dataset_name}/episodes/{episode}"}
        for episode in found.tasks[0].reference_episode_ids[:3]
    ],
)
client.datasets.update(dataset_name, linked_task=task.name)

Confirm the dataset’s task names

When task_strings.confirmable is true, a person decides which of the dataset’s own task names to use as tasks. The set you send replaces the decisions on the run’s names: a name not listed is cleared, and [] clears them all. Send one choice per usable name, as the Tasks tab does: the ones to use confirmed=True with a Task name of at most 32 characters, the rest confirmed=False.

prep = client.preparation.get(dataset_id)
usable = [
    c for c in prep.task_strings.candidates
    if not c.blocked and not c.looks_like_code
]
client.preparation.confirm_task_strings(
    dataset_id,
    prep.run_id,
    [{"key": c.key, "display_name": "Fold the towel", "confirmed": True}
     for c in usable],
)

Confirmed names start task discovery again, which drafts a Task for each. Read the preparation again to see them.

Refusal	Why
409 ABORTED	A newer run replaced the names you read: read again and decide again
400 FAILED_PRECONDITION	A blocked name (outcome words, a code, already a task label), or no names
400 INVALID_ARGUMENT	A key the run does not have, a key twice, or a name over 32 characters
403 PERMISSION_DENIED	A workspace’s service key: a person decides on task names

A personal API key decides as the person who made it, and the decision records the key.

The CLI has the same: qualia dataset preparation and qualia dataset confirm-task-names.