lightning-sdk 0.1.42__py3-none-any.whl → 0.1.44__py3-none-any.whl

lightning_sdk/lightning_cloud/openapi/models/v1_project_membership.py

@@ -58,6 +58,7 @@ class V1ProjectMembership(object):
         'last_name': 'str',
         'membership_count': 'str',
         'name': 'str',
+        'next_free_credits_grant_at': 'datetime',
         'organization': 'str',
         'owner_id': 'str',
         'owner_type': 'V1OwnerType',
@@ -87,6 +88,7 @@ class V1ProjectMembership(object):
         'last_name': 'lastName',
         'membership_count': 'membershipCount',
         'name': 'name',
+        'next_free_credits_grant_at': 'nextFreeCreditsGrantAt',
         'organization': 'organization',
         'owner_id': 'ownerId',
         'owner_type': 'ownerType',
@@ -98,7 +100,7 @@ class V1ProjectMembership(object):
         'username': 'username'
     }
 
-    def __init__(self, avatar_url: 'str' =None, balance: 'float' =None, created_at: 'datetime' =None, creator_id: 'str' =None, datastore_count: 'str' =None, description: 'str' =None, display_name: 'str' =None, email: 'str' =None, first_name: 'str' =None, free_credits_enabled: 'bool' =None, inactive: 'bool' =None, is_default: 'bool' =None, job_count: 'str' =None, job_title: 'str' =None, last_name: 'str' =None, membership_count: 'str' =None, name: 'str' =None, organization: 'str' =None, owner_id: 'str' =None, owner_type: 'V1OwnerType' =None, project_id: 'str' =None, quotas: 'V1Quotas' =None, roles: 'list[V1Role]' =None, updated_at: 'datetime' =None, user_id: 'str' =None, username: 'str' =None):  # noqa: E501
+    def __init__(self, avatar_url: 'str' =None, balance: 'float' =None, created_at: 'datetime' =None, creator_id: 'str' =None, datastore_count: 'str' =None, description: 'str' =None, display_name: 'str' =None, email: 'str' =None, first_name: 'str' =None, free_credits_enabled: 'bool' =None, inactive: 'bool' =None, is_default: 'bool' =None, job_count: 'str' =None, job_title: 'str' =None, last_name: 'str' =None, membership_count: 'str' =None, name: 'str' =None, next_free_credits_grant_at: 'datetime' =None, organization: 'str' =None, owner_id: 'str' =None, owner_type: 'V1OwnerType' =None, project_id: 'str' =None, quotas: 'V1Quotas' =None, roles: 'list[V1Role]' =None, updated_at: 'datetime' =None, user_id: 'str' =None, username: 'str' =None):  # noqa: E501
         """V1ProjectMembership - a model defined in Swagger"""  # noqa: E501
         self._avatar_url = None
         self._balance = None
@@ -117,6 +119,7 @@ class V1ProjectMembership(object):
         self._last_name = None
         self._membership_count = None
         self._name = None
+        self._next_free_credits_grant_at = None
         self._organization = None
         self._owner_id = None
         self._owner_type = None
@@ -161,6 +164,8 @@ class V1ProjectMembership(object):
             self.membership_count = membership_count
         if name is not None:
             self.name = name
+        if next_free_credits_grant_at is not None:
+            self.next_free_credits_grant_at = next_free_credits_grant_at
         if organization is not None:
             self.organization = organization
         if owner_id is not None:
@@ -537,6 +542,27 @@ class V1ProjectMembership(object):
 
         self._name = name
 
