Scripting API — Reference

20 min

Main

Main(func)

Decorator to mark the main entry point function of a script. Needs the return type to be annotated to know how to serialize the return value.

Example:

@dataclass
class MyResult:
    output1: int
    output2: str

@Main
def Execute(...) -> MyResult:
    ...

Parameter	Type	Default
func

InParam

Describe a parameter metadata for the main entry point function of a script.

Instances of this class are intended to be used as metadata inside typing.Annotated on function parameters. Example:

from typing import Annotated
@Main
def Execute(
    foo: Annotated[str, InParam(description="the foo parameter", default="abc")],
) -> MyResult:
    ...

description: Optional[str] = None # The description of the parameter display_name: Optional[str] = None # A user-friendly name for the parameter choices: Optional[list[Any]] = None # Allowed choices for the parameter, these are displayed to the user but not enforced

The host can call get_param_metadata(Execute) to obtain a mapping of parameter name -> Param instance.

Attribute	Type	Description
description	Optional[str]
display_name	Optional[str]
choices	Optional[list[Any]]

OutParam

Describes an output parameter metadata for the main entry point function of a script.

Instances of this class are intended to be used as metadata inside typing.Annotated on function output's dataclass's fields. Example:

from typing import Annotated

@dataclass
class MyResult:
    output1: Annotated[int, OutParam("Description of output1", "Output 1")]
    output2: Annotated[str, OutParam("A string output")]

@Main
def Execute() -> MyResult:
    ...

Attribute	Type	Description
description	Optional[str]
display_name	Optional[str]

get_in_param_metadata

get_in_param_metadata(func) -> Dict[str, InParam]

Extract InParam metadata from a function's parameter annotations.

Looks for typing.Annotated[...] annotations and returns a dict mapping parameter name to the InParam instance if present. Parameters without a InParam annotation are omitted.

Parameter	Type	Default
func

Returns: Dict[str, InParam]

get_in_param_defaults

get_in_param_defaults(func, input_params: Dict[str, Any]) -> Dict[str, Any]

Return a mapping of parameter name -> default (from InParam or signature).

Priority: InParam.default (if set) -> function signature default -> None

Parameter	Type	Default
func
input_params	Dict[str, Any]

Returns: Dict[str, Any]

get_out_param_metadata

get_out_param_metadata(return_type: Type) -> Dict[str, OutParam]

Extract OutParam metadata from a function's parameter annotations.

Looks for typing.Annotated[...] annotations and returns a dict mapping field name to the OutParam instance if present. Fields without a OutParam annotation are omitted.

Parameter	Type	Default
return_type	Type

Returns: Dict[str, OutParam]

IAsyncScriptingApi

Protocol for the Cellario OS scripting API parameter. This is required to be the first type of your first parameter in your main script function. For example:

from typing import Annotated
from hrb_scripting_api.scripting_api import IAsyncScriptingApi
from hrb_scripting_api.scripting_decorators import Main, Param
from dataclasses import dataclass

@dataclass
class MyResult:
    output1: int
    output2: str

@Main
def Execute(
    api: IAsyncScriptingApi,
    foo: Annotated[str, Param("the foo parameter", default="abc")],
) -> MyResult:
    ...

Attribute	Type	Description
workflow_order_id	str	Unique identifier of this particular executing workflow's order.
workflow_order_step_id	str	Unique identifier of this workflow's order's currently executing step.
order_asset_id	str	Unique identifier of this particular executing workflow's protocol order.
order_id	str	Identifier for the executing workflow's protocol order's operation identifier.
operation_id	str	Unique identifier for this operation step within this particular executing workflow.
token	str	Authentication/authorization token for the script runtime (opaque).
all_parameters	Dict[str, Any]	A mapping of all available parameters (string -> Any).
secrets	SecretsAccessor	Flat key-value secrets injected from a key vault. Usage: api.secrets["my-api-key"]
data	DataAPI	Cellario data-access API client, authenticated and ready to use.
events	EventsAPI	Cellario events API client, authenticated and ready to use.
blob_storage	BlobStorageAPI	Cellario blob storage API client, authenticated and ready to use.
lab_services	LabServicesAPI	Cellario lab services API client, authenticated and ready to use.
platform	PlatformAPI	Cellario platform API client, authenticated and ready to use.

IAsyncScriptingApi.set_break_point

set_break_point(self) -> None

Allow the host to set a break point in the running script for local debugging when a debugger is attached. Implementations may be no-ops in production.

Returns: None

SecretsAccessor

Key-value access to flat secrets injected from a key vault.

Usage: api.secrets["my-api-key"]

SecretsAccessor.get

get(self, key: str, default: str = '') -> str

Parameter	Type	Default
key	str
default	str	''

Returns: str

LabwareLocation

Attribute	Type	Description
deviceId	Optional[str]
deviceName	Optional[str]
column	Optional[int]
row	Optional[int]
description	Optional[str]

LabwareSetEntry

Attribute	Type	Description
barcode	str
labwareTypeId	Optional[str]
location	Optional[LabwareLocation]

LabwareSetV2Entry

Attribute	Type	Description
barcode	str
labwareId	Optional[str]
labwareTypeId	Optional[str]
currentLocation	Optional[LabwareLocation]
destinationLocation	Optional[LabwareLocation]

LabwareSetV2

Attribute	Type	Description
id	str
moveOperation	bool
entries	list[LabwareSetV2Entry]

LabwareMoveEntry

Attribute	Type	Description
barcode	str
labwareTypeId	Optional[str]
from_	Optional[LabwareLocation]
to	Optional[LabwareLocation]