Skip to main content
A container function is a pure function of named values. Your model passes it a list of named inputs, your code computes, and it returns a list of named results. Your code never sees terms, node IDs, or the model itself. Only names and values cross the boundary, so the same image works in any model.

How inputs reach your code

When you configure a container function block, you add one input row per parameter your code reads. Each row has:
  • A parameter name, such as discount_rate. Your code looks the value up by this name. Names must start with a letter or underscore and contain only letters, digits, and underscores.
  • A term in the model that supplies the value. It can be any term: a manual input, a formula result, or an output of another container function.
  • An optional “send as” unit. The platform converts the term’s value to this unit before your code sees it. If the units are dimensionally incompatible (USD into MWh, for example), the run fails instead of passing a wrong number.
Before each run, the platform reads the current value of every mapped term and writes them all to a JSON file at the path in AIRELABS_HOOK_INPUT_PATH:
hook-input.json
Each entry has a name and exactly one value field. The field name tells you the type.
Container functions don’t re-run automatically. When the value or unit of a mapped term changes, the block shows Needs re-run. Run it again to send the new values.

How outputs reach your model

Your code writes a JSON file to AIRELABS_HOOK_OUTPUT_PATH with a results array in the same format:
hook-output.json
Your code chooses the output names. Each result becomes an output term on the block, available to downstream formulas. You can bind a result to an existing term in the block configuration. If you don’t, the platform creates an output term for it and keeps it stable across runs. A result can be an error instead of a value. The platform shows that output as an error and propagates it downstream, while the other outputs still get their values. Use this for problems that affect one output, such as an invalid rate. For problems that make the whole run meaningless, exit with a non-zero code. The container must write the output file and exit with code 0. A non-zero exit, a missing output file, or invalid JSON marks the whole run as failed. Only standard error is captured in the run logs, so print diagnostics there.

Value types

Inputs and results use the same types. Set exactly one value field per entry.
  • Numbers are decimal strings ("0.08", not 0.08), so no precision is lost on the way. Don’t use scientific notation or thousands separators.
  • Booleans are the strings "true" and "false", not JSON booleans.
  • Timestamps are not supported. A timestamp or timestampArray result shows as the error #CONTAINER_ERR_UNSUPPORTED_TYPE. Return a date or a string instead.

Units

A number’s unit is optional. On inputs, it is the “send as” unit if you set one, or the term’s own unit otherwise. On results, the platform matches the unit name against your organization’s units. If a result’s unit is not recognized, that output shows the error #CONTAINER_ERR_UNRESOLVED_UNIT instead of a number with a wrong unit.
Set a “send as” unit on every numeric input your code does arithmetic on. Then a change to a term’s unit in the model, such as kW to MW, is converted for you instead of silently changing your results.

Declaring your function’s interface

You can publish your function’s inputs and outputs with the image, so nobody has to retype them. Add an image label named com.airelabs.schema.v1.hook whose value is a JSON description of the interface:
Pass it as a build argument, minified onto one line:
When the selected image has this label, the block configuration pre-fills the input rows with the declared names. It marks required inputs and won’t save until each one is mapped to a term. AI assist proposes a term from the model for every declared input you have not mapped yet; you review each proposal and accept or change it, so mapping a function with many inputs on a large model does not mean searching for every term by hand. It also sets the “send as” unit from each input’s unit. The tag picker shows how many inputs the image declares. Images without the label keep the free-form input list.
  • Types: CONTAINER_FUNCTION_VALUE_TYPE_ followed by QUANTITY (a number), STRING, BOOL, DATE, or the array forms QUANTITY_ARRAY, STRING_ARRAY, BOOL_ARRAY, DATE_ARRAY.
  • Input fields: name, type, required, unit, description.
  • Output fields: name, type, unit, description, label, tags.
  • Limits: the label must be valid JSON with no unknown keys and at most 32 KB. The push still succeeds when the label is invalid. The reason shows on the Container Registry page and in the block configuration, which falls back to free-form inputs.
Generate the label from your code instead of maintaining it by hand. For example, give your entry point a --describe flag that prints the schema from the same declarations your code uses to read inputs. Then the label cannot drift from the code.

Environment variables

The platform sets these before your container starts:

JSON schemas

Machine-readable schemas for the input and output files, for editor autocompletion and validation:
  • Input: https://app.airelabs.com/schemas/v1/airelabs.v1.HookInput.jsonschema.strict.bundle.json
  • Output: https://app.airelabs.com/schemas/v1/airelabs.v1.HookOutput.jsonschema.strict.bundle.json
For a complete working function, see Container Functions with Python or Container Functions with R.