5821 Add interface for bundle workflows (#5822)

Fixes #5821 .

### Description

The main idea of this PR is to solve 3 pain points of the current bundle
training or inference workflow:
1. Training or inference is defined in a "rigid" `training` or
`evaluation` list, so 3rd party package can't flexibly initialize and
run the workflows separately, see:
Project-MONAI/model-zoo#294. This PR splits it
into `initialize`, `run` and `finalize`, and still compatible with
current existing bundles.
2. 3rd party packages need to access the bundle config directly with
specifed keys based on `ConfigParser`, but some developers of bundles
don't want to write JSON or YAML configs. This PR implemented the
interface to support both config-based and python-based workflows.
3. MONAI Label, MONAI deploy, MONAI-FL require many fixed properties of
a training or inference workflow, but we don't have definition for them
in the code, just described in the developer guide doc of model-zoo.
This PR implemented the `TrainProperties` and `inferenceProperties`
interfaces and check tool.

### Types of changes
<!--- Put an `x` in all the boxes that apply, and remove the not
applicable items -->
- [x] Non-breaking change (fix or new feature that would not break
existing functionality).
- [ ] Breaking change (fix or new feature that would cause existing
functionality to change).
- [ ] New tests added to cover the changes.
- [ ] Integration tests passed locally by running `./runtests.sh -f -u
--net --coverage`.
- [ ] Quick tests passed locally by running `./runtests.sh --quick
--unittests --disttests`.
- [ ] In-line docstrings updated.
- [ ] Documentation updated, tested `make html` command in the `docs/`
folder.

---------

Signed-off-by: Nic Ma <nma@nvidia.com>
Signed-off-by: root <root@apt-sh-ai.nvidia.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: root <root@apt-sh-ai.nvidia.com>

monai/bundle/__init__.py

@@ -13,6 +13,7 @@
 
 from .config_item import ComponentLocator, ConfigComponent, ConfigExpression, ConfigItem, Instantiable
 from .config_parser import ConfigParser
+from .properties import InferProperties, TrainProperties
 from .reference_resolver import ReferenceResolver
 from .scripts import (
     ckpt_export,
@@ -22,7 +23,6 @@
     get_bundle_versions,
     init_bundle,
     load,
-    patch_bundle_tracking,
     run,
     verify_metadata,
     verify_net_in_out,
@@ -36,3 +36,4 @@
     MACRO_KEY,
     load_bundle_config,
 )
+from .workflows import BundleWorkflow, ConfigWorkflow

monai/bundle/properties.py

@@ -0,0 +1,192 @@
+# Copyright (c) MONAI Consortium
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+The predefined properties for a bundle workflow, other applications can leverage the properties
+to interact with the bundle workflow.
+Some properties are required and some are optional, optional properties mean: if some component of the
+bundle workflow refer to the property, the property must be defined, otherwise, the property can be None.
+Every item in this `TrainProperties` or `InferProperties` dictionary is a property,
+the key is the property name and the values include:
+1. description.
+2. whether it's a required property.
+3. config item ID name (only applicable when the bundle workflow is defined in config).
+4. reference config item ID name (only applicable when the bundle workflow is defined in config).
+
+"""
+
+from __future__ import annotations
+
+from monai.bundle.utils import ID_SEP_KEY
+from monai.utils import BundleProperty, BundlePropertyConfig
+
+TrainProperties = {
+    "bundle_root": {
+        BundleProperty.DESC: "root path of the bundle.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: "bundle_root",
+    },
+    "device": {
+        BundleProperty.DESC: "target device to execute the bundle workflow.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: "device",
+    },
+    "dataset_dir": {
+        BundleProperty.DESC: "directory path of the dataset.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: "dataset_dir",
+    },
+    "trainer": {
+        BundleProperty.DESC: "training workflow engine.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}trainer",
+    },
+    "max_epochs": {
+        BundleProperty.DESC: "max number of epochs to execute the training.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}trainer{ID_SEP_KEY}max_epochs",
+    },
+    "train_dataset": {
+        BundleProperty.DESC: "PyTorch dataset object for the training logic.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}dataset",
+    },
+    "train_dataset_data": {
+        BundleProperty.DESC: "data source for the training dataset.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}dataset{ID_SEP_KEY}data",
+    },
+    "train_inferer": {
+        BundleProperty.DESC: "MONAI Inferer object to execute the model computation in training.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}inferer",
+    },
+    "train_handlers": {
+        BundleProperty.DESC: "event-handlers for the training logic.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}handlers",
+        BundlePropertyConfig.REF_ID: f"train{ID_SEP_KEY}trainer{ID_SEP_KEY}train_handlers",
+    },
+    "train_preprocessing": {
+        BundleProperty.DESC: "preprocessing for the training input data.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}preprocessing",
+        BundlePropertyConfig.REF_ID: f"train{ID_SEP_KEY}dataset{ID_SEP_KEY}transform",
+    },
+    "train_postprocessing": {
+        BundleProperty.DESC: "postprocessing for the training model output data.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}postprocessing",
+        BundlePropertyConfig.REF_ID: f"train{ID_SEP_KEY}trainer{ID_SEP_KEY}postprocessing",
+    },
+    "train_key_metric": {
+        BundleProperty.DESC: "key metric to compute on the training data.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"train{ID_SEP_KEY}key_metric",
+        BundlePropertyConfig.REF_ID: f"train{ID_SEP_KEY}trainer{ID_SEP_KEY}key_train_metric",
+    },
+    "evaluator": {
+        BundleProperty.DESC: "validation workflow engine.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"validate{ID_SEP_KEY}evaluator",
+        BundlePropertyConfig.REF_ID: "validator",  # this REF_ID is the arg name of `ValidationHandler`
+    },
+    "val_interval": {
+        BundleProperty.DESC: "validation interval during the training.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: "val_interval",
+        BundlePropertyConfig.REF_ID: "interval",  # this REF_ID is the arg name of `ValidationHandler`
+    },
+    "val_handlers": {
+        BundleProperty.DESC: "event-handlers for the validation logic.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"validate{ID_SEP_KEY}handlers",
+        BundlePropertyConfig.REF_ID: f"validate{ID_SEP_KEY}evaluator{ID_SEP_KEY}val_handlers",
+    },
+    "val_dataset": {
+        BundleProperty.DESC: "PyTorch dataset object for the validation logic.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"validate{ID_SEP_KEY}dataset",
+        BundlePropertyConfig.REF_ID: f"validate{ID_SEP_KEY}dataloader{ID_SEP_KEY}dataset",
+    },
+    "val_dataset_data": {
+        BundleProperty.DESC: "data source for the validation dataset.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"validate{ID_SEP_KEY}dataset{ID_SEP_KEY}data",
+        BundlePropertyConfig.REF_ID: None,  # no reference to this ID
+    },
+    "val_inferer": {
+        BundleProperty.DESC: "MONAI Inferer object to execute the model computation in validation.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"validate{ID_SEP_KEY}inferer",
+        BundlePropertyConfig.REF_ID: f"validate{ID_SEP_KEY}evaluator{ID_SEP_KEY}inferer",
+    },
+    "val_preprocessing": {
+        BundleProperty.DESC: "preprocessing for the validation input data.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"validate{ID_SEP_KEY}preprocessing",
+        BundlePropertyConfig.REF_ID: f"validate{ID_SEP_KEY}dataset{ID_SEP_KEY}transform",
+    },
+    "val_postprocessing": {
+        BundleProperty.DESC: "postprocessing for the validation model output data.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"validate{ID_SEP_KEY}postprocessing",
+        BundlePropertyConfig.REF_ID: f"validate{ID_SEP_KEY}evaluator{ID_SEP_KEY}postprocessing",
+    },
+    "val_key_metric": {
+        BundleProperty.DESC: "key metric to compute on the validation data.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: f"validate{ID_SEP_KEY}key_metric",
+        BundlePropertyConfig.REF_ID: f"validate{ID_SEP_KEY}evaluator{ID_SEP_KEY}key_val_metric",
+    },
+}
+
+
+InferProperties = {
+    "bundle_root": {
+        BundleProperty.DESC: "root path of the bundle.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: "bundle_root",
+    },
+    "device": {
+        BundleProperty.DESC: "target device to execute the bundle workflow.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: "device",
+    },
+    "network_def": {
+        BundleProperty.DESC: "network module for the inference.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: "network_def",
+    },
+    "inferer": {
+        BundleProperty.DESC: "MONAI Inferer object to execute the model computation in inference.",
+        BundleProperty.REQUIRED: True,
+        BundlePropertyConfig.ID: "inferer",
+    },
+    "preprocessing": {
+        BundleProperty.DESC: "preprocessing for the input data.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: "preprocessing",
+        BundlePropertyConfig.REF_ID: f"dataset{ID_SEP_KEY}transform",
+    },
+    "postprocessing": {
+        BundleProperty.DESC: "postprocessing for the model output data.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: "postprocessing",
+        BundlePropertyConfig.REF_ID: f"evaluator{ID_SEP_KEY}postprocessing",
+    },
+    "key_metric": {
+        BundleProperty.DESC: "the key metric during evaluation.",
+        BundleProperty.REQUIRED: False,
+        BundlePropertyConfig.ID: "key_metric",
+        BundlePropertyConfig.REF_ID: f"evaluator{ID_SEP_KEY}key_val_metric",
+    },
+}