+    @property
+    def next_free_credits_grant_at(self) -> 'datetime':
+        """Gets the next_free_credits_grant_at of this V1ProjectMembership.  # noqa: E501
+
+
+        :return: The next_free_credits_grant_at of this V1ProjectMembership.  # noqa: E501
+        :rtype: datetime
+        """
+        return self._next_free_credits_grant_at
+
+    @next_free_credits_grant_at.setter
+    def next_free_credits_grant_at(self, next_free_credits_grant_at: 'datetime'):
+        """Sets the next_free_credits_grant_at of this V1ProjectMembership.
+
+
+        :param next_free_credits_grant_at: The next_free_credits_grant_at of this V1ProjectMembership.  # noqa: E501
+        :type: datetime
+        """
+
+        self._next_free_credits_grant_at = next_free_credits_grant_at
+
     @property
     def organization(self) -> 'str':
         """Gets the organization of this V1ProjectMembership.  # noqa: E501

lightning_sdk/mmt/__init__.py

@@ -1,3 +1,4 @@
+from lightning_sdk.mmt.base import MMTMachine
 from lightning_sdk.mmt.mmt import MMT
 
-__all__ = ["MMT"]
+__all__ = ["MMT", "MMTMachine"]

lightning_sdk/mmt/base.py

@@ -1,5 +1,5 @@
 from abc import abstractmethod
-from typing import TYPE_CHECKING, Dict, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Dict, Optional, Protocol, Tuple, Union
 
 if TYPE_CHECKING:
     from lightning_sdk.machine import Machine
@@ -10,11 +10,41 @@ if TYPE_CHECKING:
     from lightning_sdk.user import User
 
 from lightning_sdk.job.base import _BaseJob
-from lightning_sdk.job.job import Job
 from lightning_sdk.utils.resolve import _resolve_deprecated_cluster
 
 
+class MMTMachine(Protocol):
+    """A single machine in multi-machine training."""
+
+    @property
+    def name(self) -> str:
+        """The Name of the individual machine. Usually corresponds to the rank."""
+        ...
+
+    @property
+    def machine(self) -> "Machine":
+        """The actual machine type this node is running on."""
+        ...
+
+    @property
+    def artifact_path(self) -> Optional[str]:
+        """The path to the artifacts of this job."""
+        ...
+
+    @property
+    def status(self) -> "Status":
+        """The status of this job."""
+        ...
+
+    @property
+    def logs(self) -> str:
+        """The logs of the given machine."""
+        ...
+
+
 class _BaseMMT(_BaseJob):
+    """Base interface to all job types."""
+
     @classmethod
     def run(
         cls,
@@ -36,6 +66,39 @@ class _BaseMMT(_BaseJob):
         artifacts_remote: Optional[str] = None,
         cluster: Optional[str] = None,  # deprecated in favor of cloud_account
     ) -> "_BaseMMT":
+        """Run async workloads using a docker image across multiple machines.
+
+        Args:
+            name: The name of the job. Needs to be unique within the teamspace.
+            machine: The machine type to run the job on. One of {", ".join(_MACHINE_VALUES)}.
+            num_machine: The number of machines to run on.
+            command: The command to run inside your job. Required if using a studio. Optional if using an image.
+                If not provided for images, will run the container entrypoint and default command.
+            studio: The studio env to run the job with. Mutually exclusive with image.
+            image: The docker image to run the job with. Mutually exclusive with studio.
+            teamspace: The teamspace the job should be associated with. Defaults to the current teamspace.
+            org: The organization owning the teamspace (if any). Defaults to the current organization.
+            user: The user owning the teamspace (if any). Defaults to the current user.
+            cloud_account: The cloud account to run the job on.
+                Defaults to the studio cloud account if running with studio compute env.
+                If not provided will fall back to the teamspaces default cloud account.
+            env: Environment variables to set inside the job.
+            interruptible: Whether the job should run on interruptible instances. They are cheaper but can be preempted.
+            image_credentials: The credentials used to pull the image. Required if the image is private.
+                This should be the name of the respective credentials secret created on the Lightning AI platform.
+            cloud_account_auth: Whether to authenticate with the cloud account to pull the image.
+                Required if the registry is part of a cloud provider (e.g. ECR).
+            artifacts_local: The path of inside the docker container, you want to persist images from.
+                CAUTION: When setting this to "/", it will effectively erase your container.
+                Only supported for jobs with a docker image compute environment.
+            artifacts_remote: The remote storage to persist your artifacts to.
+                Should be of format <CONNECTION_TYPE>:<CONNECTION_NAME>:<PATH_WITHIN_CONNECTION>.
+                PATH_WITHIN_CONNECTION hereby is a path relative to the connection's root.
+                E.g. efs:data:some-path would result in an EFS connection named `data` and to the path `some-path`
+                within it.
+                Note that the connection needs to be added to the teamspace already in order for it to be found.
+                Only supported for jobs with a docker image compute environment.
+        """
         from lightning_sdk.studio import Studio
 
         cloud_account = _resolve_deprecated_cluster(cloud_account, cluster)
@@ -134,53 +197,92 @@ class _BaseMMT(_BaseJob):
         artifacts_local: Optional[str] = None,
         artifacts_remote: Optional[str] = None,
     ) -> None:
-        """Submits a job and updates the internal _job attribute as well as the _name attribute."""
+        """Submit a new multi-machine job to the Lightning AI platform.
+
+        Args:
+            num_machines: The number of machines to run on.
+            machine: The machine type to run the job on. One of {", ".join(_MACHINE_VALUES)}.
+            command: The command to run inside your job. Required if using a studio. Optional if using an image.
+                If not provided for images, will run the container entrypoint and default command.
+            studio: The studio env to run the job with. Mutually exclusive with image.
+            image: The docker image to run the job with. Mutually exclusive with studio.
+            env: Environment variables to set inside the job.
+            interruptible: Whether the job should run on interruptible instances. They are cheaper but can be preempted.
+            cloud_account: The cloud account to run the job on.
+                Defaults to the studio cloud account if running with studio compute env.
+                If not provided will fall back to the teamspaces default cloud account.
+            image_credentials: The credentials used to pull the image. Required if the image is private.
+                This should be the name of the respective credentials secret created on the Lightning AI platform.
+            cloud_account_auth: Whether to authenticate with the cloud account to pull the image.
+                Required if the registry is part of a cloud provider (e.g. ECR).
+            artifacts_local: The path of inside the docker container, you want to persist images from.
+                CAUTION: When setting this to "/", it will effectively erase your container.
+                Only supported for jobs with a docker image compute environment.
+            artifacts_remote: The remote storage to persist your artifacts to.
+                Should be of format <CONNECTION_TYPE>:<CONNECTION_NAME>:<PATH_WITHIN_CONNECTION>.
+                PATH_WITHIN_CONNECTION hereby is a path relative to the connection's root.
+                E.g. efs:data:some-path would result in an EFS connection named `data` and to the path `some-path`
+                within it.
+                Note that the connection needs to be added to the teamspace already in order for it to be found.
+                Only supported for jobs with a docker image compute environment.
+        """
 
     @property
     @abstractmethod
-    def machines(self) -> Tuple["Job", ...]:
-        pass
+    def machines(self) -> Tuple[MMTMachine, ...]:
+        """Returns the sub-jobs for each individual instance."""
 
     @property
     @abstractmethod
     def machine(self) -> "Machine":
-        pass
+        """Returns the machine type this job is running on."""
 
     @abstractmethod
     def stop(self) -> None:
-        pass
+        """Stops the job."""
 
     @abstractmethod
     def delete(self) -> None:
-        pass
+        """Deletes the job.
+
+        Caution: This also deletes all artifacts and snapshots associated with the job.
+        """
 
     @property
     @abstractmethod
     def status(self) -> "Status":
-        pass
+        """The current status of the job."""
 
     @property
     @abstractmethod
     def artifact_path(self) -> Optional[str]:
-        pass
+        """Path to the artifacts created by the job within the distributed teamspace filesystem."""
 
     @property
     @abstractmethod
     def snapshot_path(self) -> Optional[str]:
-        pass
+        """Path to the studio snapshot used to create the job within the distributed teamspace filesystem."""
 
     @property
     def share_path(self) -> Optional[str]:
+        """Path to the jobs share path."""
         return None
 
-    @abstractmethod
-    def _update_internal_job(self) -> None:
-        pass
-
     @property
     def name(self) -> str:
+        """The job's name."""
         return self._name
 
     @property
     def teamspace(self) -> "Teamspace":
