This repository contains a cookiecutter template for MAGNET integration Python packages. This includes a Python package directory structure and boilerplate support files.

Setup

Install uv, installation instructions.

The uvx command will allow us to run cookiecutter without installing it in an existing Python environment.

(Note that we also use uv for Python virtual environment management)

Generate

The uvx cookiecutter command can be run against a local copy of this repository:

git clone https://github.com/AIQ-Kitware/magnet-integration-template.git
uvx cookiecutter magnet-integration-template

Or against the hosted repository directly:

uvx cookiecutter https://github.com/AIQ-Kitware/magnet-integration-template

You'll be asked to fill out several variables such as package_name and package_description, which will be used in populating the output directory and package files. For package_name, we recommend including your team name and TA designation, e.g. "jhu_ta1" or "aiq_jhu_ta1".

Note: Throughout the remainder of this document, when referring to <variable_name> (e.g. <package_name>) that we mean whatever value was entered into cookiecutter during setup (e.g. "example_magnet_integration_package").

Output

Once the command has finished you should have an output directory with the same name as the package_name you designated. With roughly the following structure (omitting some files here for brevity):

example_magnet_integration_package
├── Dockerfile
├── example_magnet_integration_package
│   ├── algorithms
│   ├── backends
│   │   └── helm
│   │       ├── run_specs
│   │       └── scenarios
│   └── cards
├── pyproject.toml
└── README.md

This output package should be immediately pip-installable.

The rest of this section identifies the files and directories that likely need further modification as you develop and add your algorithms and evaluation cards.

pyproject.toml

This is the primary file that defines your Python module. Most of it can be left as-is, but you'll likely need / want to add your own Python dependencies (note that the MAGNET Framework is included in dependencies list by default):

...
dependencies = [
    # The [optional] flag here is used to include optional
    # dependencies in the aiq-magnet install (needed for the HELM
    # download utility)
    "aiq-magnet[optional] @ git+https://github.com/AIQ-Kitware/aiq-magnet",
    # We have a version of `aiq-magnet` hosted on PyPI and intend to
    # push semi-regular updates there once the API stabalizes.  For
    # now, pointing to the GitHub repository will be sure to get you
    # the latest version.  If you want to use the PyPI version,
    # comment out the above line and uncomment this one:
    # "aiq-magnet[optional]",
    # Add your other Python dependencies here
]

Custom HELM run_specs

(This section is largely for TA2 teams or TA1 teams that intend to define their own custom datasets etc. that aren't already available through HELM)

We use Python entry-points to make custom HELM run_spec definitions available when using HELM via MAGNET.

...
[project.entry-points."helm.run_specs"]
run_specs = "<package_name>.backends.helm.run_specs"
...

This means that any run_spec defined in the <package_name>/backends/helm/run_specs/__init__.py will be made available. Note that this file is empty by default, if you were to add a custom run_spec (e.g. <package_name>/backends/helm/run_specs/my_run_spec.py) you'll want import it in the aformentioned __init__.py file, or add it directly to the [project.entry-points."helm.run_specs"] section in pyproject.toml:

# In <package_name>/backends/helm/run_specs/__init__.py
from <package_name>/backends/helm/run_specs/my_run_spec import my_run_spec

Or ..

[project.entry-points."helm.run_specs"]
run_specs = "<package_name>.backends.helm.run_specs"
my_run_spec = "<package_name>.backends.helm.run_specs.my_run_spec"

If you need to define and use custom HELM scenarios (should be placed in <package_name>/backends/helm/scenarios), that need to be referenced by your custom run_specs, you'll want to import and reference them as:

from <package_name>.backends.helm.scenarios.my_scenario import my_scenario

Dockerfile

This file is intentionally left empty for now (apart from a # Placeholder comment). If your algorithms require particular system libraries or tools, a Dockerfile is likely necessary to capture those in a reproducable way. Please reach out to the Kitware AIQ team for more details and we will work with you there.

<package_name>/backends/helm/run_specs

Put your custom HELM run_specs in this directory.

<package_name>/backends/helm/scenarios

Put your custom HELM scenarios in this directory.

<package_name>/algorithms

Put your algorithm code here (e.g. predictor implementations).

<package_name>/cards

Put your evaluation card YAML files here.

Complete Integration Example

We maintain a real integration example here for reference.