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:

- 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

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

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:

- 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 to control Task behavior based on results

• Grid Search to understand parameter styles

• Manual Sweeps for targeted parameter combinations