+        """The teamspace the job is part of."""
         return self._teamspace
+
+    @property
+    def logs(self) -> str:
+        """Logs of the rank 0 machine."""
+        return self.machines[0].logs
+
+    @abstractmethod
+    def _update_internal_job(self) -> None:
+        pass

lightning_sdk/mmt/mmt.py

@@ -1,9 +1,13 @@
-from typing import TYPE_CHECKING, Any, Dict, Optional, Protocol, Tuple, Union
+from contextlib import suppress
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Union
 
+from lightning_sdk.api.user_api import UserApi
 from lightning_sdk.job.job import _has_jobs_v2
-from lightning_sdk.mmt.base import _BaseMMT
+from lightning_sdk.mmt.base import MMTMachine, _BaseMMT
 from lightning_sdk.mmt.v1 import _MMTV1
 from lightning_sdk.mmt.v2 import _MMTV2
+from lightning_sdk.utils.resolve import _setup_logger
 
 if TYPE_CHECKING:
     from lightning_sdk.machine import Machine
@@ -13,28 +17,25 @@ if TYPE_CHECKING:
     from lightning_sdk.teamspace import Teamspace
     from lightning_sdk.user import User
 
+_logger = _setup_logger(__name__)
 
-class MMTMachine(Protocol):
-    """A single machine in multi-machine training."""
 
