Scripting API — Reference
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) -> NoneAllow 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 = '') -> strParameter | 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] | |