Script Authoring

7 min

A Cellario OS script is an async Python function decorated with @Main. The platform executes it as a workflow step, injecting an IAsyncScriptingApi context object and any configured input parameters, then recording the returned outputs.

Platform limits

Constraint	Value
Execution timeout	30 minutes
Outbound HTTP	Public endpoints only — private/on-prem hosts are not reachable
Third-party packages	Public PyPI only — the Cellario private index is not available at runtime
Python version	3.13+

Script structure

import json
from dataclasses import dataclass
from typing import Annotated

from hrb_scripting_api.scripting_api import IAsyncScriptingApi
from hrb_scripting_api.scripting_decorators import InParam, Main, OutParam


@dataclass
class Result:
    message: Annotated[
        str,
        OutParam(display_name="Message", description="Human-readable result summary"),
    ]


@Main
async def my_script(
    api: IAsyncScriptingApi,
    name: Annotated[str, InParam(display_name="Name", description="Name to greet")] = "",
) -> Result:
    return Result(message=f"Hello, {name}")

Key rules:

The entry function must be async def.

The first argument must be api: IAsyncScriptingApi.

The return type must be a @dataclass with Annotated[T, OutParam(...)] fields.

The workflow designer always passes a value for every parameter. Defaults on the function signature are mainly useful for local testing and direct invocation outside the platform.

display_name and description are optional on both InParam and OutParam, but providing them improves the experience in the workflow designer.

Do not use from __future__ import annotations. The Cellario executor loads scripts via importlib without registering them in sys.modules. Stringized annotations cause @dataclass to crash on type resolution at runtime. Remove this import if your editor adds it automatically.

Supported I/O types

Not all Python types round-trip through the platform correctly.

Type	Input	Output	Notes
str	✅	✅
int	✅	✅
float	✅	✅
bool	✅	✅	Used for loop control — see Patterns
datetime	❌	✅	Inputs are silently dropped; accept str and parse manually
list[T]	❌	❌	Silently dropped; pass JSON strings instead — see Patterns
dict	❌	❌	Silently dropped; pass JSON strings instead

The api object

IAsyncScriptingApi exposes the following at runtime:

api.workflow_order_id       # str — UUID of the current workflow order
api.workflow_order_step_id  # str — UUID of the current step
api.token                   # str — bearer token for the current session
api.secrets["key"]          # str — vault secret; returns "" for missing keys

api.data                    # Data API client (cellario_cloud_data)
api.blob_storage            # Blob Storage client (cellario_cloud_blob_storage)
api.events                  # Events client (cellario_cloud_events)
api.lab_services            # Lab Services client (cellario_cloud_lab_services)

Declaring dependencies

Scripts are deployed with a requirements.txt file in their directory. List only public PyPI packages here. Platform packages (hrb_scripting_api, cellario_cloud_*) are injected by the runtime — do not list them.

# requirements.txt

# hrb_scripting_api and cellario_cloud_* are provided by the Cellario runtime.
# List only third-party PyPI packages below.
httpx==0.28.1
tenacity==9.1.4
marshmallow==4.3.0
marshmallow-dataclass==8.7.1

For local development, declare the full set of packages in pyproject.toml with the Cellario private index, and use uv sync to install them. The requirements.txt files are only used by the cloud runtime.

# pyproject.toml
[project]
dependencies = [
    "hrb_cloud_script_python-os117>=1.0.0,<2.0.0",
    "httpx>=0.28.1",
    "tenacity>=9.1.4",
]

[[tool.uv.index]]
url = "https://artifacts.cellario.cloud/artifactory/api/pypi/pypi-libraries-local/simple"

The (default) sentinel

When a str input parameter has no configured value in the workflow designer, the platform passes the literal string "(default)". Numeric types receive 0 and booleans receive False. Normalize string parameters early:

def _param(value: str) -> str:
    v = value.strip()
    return "" if v == "(default)" else v