-    @property
-    def name(self) -> str:
-        ...
-
-    @property
-    def machine(self) -> "Machine":
-        ...
+@lru_cache(maxsize=None)
+def _has_mmt_v2() -> bool:
+    # users need both mmtv2 and jobsv2 flags in order for mmtv2 to work correctly
+    if not _has_jobs_v2():
+        return False
 
-    @property
-    def artifact_path(self) -> Optional[str]:
-        ...
-
-    @property
-    def status(self) -> "Status":
-        ...
+    api = UserApi()
+    try:
+        return api._get_feature_flags().mmt_v2
+    except Exception:
+        return False
 
 
 class MMT(_BaseMMT):
+    """Class to submit and manage multi-machine jobs on the Lightning AI Platform."""
+
     _force_v1: (
         bool
     ) = False  # required for studio plugin still working correctly as v2 currently does not support the studio env
@@ -48,7 +49,16 @@ class MMT(_BaseMMT):
         *,
         _fetch_job: bool = True,
     ) -> None:
-        internal_mmt_cls = _MMTV2 if _has_jobs_v2() and not self._force_v1 else _MMTV1
+        """Fetch already existing jobs.
+
+        Args:
+            name: the name of the job
+            teamspace: the teamspace the job is part of
+            org: the name of the organization owning the :param`teamspace` in case it is owned by an org
+            user: the name of the user owning the :param`teamspace`
+                in case it is owned directly by a user instead of an org.
+        """
+        internal_mmt_cls = _MMTV2 if _has_mmt_v2() and not self._force_v1 else _MMTV1
 
         self._internal_mmt = internal_mmt_cls(
             name=name,
@@ -79,6 +89,39 @@ class MMT(_BaseMMT):
         artifacts_remote: Optional[str] = None,
         cluster: Optional[str] = None,  # deprecated in favor of cloud_account
     ) -> "MMT":
