What is a workflow?
A workflow is the top-level executable process you write to achieve a scientific outcome. It coordinates timing, logic, data flow, and physical state across one or more instruments.
unitelabs-sdk< 0.10.0, import flow and task from Prefect instead. Use flow in place of both workflow and phase decorators, and task as step decorators.The automation hierarchy
UniteLabs workflows are built from four nested concepts:
| Concept | Role |
|---|---|
| Workflow | The top-level process: defines what scientific result is produced |
| Phase | Represents a logical stage of the scientific intent: always ends in a stable, checkpoint state |
| Step | The smallest scientific unit operation: executes on exactly one device and is highly reusable |
| Action | A device endpoint, dynamically generated based on the interface - used in steps and contains no additional logic |
Once started, a workflow creates a Run; a single execution of a workflow. Workflows, phases and steps should be versioned with Git. To enhance reusability across workflows, we recommend creating a library of reusable phases and steps.
A minimal example
from unitelabs.sdk import __version__ as sdk_version
from unitelabs.sdk import (
get_logger,
workflow,
)
@workflow(
name="Hello World",
retries=0,
)
async def hello_world_flow(recipient_name: str = "world") -> None:
"""
Log a greeting and SDK version info to confirm the environment works.
Args:
recipient_name: Name to greet (default: "world").
"""
logger = get_logger()
logger.info(f"Hello, {recipient_name}!")
logger.info(f"UniteLabs SDK: {sdk_version}")
The @workflow decorator registers the function with the workflow engine. Phases are called like regular Python functions; the workflow engine handles scheduling, parallelism, and recovery.
What a workflow is responsible for
- Scientific goal: defined by the result it produces, not the hardware it uses
- Control flow: supports loops, conditionals, and branching
- State ownership: the single source of truth for sample identity, lineage, and consumed resources across all phases
Concepts
- Workflow: full reference
- Phase: logical stages and checkpoints
- Step: device-level atomic operations
- Runs: what happens when a workflow executes
- Human in the Loop: pausing for manual input
Run locally or on the platform
The same workflow file runs in both places. During development, run it directly from your IDE or terminal. The pyproject.toml defines a script that calls the workflow, so you ca just run it like this:
uv run workflow
When you're ready for scheduled, tracked, or team-accessible runs, deploy the same file to the platform, with no code changes required. See Deploy a workflow for the deployment steps.
Next steps
- Your first workflow: write and run a workflow end to end
- Deploy a workflow: register and run it on the platform