Allow setting the algorithm api method (#4469)

Adds the ability to set the API method by adding a label on the
container (`org.grand-challenge.api-method`). The value of this can be
`exec` (default, set if label is missing) or `invoke` (new). The api
method is then passed through to the instance at runtime as
`GRAND_CHALLENGE_COMPONENT_API_METHOD` for pickup by SageMaker Shim.

See DIAGNijmegen/rse-roadmap#400

Author: jmsmkn

app/grandchallenge/algorithms/migrations/0090_algorithmimage_api_method_and_more.py

@@ -0,0 +1,36 @@
+# Generated by Django 5.2.10 on 2026-01-27 13:09
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("algorithms", "0089_job_algorithms__created_679c29_idx"),
+        (
+            "uploads",
+            "0009_useruploadgroupobjectpermission_uploads_use_group_i_53998e_idx",
+        ),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="algorithmimage",
+            name="api_method",
+            field=models.CharField(
+                choices=[("exec", "Exec"), ("invoke", "Invoke")],
+                default="exec",
+                editable=False,
+                max_length=6,
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="algorithmimage",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("api_method__in", ["exec", "invoke"])),
+                name="algorithms_algorithmimage_api_method_in_choices",
+            ),
+        ),
+    ]

app/grandchallenge/challenges/migrations/0001_initial.py

@@ -22,6 +22,7 @@ class Migration(migrations.Migration):
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
         ("task_categories", "0001_initial"),
         ("publications", "0003_auto_20201001_0758"),
+        ("modalities", "0001_initial"),
     ]
 
     operations = [

app/grandchallenge/challenges/models.py

@@ -47,6 +47,7 @@
     send_email_percent_budget_consumed_alert,
 )
 from grandchallenge.challenges.utils import ChallengeTypeChoices
+from grandchallenge.components.models import APIMethodChoices
 from grandchallenge.components.schemas import (
     SELECTABLE_GPU_TYPES_SCHEMA,
     GPUTypeChoices,
@@ -1323,6 +1324,7 @@ def compute_costs_euro_cents_per_hour(self):
                 requires_gpu_type=gpu_type,
                 use_warm_pool=False,
                 signing_key=b"",
+                api_method=APIMethodChoices.EXEC,
             )
             for gpu_type in self.algorithm_selectable_gpu_type_choices
         ]

app/grandchallenge/components/backends/base.py

@@ -41,6 +41,7 @@
 )
 from grandchallenge.components.backends.utils import user_error
 from grandchallenge.components.models import (
+    APIMethodChoices,
     ComponentInterface,
     ComponentInterfaceValue,
     InterfaceKindChoices,
@@ -320,6 +321,7 @@ def __init__(
         requires_gpu_type: GPUTypeChoices,
         use_warm_pool: bool,
         signing_key: bytes,
+        api_method: APIMethodChoices,
         algorithm_model=None,
         ground_truth=None,
         **kwargs,
@@ -334,6 +336,7 @@ def __init__(
             use_warm_pool and settings.COMPONENTS_USE_WARM_POOL
         )
         self._signing_key = signing_key
+        self._api_method = api_method
         self._algorithm_model = algorithm_model
         self._ground_truth = ground_truth
 
@@ -450,6 +453,7 @@ def invocation_environment(self):
             "GRAND_CHALLENGE_COMPONENT_SIGNING_KEY_HEX": binascii.hexlify(
                 self._signing_key
             ).decode("ascii"),
+            "GRAND_CHALLENGE_COMPONENT_API_METHOD": self._api_method,
         }
 
         if self._algorithm_model:

app/grandchallenge/components/models.py

@@ -24,7 +24,7 @@
     RegexValidator,
 )
 from django.db import models, transaction
-from django.db.models import IntegerChoices, QuerySet
+from django.db.models import IntegerChoices, QuerySet, TextChoices
 from django.db.transaction import on_commit
 from django.forms import ModelChoiceField
 from django.template.defaultfilters import truncatewords
