artificial.workflows.decorators#

@action(
capability: str,
name: str,
display_name: str = '',
default_duration: int = 0,
description: str = '',
)#

Generic decorator for a function describing an action reachable via the given capability and action name.

Parameters:

  • capability – the name of the capability required to execute the action

  • name – the name of the action known to its executor

  • display_name – the name to display in LabOps for the action. Defaults to empty; the display name will be substrate_name if this is empty.

  • default_duration – the default estimate for the duration of the action in seconds.

  • description – display description for the action.

@action_reference#

Decorator for a function referencing an externally-defined action with the given id.

Parameters:

id – the id of the externally-defined action

@actor_parameter(
parameter_name: str,
possible_actor_references: list,
config: Dict = None,
)#

Decorator for a workflow indicating that one of its parameters corresponds to a reference to an actor selected during job scheduling. This parameter may be used to branch based on the id of the selected actor at runtime.

Parameters:

  • parameter_name – the name of the associated Python parameter

  • possible_actor_references – a list of references to possible actors; branching on the actor id must exhaustively check this list.

@batching_action#

Decorator for a batching action associated with a workflow.

For a workflow that takes a single parameter of type P, the batching action is expected to take List[P] and return P.

Org action:

the batching action function; this should be annotated with @action.

@batching_validation_action#

Decorator for a batching validation action associated with a workflow.

For a workflow that takes a single parameter of type P, the batching action is expected to take List[P] and return artificial.workflows.validation.ValidationResponse.

Org action:

the batching validation action function; this should be annotated with @action.

@config_parameter(parameter_name: str, config_parameter_name: str)#

Decorator for an action function indicating that one of its parameters corresponds to a property in the generated action’s action_config.

Parameters:

  • parameter_name – the name of the associated Python parameter

  • config_parameter_name – the key to add to the generated action’s action_config

@config_type#

Decorator for a workflow indicating the dataclass type that defines its workflow config type. Config types will be transformed into a config JSON schema that will be included in the generated workflow data and registered with the config service on import. Calling get_job_config returns a reference whose usage is equivalent to reading a value of type config_class from the config service.

Parameters:

config_class – a reference to a dataclass that defines the config type for the workflow.

@field(field_name: str, config: dict = {})#

Optional decorator for a struct class (dataclass) corresponding to a field. Struct fields should be annotated with a type; currently allowed types are bool, int, float, str, datetime, bytes, enum classes, struct (dataclass) classes containing allowed types, and Lists or Sets of allowed types.

Parameters:

  • field_name – the name of the associated field

  • config –

    dict of properties describing how to configure the field in an ActionParameter’s type. Allowed properties:

    • readonly: bool: whether the value UI for the field is readonly

    • description: str: user description of field

    • uiTitle: str: the label to show on the field UI

    • uiWidget: str: the type of UI widget to show for the field. Allowed: ‘none’, ‘text’, ‘numeric’, ‘file’, ‘switch’, ‘select’, ‘checkbox’, ‘filePicker’, ‘jsonFilePicker’, ‘datePicker’, ‘table’, ‘arrayInput’

    • alwaysDisplay: bool: whether to ensure this field displays in abbreviated parameter views

    • formatting: str: for numeric fields, a printf-style string indicating how to format the value

    • range: {'min':float, 'max':float, 'step':float}: for float fields, the range of valid values

    • pattern: str: for str fields, a regex matching valid values

    • minLength/maxLength: int: for str parameters, the minimum or maximum length of the string

    • minItems/maxItems: int: for List/Set parameters, the minimum or maximum number of elements

    • element: dict: for List/Set fields, the config dict to apply to the element type

    • csvTag: dict{'sourceColumnRegex':str, 'targetJsonPointer':str, 'allowEmpty':bool?}: indicates that the field corresponds to a CSV

      column whose name matches sourceColumnRegex, and should be mapped to targetJsonPointer. Mutually exclusive with jsonTag.

    • jsonTag: dict{'sourceJsonPointer':str, 'targetJsonPointer':str, 'allowEmpty':bool?}: indicates that the field corresponds to a JSON

      key named sourceJsonPointer, and should be mapped to targetJsonPointer. Mutually exclusive with csvTag.

@parameter(
parameter_name: str,
config: dict = {},
parameter_id: str = None,
action_parameter_name: str = None,
)#

Decorator for an action function’s parameter bound to an ActionParameter. Either this should reference an externally-defined ActionParameter by id (e.g. for an assistant), or the associated Python parameter should be annotated with a type; currently allowed types are bool, int, float, str, datetime, bytes, enum classes, struct (dataclass) classes containing allowed types, and Lists or Sets of allowed types.