+        """Run async workloads using a docker image across multiple machines.
+
+        Args:
+            name: The name of the job. Needs to be unique within the teamspace.
+            machine: The machine type to run the job on. One of {", ".join(_MACHINE_VALUES)}.
+            num_machine: The number of machines to run on.
+            command: The command to run inside your job. Required if using a studio. Optional if using an image.
+                If not provided for images, will run the container entrypoint and default command.
+            studio: The studio env to run the job with. Mutually exclusive with image.
+            image: The docker image to run the job with. Mutually exclusive with studio.
+            teamspace: The teamspace the job should be associated with. Defaults to the current teamspace.
+            org: The organization owning the teamspace (if any). Defaults to the current organization.
+            user: The user owning the teamspace (if any). Defaults to the current user.
+            cloud_account: The cloud account to run the job on.
+                Defaults to the studio cloud account if running with studio compute env.
+                If not provided will fall back to the teamspaces default cloud account.
+            env: Environment variables to set inside the job.
+            interruptible: Whether the job should run on interruptible instances. They are cheaper but can be preempted.
+            image_credentials: The credentials used to pull the image. Required if the image is private.
+                This should be the name of the respective credentials secret created on the Lightning AI platform.
+            cloud_account_auth: Whether to authenticate with the cloud account to pull the image.
+                Required if the registry is part of a cloud provider (e.g. ECR).
+            artifacts_local: The path of inside the docker container, you want to persist images from.
+                CAUTION: When setting this to "/", it will effectively erase your container.
+                Only supported for jobs with a docker image compute environment.
+            artifacts_remote: The remote storage to persist your artifacts to.
+                Should be of format <CONNECTION_TYPE>:<CONNECTION_NAME>:<PATH_WITHIN_CONNECTION>.
+                PATH_WITHIN_CONNECTION hereby is a path relative to the connection's root.
+                E.g. efs:data:some-path would result in an EFS connection named `data` and to the path `some-path`
+                within it.
+                Note that the connection needs to be added to the teamspace already in order for it to be found.
+                Only supported for jobs with a docker image compute environment.
+        """
         ret_val = super().run(
             name=name,
             num_machines=num_machines,
@@ -98,8 +141,15 @@ class MMT(_BaseMMT):
             artifacts_remote=artifacts_remote,
             cluster=cluster,  # deprecated in favor of cloud_account
         )
-        # required for typing with "Job"
+        # required for typing with "MMT"
         assert isinstance(ret_val, cls)
+
+        msg = "Multi-Machine Job was successfully launched."
+
+        with suppress(NotImplementedError):
+            msg += f" View it at {ret_val.link}"
+
+        _logger.info(msg)
         return ret_val
 
     def _submit(
@@ -117,6 +167,35 @@ class MMT(_BaseMMT):
         artifacts_local: Optional[str] = None,
         artifacts_remote: Optional[str] = None,
     ) -> "MMT":
