Script Authoring
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.
Supported I/O types
Not all Python types round-trip through the platform correctly.
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.1For 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