Parameters:

  • parameter_name – the name of the associated Python parameter

  • config –

    dict of properties describing how to show the parameter in the request module. Allowed properties:

    • required: bool: whether a value for the parameter must be supplied

    • readonly: bool: whether the value UI for the parameter is readonly

    • description: str: user description of parameter

    • uiTitle: str: the label to show on the parameter UI

    • uiWidget: str: the type of UI widget to show for the parameter. Allowed: ‘none’, ‘text’, ‘numeric’, ‘file’, ‘switch’, ‘select’, ‘checkbox’, ‘filePicker’, ‘jsonFilePicker’, ‘datePicker’, ‘table’, ‘arrayInput’

    • alwaysDisplay: bool: whether to ensure this parameter displays in abbreviated parameter views

    • formatting: str: for numeric parameters, a printf-style string indicating how to format the value

    • range: {'min':float, 'max':float, 'step':float}: for float parameters, the range of valid values

    • pattern: str: for str parameters, a regex matching valid values

    • minLength/maxLength: int: for str parameters, the minimum or maximum length of the string

    • minItems/maxItems: int: for List/Set parameters, the minimum or maximum number of elements

    • preCreate: bool: parameter supplied during request creation

    • preBatch: bool: parameter supplied during job creation before batching requests

    • postBatch: bool: parameter supplied during job creation after batching requests

    • preSchedule: bool: parameter supplied during scheduling

    • element: dict: for List/Set parameters, the config dict to apply to the element type

  • parameter_id – if supplied, indicates the id of an externally-defined ActionParameter to reference (e.g. for an assistant).

  • action_parameter_name – if supplied, indicates the name of an externally-defined ActionParameter to reference (e.g. for an assistant).

@return_parameter(
return_parameter_name: str | List[str] = None,
parameter_id: str | List[str] = None,
action_parameter_name: str | List[str] = None,
)#

Decorator for an action function indicating that its return value is bound to one or more ActionParameters Either this should reference externally-defined ActionParameters by id or name (e.g. for an assistant), or the function must be annotated with a return type; currently allowed types are bool, int, float, str, datetime, bytes, enum classes, struct (dataclass) classes containing allowed types, Lists or Sets of allowed types, or Tuples of allowed non-Tuple types indicating multiple return values. When multiple return values are defined, a parameter name or id must be specified for each one in tuple element order.

Parameters:

  • return_parameter_name – if supplied, the names of output ActionParameters to create for the return value.

  • parameter_id – if supplied, the ids of output ActionParameters to reference (e.g., for an assistant).

  • action_parameter_name – if supplied, the names of externally-defined ActionParameters to reference (e.g. for an assistant)

@system_name#

Optional decorator for a struct class (dataclass) indicating a system name to tag corresponding ActionParameter types with, to allow the parameter type to be recognizable to the system.

Parameters:

name – the system name to tag ActionParameter types created from this struct with

@workflow(
name: str,
id: str,
labId: str = '',
interactive: bool = True,
from_file: bool = False,
quick: bool | None = None,
recurrent: bool = False,
description: str = '',
programmatically_schedulable: bool = False,
)#

Decorator for a function to transform into a workflow.

Parameters:

  • name – the display name of the created workflow

  • id – the id of the created workflow. Should be unique among actions created within the workflow’s org

  • labId – the id of the lab in which the workflow will run

  • interactive – whether jobs can be created with the request creation UI; defaults to True

  • from_file – whether jobs can be created from file uploads from the workflow in ops; defaults to False

  • quick –

    whether jobs can be created with the quick job creation UI; defaults to None.

    None

    The workflow will be marked quick unless it contains parameters marked preSchedule.

    False

    The workflow will not be marked quick.

    True

    The workflow will be marked quick, or an error reported if the workflow contains parameters marked preSchedule.

  • recurrent – whether jobs can be created with the recurring schedule UI; defaults to False. Only parameterless workflows may be used in recurring schedules.

  • description – the display description of the created workflow

  • programmatically_schedulable –

    whether jobs can’t be scheduled with new job creation UI; defaults to False.

    False

    The workflow will show up in the job creation UI.

    True

    The workflow will NOT show up in the job creation UI.

@workflow_validation(stage: str, action: Callable, config: Dict = {})#

Decorator for a validation action associated with a workflow.

Parameters:

  • stage – the name of the stage at which the validation action will run; allowed values are ‘preCreate’, ‘postCreate’, ‘preBatch’, ‘postBatch’, ‘preSchedule’, ‘postSchedule’

  • action – the validation action function; this should be annotated with @action or @substrateAction.

  • config – a config dict to attach to the validation action instance.