@@ -1851,6 +1851,7 @@ def executor_kwargs(self):
             "memory_limit": self.requires_memory_gb,
             "use_warm_pool": self.use_warm_pool,
             "signing_key": self.signing_key,
+            "api_method": self.container.api_method,
         }
 
     def get_executor(self, *, backend):
@@ -2028,6 +2029,11 @@ class ImportStatusChoices(IntegerChoices):
     COMPLETED = 6, "Completed"
 
 
+class APIMethodChoices(TextChoices):
+    EXEC = "exec", "Exec"
+    INVOKE = "invoke", "Invoke"
+
+
 class ComponentImageManager(models.Manager):
     def executable_images(self):
         return self.filter(
@@ -2068,6 +2074,12 @@ class ComponentImage(FieldChangeMixin, models.Model):
         storage=private_s3_storage,
         max_length=255,
     )
+    api_method = models.CharField(
+        editable=False,
+        max_length=6,
+        choices=APIMethodChoices,
+        default=APIMethodChoices.EXEC,
+    )
     image_sha256 = models.CharField(editable=False, max_length=71)
     latest_shimmed_version = models.CharField(
         editable=False, max_length=8, default=""
@@ -2262,6 +2274,12 @@ def shimmed_repo_tag(self):
 
     class Meta:
         abstract = True
+        constraints = (
+            models.CheckConstraint(
+                condition=models.Q(api_method__in=APIMethodChoices.values),
+                name="%(app_label)s_%(class)s_api_method_in_choices",
+            ),
+        )
 
     @property
     def animate(self):

app/grandchallenge/components/tasks.py

@@ -627,6 +627,8 @@ def _validate_docker_image_manifest(*, instance) -> str:
             f"{desired_arch!r}."
         )
 
+    instance.api_method = _get_image_api_method(config=config)
+
     if instance._meta.model_name != "method":
         # TODO Methods are currently allowed to be duplicated
         model = apps.get_model(
@@ -736,6 +738,29 @@ def _get_image_config_file(
     return {"image_sha256": image_sha256, "config": config}
 
 
+def _get_image_api_method(*, config):
+    from grandchallenge.components.models import APIMethodChoices
+
+    label = "org.grand-challenge.api-method"
+    allowed_values = APIMethodChoices.values
+
+    labels = config["config"].get("Labels") or {}
+
+    for key, value in labels.items():
+        if str(key).lower().strip() == label:
+            cleaned_value = (
+                str(value).lower().replace("'", "").replace('"', "").strip()
+            )
+            if cleaned_value in allowed_values:
+                return cleaned_value
+            else:
+                raise ValidationError(
+                    f"The label {label} must be one of {allowed_values}, instead we found '{value}'."
+                )
+    else:
+        return APIMethodChoices.EXEC
+
+
 def lock_for_utilization_update(*, algorithm_image_pk):
     from grandchallenge.algorithms.models import AlgorithmImage
 

app/grandchallenge/evaluation/migrations/0104_method_api_method_and_more.py

@@ -0,0 +1,39 @@
+# Generated by Django 5.2.9 on 2025-12-09 15:03
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        (
+            "evaluation",
+            "0103_alter_evaluationgroundtruth_ground_truth_and_more",
+        ),
+        (
+            "uploads",
+            "0009_useruploadgroupobjectpermission_uploads_use_group_i_53998e_idx",
+        ),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="method",
+            name="api_method",
+            field=models.CharField(
+                choices=[("exec", "Exec"), ("invoke", "Invoke")],
+                default="exec",
+                editable=False,
+                max_length=6,
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="method",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("api_method__in", ["exec", "invoke"])),
+                name="evaluation_method_api_method_in_choices",
+            ),
+        ),
+    ]

app/grandchallenge/evaluation/models.py

