improve the rats.aml api

- print the studio url when submitting a job to aml
- create rats.aml.job() factory function for access to the app container
- add more relevant details to rats.aml.Request

Author: ms-lolo

rats-devtools/src/rats/aml/__init__.py

@@ -38,7 +38,7 @@
     AmlWorkspace,
 )
 from ._request import Request
-from ._submission import submit
+from ._submission import job, submit
 
 __all__ = [
     "AmlEnvironment",
@@ -50,6 +50,7 @@
     "AppServices",
     "Application",
     "Request",
+    "job",
     "main",
     "submit",
 ]

rats-devtools/src/rats/aml/_app.py

@@ -525,13 +525,16 @@ def _submit(
             **extra_aml_command_args,
         )
         returned_job = job_ops.create_or_update(job)  # type: ignore[reportUnknownMemberType]
-        logger.info(f"created job: {returned_job}")
 
         self._request = Request(
-            job_name=str(returned_job.name),
+            name=str(returned_job.name),
+            experiment_name=str(returned_job.experiment_name),
+            studio_url=str(returned_job.studio_url),
             wait=wait,
         )
 
+        print(f"created job: {self._request}")
+
         while wait:
             job_details = job_ops.get(str(returned_job.name))
             logger.info(f"job {returned_job.name} status: {job_details.status}")

rats-devtools/src/rats/aml/_request.py

@@ -2,8 +2,12 @@
 
 
 class Request(NamedTuple):
-    job_name: str
+    name: str
     """The aml job name, often generated by the aml apis."""
+    experiment_name: str
+    """The aml experiment where the job was submitted, typically our component name."""
+    studio_url: str
+    """Link to the portal page for the submitted job."""
 
     wait: bool
     """Whether the application will wait for the completion of the aml job before returning."""

rats-devtools/src/rats/aml/_submission.py

@@ -14,6 +14,42 @@ def submit(
     """
     Submit an AML job programmatically instead of calling `rats-aml submit`.
 
+    Args:
+        app_ids: list of the application to run on the remote aml job as found in pyproject.toml.
+        container_plugin: a plugin container for passing services into [rats.aml.Application][].
+        context: context to send to the remote aml job.
+        wait: wait for the successful completion of the submitted aml job.
+    """
+    submitter = job(
+        *app_ids,
+        container_plugin=container_plugin,
+        context=context,
+        wait=wait,
+    )
+    submitter.execute()
+
+
+def job(
+    *app_ids: str,
+    container_plugin: apps.ContainerPlugin = apps.EMPTY_PLUGIN,
+    context: app_context.Collection[Any] = app_context.EMPTY_COLLECTION,
+    wait: bool = False,
+) -> apps.AppContainer:
+    """
+    Convenience factory function for creating [rats.aml.Application][] instances.
+
+    Use this function if you want access to the underlying container in order to reach relevant
+    services before, after, or during the execution of the aml job.
+
+    ```python
+    from rats import aml
+
+    job = aml.app("rats_e2e.aml.basic", wait=True)
+    job.execute()
+    request = job.get(aml.AppServices.REQUEST)
+    print(request.name)
+    ```
+
     Args:
         app_ids: list of the application to run on the remote aml job as found in pyproject.toml.
         container_plugin: a plugin container for passing services into [rats.aml.Application][].
@@ -29,11 +65,10 @@ def submit(
         app_context.dumps(context),
         *w,
     )
-    submitter = apps.AppBundle(
+    return apps.AppBundle(
         app_plugin=Application,
         container_plugin=container_plugin,
         context=apps.StaticContainer(
             apps.static_service(cli.PluginConfigs.ARGV, lambda: cmd),
         ),
     )
-    submitter.execute()