+        """Submit a new multi-machine job to the Lightning AI platform.
+
+        Args:
+            num_machines: The number of machines to run on.
+            machine: The machine type to run the job on. One of {", ".join(_MACHINE_VALUES)}.
+            command: The command to run inside your job. Required if using a studio. Optional if using an image.
+                If not provided for images, will run the container entrypoint and default command.
+            studio: The studio env to run the job with. Mutually exclusive with image.
+            image: The docker image to run the job with. Mutually exclusive with studio.
+            env: Environment variables to set inside the job.
+            interruptible: Whether the job should run on interruptible instances. They are cheaper but can be preempted.
+            cloud_account: The cloud account to run the job on.
+                Defaults to the studio cloud account if running with studio compute env.
+                If not provided will fall back to the teamspaces default cloud account.
+            image_credentials: The credentials used to pull the image. Required if the image is private.
+                This should be the name of the respective credentials secret created on the Lightning AI platform.
+            cloud_account_auth: Whether to authenticate with the cloud account to pull the image.
+                Required if the registry is part of a cloud provider (e.g. ECR).
+            artifacts_local: The path of inside the docker container, you want to persist images from.
+                CAUTION: When setting this to "/", it will effectively erase your container.
+                Only supported for jobs with a docker image compute environment.
+            artifacts_remote: The remote storage to persist your artifacts to.
+                Should be of format <CONNECTION_TYPE>:<CONNECTION_NAME>:<PATH_WITHIN_CONNECTION>.
+                PATH_WITHIN_CONNECTION hereby is a path relative to the connection's root.
+                E.g. efs:data:some-path would result in an EFS connection named `data` and to the path `some-path`
+                within it.
+                Note that the connection needs to be added to the teamspace already in order for it to be found.
+                Only supported for jobs with a docker image compute environment.
+        """
         self._job = self._internal_mmt._submit(
             num_machines=num_machines,
             machine=machine,
@@ -134,33 +213,44 @@ class MMT(_BaseMMT):
         return self
 
     def stop(self) -> None:
+        """Stops the job."""
         return self._internal_mmt.stop()
 
     def delete(self) -> None:
+        """Deletes the job.
+
+        Caution: This also deletes all artifacts and snapshots associated with the job.
+        """
         return self._internal_mmt.delete()
 
     @property
     def status(self) -> "Status":
+        """The current status of the job (accumulated over all machines)."""
         return self._internal_mmt.status
 
     @property
     def machines(self) -> Tuple[MMTMachine, ...]:
+        """Returns the sub-jobs for each individual instance."""
         return self._internal_mmt.machines
 
     @property
     def machine(self) -> "Machine":
+        """Returns the machine type this job is running on."""
         return self._internal_mmt.machine
 
     @property
     def artifact_path(self) -> Optional[str]:
+        """Path to the artifacts created by the job within the distributed teamspace filesystem."""
         return self._internal_mmt.artifact_path
 
     @property
     def snapshot_path(self) -> Optional[str]:
+        """Path to the studio snapshot used to create the job within the distributed teamspace filesystem."""
         return self._internal_mmt.snapshot_path
 
     @property
     def share_path(self) -> Optional[str]:
+        """Path to the jobs share path."""
         return None
 
     def _update_internal_job(self) -> None:
@@ -168,15 +258,17 @@ class MMT(_BaseMMT):
 
     @property
     def name(self) -> str:
+        """The job's name."""
         return self._internal_mmt.name
 
     @property
     def teamspace(self) -> "Teamspace":
+        """The teamspace the job is part of."""
         return self._internal_mmt._teamspace
 
     @property
-    def cloud_account(self) -> Optional[str]:
-        return self._internal_mmt.cloud_account
+    def link(self) -> str:
+        return self._internal_mmt.link
 
     def __getattr__(self, key: str) -> Any:
         """Forward the attribute lookup to the internal job implementation."""

lightning_sdk/mmt/v1.py

@@ -16,6 +16,8 @@ from lightning_sdk.mmt.base import _BaseMMT
 
 
 class _MMTV1(_BaseMMT):
+    """V1 Implementation of Multi-Machine Training."""
+
     def __init__(
         self,
         name: str,
@@ -25,6 +27,15 @@ class _MMTV1(_BaseMMT):
         *,
         _fetch_job: bool = True,
     ) -> None:
+        """Fetch already existing jobs.
+
+        Args:
+            name: the name of the job
+            teamspace: the teamspace the job is part of
+            org: the name of the organization owning the :param`teamspace` in case it is owned by an org
+            user: the name of the user owning the :param`teamspace`
+                in case it is owned directly by a user instead of an org.
+        """
         self._job_api = MMTApiV1()
         super().__init__(name=name, teamspace=teamspace, org=org, user=user, _fetch_job=_fetch_job)
 
@@ -43,6 +54,35 @@ class _MMTV1(_BaseMMT):
         artifacts_local: Optional[str] = None,
         artifacts_remote: Optional[str] = None,
     ) -> "_MMTV1":
