# Task Blueprints

Task Blueprints let you define Task configurations in your `valohai.yaml`.

Instead of manually configuring Tasks in the UI each time, you can predefine parameter values, Task types, and execution limits in your YAML, making experiments repeatable and version-controlled.

### Why use Task Blueprints?

**Reproducibility:** Anyone on your team can run the same Task configuration without manual setup.

**Version control:** Task definitions live in Git alongside your code, so you can track changes over time.

**Automation:** Launch pre-configured Tasks from the UI, CLI, or API without reconfiguring parameters each time.

### Define a Task Blueprint

Task Blueprints require at least one step with parameters defined in your `valohai.yaml`.

Add a `task` block to your YAML:

```yaml
- step:
    name: train-model
    image: tensorflow/tensorflow:2.6.0
    command:
      - pip install valohai-utils
      - python train_model.py {parameters}
    parameters:
      - name: epochs
        default: 5
        type: integer
      - name: learning_rate
        default: 0.001
        type: float
    inputs:
      - name: dataset
        default: s3://mybucket/data/train.npz

- task:
    step: train-model
    name: hyperparameter-sweep
    type: grid-search
    maximum-queued-executions: 3
    on-child-error: stop-all-and-error
    parameters:
      - name: epochs
        style: multiple
        rules:
          items: [5, 10, 15, 20, 25]
      - name: learning_rate
        style: logspace
        rules:
          min: -5
          max: -1
          count: 5
```

This blueprint creates a Grid Search Task with 25 executions (5 epoch values × 5 learning rate values).

### Task Blueprint properties

| **Property**              | **Description**                                                                                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
| step                      | The step name this Task runs (must match a step in your YAML)                                         |
| name                      | The Task blueprint name (shows in the UI dropdown)                                                    |
| type                      | Task type: `grid-search`, `random-search`, `bayesian-optimization`, `manual-search`, or `distributed` |
| maximum-queued-executions | How many executions can be queued (and running) in parallel                                           |
| on-child-error            | What happens when an execution fails: `stop-all-and-error`, `continue-running`                        |
| parameters                | Parameter configuration (see below)                                                                   |

### Parameter configuration

Each parameter in the Task blueprint specifies:

| **style**  | **Description**              | **Rules**                     |
| ---------- | ---------------------------- | ----------------------------- |
| `single`   | One fixed value              | `value: 10`                   |
| `multiple` | List of discrete values      | `items: [5, 10, 15]`          |
| `linear`   | Evenly spaced range          | `min: 1, max: 10, count: 10`  |
| `logspace` | Logarithmically spaced range | `min: -5, max: -1, count: 5`  |
| `random`   | Random sampling              | `min: 1, max: 100, count: 20` |

#### Example: Linear parameter

```yaml
parameters:
  - name: batch_size
    style: linear
    rules:
      min: 16
      max: 128
      count: 8
```

This generates: `16, 32, 48, 64, 80, 96, 112, 128`

#### Example: Multiple values

```yaml
parameters:
  - name: model_name
    style: multiple
    rules:
      items: [resnet50, efficientnet, vit]
```

This creates 3 executions, one for each model.

### Run a Task from a blueprint

After saving your YAML, pushing to Git, and fetching the repository in Valohai:

1. Open your project in Valohai
2. Go to the **Tasks** tab
3. Click **Create Task**
4. Select the step used in your Task blueprint
5. Open the **Select task blueprint...** dropdown
6. Choose your blueprint name
7. (Optional) Adjust parameters in the UI if needed
8. Click **Create task**

Valohai will create the Task based on your blueprint configuration.

### Example: Benchmarking datasets

You want to train a model on 10 different customer datasets.

**Step 1:** Define a `store_id` parameter and parameterized input:

```yaml
- step:
    name: train-model
    image: python:3.9
    command:
      - python train.py {parameters}
    parameters:
      - name: store_id
        type: string
    inputs:
      - name: dataset
        default: s3://bucket/stores/{parameter:store_id}/data/*

- task:
    step: train-model
    name: multi-dataset-training
    type: manual-search
    maximum-queued-executions: 5
    parameters:
      - name: store_id
        style: multiple
        rules:
          items: [store-001, store-002, store-003, store-004, store-005]
```

**Step 2:** Run the Task blueprint from the UI.

Each execution trains on a different store's dataset, and results are grouped in the Task view.

### Next steps

* [Early Stopping](/tasks/early-stopping.md) to control Task behavior based on results
* [Grid Search](/tasks/grid-search.md) to understand parameter styles
* [Manual Sweeps](/tasks/manual-sweeps.md) for targeted parameter combinations


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/tasks/task-blueprints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.