@@ -1440,6 +1440,9 @@ class Method(UUIDModel, ComponentImage):
 
     phase = models.ForeignKey(Phase, on_delete=models.PROTECT, null=True)
 
+    class Meta(UUIDModel.Meta, ComponentImage.Meta):
+        pass
+
     def save(self, *args, **kwargs):
         adding = self._state.adding
 

app/grandchallenge/workstations/migrations/0034_workstationimage_api_method_and_more.py

@@ -0,0 +1,36 @@
+# Generated by Django 5.2.9 on 2025-12-09 15:02
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        (
+            "uploads",
+            "0009_useruploadgroupobjectpermission_uploads_use_group_i_53998e_idx",
+        ),
+        ("workstations", "0033_alter_workstation_logo"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="workstationimage",
+            name="api_method",
+            field=models.CharField(
+                choices=[("exec", "Exec"), ("invoke", "Invoke")],
+                default="exec",
+                editable=False,
+                max_length=6,
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="workstationimage",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("api_method__in", ["exec", "invoke"])),
+                name="workstations_workstationimage_api_method_in_choices",
+            ),
+        ),
+    ]

app/tests/components_tests/test_amazon_sagemaker_training_backend.py

@@ -20,6 +20,7 @@
     ComponentException,
     TaskCancelled,
 )
+from grandchallenge.components.models import APIMethodChoices
 from grandchallenge.components.schemas import GPUTypeChoices
 from grandchallenge.evaluation.models import Evaluation, Method
 
@@ -52,6 +53,7 @@ def test_instance_type(memory_limit, expected_type, requires_gpu_type):
         requires_gpu_type=requires_gpu_type,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     assert executor._instance_type.name == expected_type
@@ -77,6 +79,7 @@ def test_instance_type_incompatible(memory_limit, requires_gpu_type):
         requires_gpu_type=requires_gpu_type,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     with pytest.raises(ValueError):
@@ -115,6 +118,7 @@ def test_invocation_prefix():
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     # The id of the job must be in the prefixes
@@ -173,6 +177,7 @@ def test_invocation_json(settings):
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"totallysecret",
+        api_method=APIMethodChoices.EXEC,
     )
 
     with Stubber(executor._sagemaker_client) as s:
@@ -207,6 +212,7 @@ def test_invocation_json(settings):
                     "no_proxy": "amazonaws.com",
                     "GRAND_CHALLENGE_COMPONENT_MAX_MEMORY_MB": "7168",
                     "GRAND_CHALLENGE_COMPONENT_SIGNING_KEY_HEX": "746f74616c6c79736563726574",
+                    "GRAND_CHALLENGE_COMPONENT_API_METHOD": "exec",
                 },
                 "VpcConfig": {
                     "SecurityGroupIds": [
@@ -256,6 +262,7 @@ def test_set_duration():
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     assert executor.utilization_duration is None
@@ -283,6 +290,7 @@ def test_get_log_stream_name(settings):
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     with Stubber(executor._logs_client) as s:
@@ -315,6 +323,7 @@ def test_set_task_logs(settings):
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     assert executor.stdout == ""
@@ -462,6 +471,7 @@ def test_set_runtime_metrics(settings):
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     assert executor.runtime_metrics == {}
@@ -558,6 +568,7 @@ def test_handle_completed_job():
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"itsasecret",
+        api_method=APIMethodChoices.EXEC,
     )
 
     inference_result = InferenceResult(
@@ -604,6 +615,7 @@ def test_handle_time_limit_exceded(settings):
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     with pytest.raises(ComponentException) as error:
@@ -629,6 +641,7 @@ def test_handle_stopped_event(settings):
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     with (
@@ -737,6 +750,7 @@ def test_deprovision(settings):
         requires_gpu_type=GPUTypeChoices.NO_GPU,
         use_warm_pool=False,
         signing_key=b"",
+        api_method=APIMethodChoices.EXEC,
     )
 
     created_files = (