Skip to main content
Run your own Python code inside Aire Labs models. A container function is a Docker image that reads inputs from the model, runs your computation, and writes results back. You bring the Python code; the platform handles the rest. Start by running a working example that computes Levelized Cost of Energy (LCOE) from bundled solar and wind cost data, then adapt it for your own computation. It is the Python counterpart of the R example and produces identical results. Terminal commands assume macOS or Linux.

1. Prerequisites

Install OrbStack (recommended for macOS), Docker Desktop, or Docker Engine for Linux, and make sure it is running:
You should see Hello from Docker! in the output.

2. Quick start

Clone the example and build the image:
Run it with a sample input file. This simulates what the platform does: it writes the inputs to a JSON file, runs your container, and reads the results back.
You should see: OK — dataset=solar, year=2027, lcoe=43.39 USD/MWh
Inspect the output your code produced:
The platform reads this file after your container exits and writes each result back into the model. Inputs and Outputs explains the file format, the value types, and how input names map to terms in your model.

3. The Python code

The example separates the model from the platform plumbing:

main.py — the entry point

main.py
The full file also returns an error result for a non-positive discount rate, and wraps main() so any exception exits with code 1. A non-zero exit tells the platform the run failed.

lcoe/airelabs.py — the helpers

Reads the input JSON and writes the output JSON, converting the platform’s decimal strings to and from Python numbers:
  • read_hook_input() returns the list of input parameters.
  • require_number(), require_string(), require_boolean(), require_date() extract one parameter by name and raise if it is missing.
  • number_result(), number_array_result(), string_result(), boolean_result(), date_result(), error_result() build result entries.
  • write_hook_output() writes the results file.
Keep your business logic in modules like model.py with no platform dependencies. You can then develop and test it in a REPL or notebook exactly as you normally would, and main.py stays a thin wrapper.

lcoe/data_lookup.py — bundled data

Containers have no network access when they run, so reference data is built into the image. data_lookup.py resolves data/ relative to its own file, not the working directory, and raises a clear error for an unknown dataset or year. See No Internet: Bundling Data for why and for how to bring in data from remote sources.

4. Different inputs

Copy a different fixture into /tmp/airelabs/hook-input.json and re-run the docker run command from the quick start. Run the tests inside the image:

5. Writing your own function

  1. Write your model as plain Python that takes arguments and returns values.
  2. Edit main.py to read the parameters your model needs with the require_* helpers and write its results with the *_result helpers.
  3. Add a fixture in fixtures/ with the parameters your model expects.
  4. Add dependencies to dependencies in pyproject.toml, then run uv lock. They are installed when the image is built.
  5. Rebuild and run with docker build and the same docker run command, using your fixture.

6. The Dockerfile

The example uses the official uv image and installs the locked dependencies at build time:
Dockerfile
  • uv sync --locked installs exactly the versions in uv.lock, so every build gets the same packages.
  • COPY . /app copies your code, data/, and fixtures into the image.
  • CMD runs your entry point. It is a CMD, not an ENTRYPOINT, so you can override it locally, as the test commands above do.
The platform runs linux/amd64 images. If you build on Apple Silicon, build with docker build --platform linux/amd64 before you publish. The publishing workflow does this for you.

7. Develop with moon

The docker commands above need nothing but Docker. The example repository also defines its test, lint, build, and release steps as moon tasks. moon installs the pinned Python and uv versions, keeps the virtual environment in sync with uv.lock, and skips a task when its inputs have not changed since the last run. The same tasks run in the repository’s GitHub Actions, so a green run on your machine means a green run in CI. Install proto, the toolchain manager, then provision the pinned versions from the repository root:
This installs the moon, Python, and uv versions pinned in .prototools. There is no separate install step: moon runs uv sync before each task when the lockfile has changed. lcoe:build prints the name of the image it built. Use that name in place of lcoe-python in the docker run commands above. To publish with lcoe:release, pass your organization ID and an API key with Registry Push permission (see Publishing Container Functions), and set RELEASE_ENV=production. Your organization ID is the part of your registry hostname between org- and .registry:
This pushes org-<your-org-id>.registry.airelabs.run/lcoe-python:v1.2.0. Set IMAGE_REPO to publish under a different image name. Without RELEASE_VERSION, the tag is the git tag on the current commit, or branch-<branch>-<short-sha> if there is none.
RELEASE_ENV defaults to stage, an Aire Labs internal registry. Always set RELEASE_ENV=production to publish to your organization’s registry.

8. What’s next

Once your function works locally, publish it so your models can run it. Publishing Container Functions from GitHub sets up a GitHub Actions workflow that builds and pushes a new image every time you push a git tag. The workflow is the same for Python and R.