+        """Submit a new multi-machine job to the Lightning AI platform.
+
+        Args:
+            num_machines: The number of machines to run on.
+            machine: The machine type to run the job on. One of {", ".join(_MACHINE_VALUES)}.
+            command: The command to run inside your job. Required if using a studio. Optional if using an image.
+                If not provided for images, will run the container entrypoint and default command.
+            studio: The studio env to run the job with. Mutually exclusive with image.
+            image: The docker image to run the job with. Mutually exclusive with studio.
+            env: Environment variables to set inside the job.
+            interruptible: Whether the job should run on interruptible instances. They are cheaper but can be preempted.
+            cloud_account: The cloud account to run the job on.
+                Defaults to the studio cloud account if running with studio compute env.
+                If not provided will fall back to the teamspaces default cloud account.
+            image_credentials: The credentials used to pull the image. Required if the image is private.
+                This should be the name of the respective credentials secret created on the Lightning AI platform.
+            cloud_account_auth: Whether to authenticate with the cloud account to pull the image.
+                Required if the registry is part of a cloud provider (e.g. ECR).
+            artifacts_local: The path of inside the docker container, you want to persist images from.
+                CAUTION: When setting this to "/", it will effectively erase your container.
+                Only supported for jobs with a docker image compute environment.
+            artifacts_remote: The remote storage to persist your artifacts to.
+                Should be of format <CONNECTION_TYPE>:<CONNECTION_NAME>:<PATH_WITHIN_CONNECTION>.
+                PATH_WITHIN_CONNECTION hereby is a path relative to the connection's root.
+                E.g. efs:data:some-path would result in an EFS connection named `data` and to the path `some-path`
+                within it.
+                Note that the connection needs to be added to the teamspace already in order for it to be found.
+                Only supported for jobs with a docker image compute environment.
+        """
         if studio is None:
             raise ValueError("Studio is required for submitting jobs")
         if image is not None or image_credentials is not None or cloud_account_auth:
@@ -80,18 +120,25 @@ class _MMTV1(_BaseMMT):
 
     @property
     def machines(self) -> Tuple["Work", ...]:
+        """Returns the sub-jobs for each individual instance."""
         works = self._job_api.list_works(self._guaranteed_job.id, self.teamspace.id)
 
         return tuple(Work(w.id, self, self.teamspace) for w in works)
 
     def stop(self) -> None:
+        """Stops the job."""
         self._job_api.stop_job(self._guaranteed_job.id, self.teamspace.id)
 
     def delete(self) -> None:
+        """Deletes the job.
+
+        Caution: This also deletes all artifacts and snapshots associated with the job.
+        """
         self._job_api.delete_job(self._guaranteed_job.id, self.teamspace.id)
 
     @property
     def status(self) -> "Status":
+        """The current status of the job."""
         try:
             status = self._job_api.get_job_status(self._job.id, self.teamspace.id)
             return _internal_status_to_external_status(status)
@@ -102,24 +149,33 @@ class _MMTV1(_BaseMMT):
 
     @property
     def artifact_path(self) -> Optional[str]:
+        """Path to the artifacts created by the job within the distributed teamspace filesystem."""
         return f"/teamspace/jobs/{self.name}"
 
     @property
     def snapshot_path(self) -> Optional[str]:
+        """Path to the studio snapshot used to create the job within the distributed teamspace filesystem."""
         return f"/teamspace/jobs/{self.name}/snapshot"
 
     @property
     def machine(self) -> "Machine":
+        """Returns the machine type this job is running on."""
         return self.machines[0].machine
 
     @property
     def name(self) -> str:
+        """The job's name."""
         return self._name
 
     @property
     def teamspace(self) -> "Teamspace":
+        """The teamspace the job is part of."""
         return self._teamspace
 
+    @property
+    def link(self) -> str:
+        return f"https://lightning.ai/{self.teamspace.owner.name}/{self.teamspace.name}/studios/{self._job_api.get_studio_name(self._guaranteed_job)}/app?app_id=mmt&app_tab=Runs&job_name={self.name}"
+
     # the following and functions are solely to make the Work class function
     @property
     def _id(self) -> str: