Phase

A phase is a logical grouping of steps that represents a meaningful state change for a sample. Every phase ends in a stable, externally comprehensible state — a checkpoint that the workflow engine can recover from.

You define a phase as a Python function decorated with @phase. Inside it, you call steps to issue device commands. The workflow engine sequences steps, manages device locking, and surfaces errors to the phase level for user-defined recovery.

Example

from unitelabs.sdk.automate import phase

@phase()
async def agitation(target: Plate):
    await mix(target)
    await shake(target, rpm=300, duration=60)

Key properties

• Checkpoint-driven: always ends in a state that is stable and externally comprehensible; if a run is interrupted, recovery starts at the last completed phase
• Recoverable: errors within a phase are surfaced to the user for manual or automated recovery; see Error Handling for how to define recovery behavior
• Resource-scoped: implicitly defines which devices are locked while it runs; the workflow engine acquires locks before the phase starts and releases them when it completes
• Composable: phases are regular Python functions that can be reused across different workflows

Parallel phases

The workflow engine runs independent phases in parallel. If two phases share no data dependency, they execute concurrently — the workflow author does not need to do anything special:

@workflow(name="Parallel Prep")
async def main():
    # No dependency between these — runs in parallel
    reagent_a = await prepare_reagent_a()
    reagent_b = await prepare_reagent_b()

    await combine(reagent_a, reagent_b)  # waits for both

Error handling in phases

Steps within a phase are retried automatically on technical failure. If a step exhausts its retries, the error propagates to the phase for user-defined recovery — see Error Handling.

Related concepts

• Step: the individual device commands inside a phase
• Error Handling: how errors propagate through the hierarchy