sagemaker-core 1.0.62__py3-none-any.whl → 2.1.1__py3-none-any.whl

sagemaker/core/interactive_apps/base_interactive_app.py

@@ -0,0 +1,204 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+"""A base class for starting/accessing apps hosted on Amazon SageMaker Studio"""
+
+from __future__ import absolute_import
+
+import abc
+import base64
+import json
+import logging
+import os
+import re
+import webbrowser
+
+from typing import Optional
+import boto3
+from sagemaker.core.helper.session_helper import Session, NOTEBOOK_METADATA_FILE
+
+logger = logging.getLogger(__name__)
+
+
+class BaseInteractiveApp(abc.ABC):
+    """BaseInteractiveApp is a base class for creating/accessing apps hosted on SageMaker."""
+
+    def __init__(
+        self,
+        region: Optional[str] = None,
+    ):
+        """Initialize a BaseInteractiveApp object.
+
+        Args:
+            region (str): Optional. The AWS Region, e.g. us-east-1. If not specified,
+                one is created using the default AWS configuration chain.
+                Default: ``None``
+        """
+        if isinstance(region, str):
+            self.region = region
+        else:
+            try:
+                self.region = Session().boto_region_name
+            except ValueError:
+                raise ValueError(
+                    "Failed to get the Region information from the default config. Please either "
+                    "pass your Region manually as an input argument or set up the local AWS"
+                    " configuration."
+                )
+
+        self._sagemaker_client = boto3.client("sagemaker", region_name=self.region)
+        # Used to store domain and user profile info retrieved from Studio environment.
+        self._domain_id = None
+        self._user_profile_name = None
+        self._in_studio_env = False
+        self._get_domain_and_user()
+
+    def __str__(self):
+        """Return str(self)."""
+        return f"{type(self).__name__}(region={self.region})"
+
+    def __repr__(self):
+        """Return repr(self)."""
+        return self.__str__()
+
+    def _get_domain_and_user(self):
+        """Get domain id and user profile from Studio environment.
+
+        To verify Studio environment, we check if NOTEBOOK_METADATA_FILE exists
+        and domain id and user profile name are present in the file.
+        """
+        if not os.path.isfile(NOTEBOOK_METADATA_FILE):
+            return
+
+        try:
+            with open(NOTEBOOK_METADATA_FILE, "rb") as metadata_file:
+                metadata = json.loads(metadata_file.read())
+        except OSError as err:
+            logger.warning("Could not load metadata due to unexpected error. %s", err)
+            return
+
+        if "DomainId" in metadata and "UserProfileName" in metadata:
+            self._in_studio_env = True
+            self._domain_id = metadata.get("DomainId")
+            self._user_profile_name = metadata.get("UserProfileName")
+
+    def _get_presigned_url(
+        self,
+        create_presigned_url_kwargs: dict,
+        redirect: Optional[str] = None,
+        state: Optional[str] = None,
+    ):
+        """Generate a presigned URL to access a user's domain / user profile.
+
+        Optional state and redirect parameters can be used to to have presigned URL automatically
+        redirect to a specific app and provide modifying data.
+
+        Args:
+            create_presigned_url_kwargs (dict): Required. This dictionary should include the
+                parameters that will be used when calling create_presigned_domain_url via the boto3
+                client. At a minimum, this should include the "DomainId" and "UserProfileName"
+                parameters as defined by create_presigned_domain_url's documentation.
+                Default: ``None``
+            redirect (str): Optional. This value will be appended to the resulting presigned URL
+                in the format "&redirect=<redirect parameter>". This is used to automatically
+                redirect the user into a specific Studio app.
+                Default: ``None``
+            state (str): Optional. This value will be appended to the resulting presigned URL
+                in the format "&state=<state parameter base64 encoded>". This is used to
+                automatically apply a state to the given app. Should be used in conjuction with
+                the redirect parameter.
+                Default: ``None``
+
+        Returns:
+            str: A presigned URL.
+        """
+        response = self._sagemaker_client.create_presigned_domain_url(**create_presigned_url_kwargs)
+        if response["ResponseMetadata"]["HTTPStatusCode"] == 200:
+            url = response["AuthorizedUrl"]
+        else:
+            raise ValueError(
+                "An invalid status code was returned when creating a presigned URL."
+                f" See response for more: {response}"
+            )
+
+        if redirect:
+            url += f"&redirect={redirect}"
+
+        if state:
+            url += f"&state={base64.b64encode(bytes(state, 'utf-8')).decode('utf-8')}"
+
+        logger.warning(
+            "A presigned domain URL was generated. This is sensitive and should not be shared with"
+            " others."
+        )
+
+        return url
+
+    def _open_url_in_web_browser(self, url: str):
+        """Open a URL in the default web browser.
+
+        Args:
+            url (str): The URL to open.
+        """
+        webbrowser.open(url)
+
+    def _validate_job_name(self, job_name: str):
+        """Validate training job name format.
+
+        Args:
+            job_name (str): The job name to validate.
+
+        Returns:
+            bool: Whether the supplied job name is valid.
+        """
+        job_name_regex = "^[a-zA-Z0-9](-*[a-zA-Z0-9]){0,62}"
+        if not re.fullmatch(job_name_regex, job_name):
+            raise ValueError(
+                f"Invalid job name. Job name must match regular expression {job_name_regex}"
+            )
+
+    def _validate_domain_id(self, domain_id: str):
+        """Validate domain id format.
+
+        Args:
+            domain_id (str): Required. The domain ID to validate.
+
+        Returns:
+            bool: Whether the supplied domain ID is valid.
+        """
+        if domain_id is None or len(domain_id) > 63:
+            return False
+        return True
+
+    def _validate_user_profile_name(self, user_profile_name: str):
+        """Validate user profile name format.
+
+        Args:
+            user_profile_name (str): Required. The user profile name to validate.
+
+        Returns:
+            bool: Whether the supplied user profile name is valid.
+        """
+        user_profile_name_regex = "^[a-zA-Z0-9](-*[a-zA-Z0-9]){0,62}"
+        if user_profile_name is None or not re.fullmatch(
+            user_profile_name_regex, user_profile_name
+        ):
+            return False
+        return True
+
+    @abc.abstractmethod
+    def get_app_url(self):
+        """Abstract method to generate a URL to help access the application in Studio.
+
+        Classes that inherit from BaseInteractiveApp should implement and override with what
+        parameters are needed for its specific use case.
+        """

sagemaker/core/interactive_apps/detail_profiler_app.py

@@ -0,0 +1,139 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+"""Methods for starting up and accessing DetailProfiler apps
+
+This module contains methods for starting up and accessing
+DetailProfiler apps hosted on SageMaker
+"""
+from __future__ import absolute_import
+
+import json
+import logging
+import os
+import re
+
+from typing import Optional
+from sagemaker.core.helper.session_helper import Session, NOTEBOOK_METADATA_FILE
+
+logger = logging.getLogger(__name__)
+
+
+class DetailProfilerApp(object):
+    """Class for creating/accessing a DetailProfiler app hosted on SageMaker."""
+
+    def __init__(self, region: Optional[str] = None):
+        """Initialize a DetailProfilerApp object.
+
+        Args:
+            region (str): The name of the region e.g. us-east-1. If not specified,
+                one is created using the default AWS configuration chain.
+        """
+        if region:
+            self.region = region
+        else:
+            try:
+                self.region = Session().boto_region_name
+            except ValueError:
+                raise ValueError(
+                    "Failed to get region from default config. Please eihter pass region "
+                    "as an input argument or setup the local AWS config."
+                )
+
+        self._domain_id = None
+        self._user_profile_name = None
+        self._valid_domain_and_user = False
+        self._get_domain_and_user()
+
+    def __str__(self):
+        """Return str(self)."""
+        return f"DetailProfilerApp(region={self.region})"
+
+    def __repr__(self):
+        """Return repr(self)."""
+        return self.__str__()
+
+    def get_app_url(self, training_job_name: Optional[str] = None):
+        """Get an unsigned URL for DetailProfiler app hosted on SageMaker.
+
+           For users that are already in SM Studio notebook instance, the method tries to
+           get domain id and user profile from the Studio environment. If succeeded, the
+           generated URL will direct to SM DetailProfiler app. Otherwise it will direct to
+           DetailProfiler landing page on SageMaker console. For non Studio users, the
+           URL will direct to the DetailProfiler landing page on SageMaker console.
+
+        Args:
+            training_job_name (str): Optional. The name of the training job to pre-load in
+                DetailProfiler.
+                If not provided, no job will be automatically loaded when the URL is opened.
+
+        Returns:
+            str: An unsigned URL for DetailProfiler hosted on SageMaker.
+        """
+        if self._valid_domain_and_user:
+            url = f"https://{self._domain_id}.studio.{self.region}.sagemaker.aws/profiler/default"
+            if training_job_name is not None:
+                self._validate_job_name(training_job_name)
+                url += f"/#!/welcome?profile={training_job_name}"
+        else:
+            dp = "profiler-landing"
+            url = "https://{region}.console.aws.amazon.com/sagemaker/home?region={region}#/{dp}".format(
+                region=self.region, dp=dp
+            )
+
+        return url
+
+    def _get_domain_and_user(self):
+        """Validate studio domain id and user profile
+
+        Get and validate studio domain id and user profile
+        from NOTEBOOK_METADATA_FILE in studio environment.
+
+        Set _valid_domain_and_user to True if validation succeeded.
+        """
+        if not os.path.isfile(NOTEBOOK_METADATA_FILE):
+            return
+
+        with open(NOTEBOOK_METADATA_FILE, "rb") as f:
+            metadata = json.loads(f.read())
+            self._domain_id = metadata.get("DomainId")
+            self._user_profile_name = metadata.get("UserProfileName")
+            if self._validate_domain_id() is True and self._validate_user_profile_name() is True:
+                self._valid_domain_and_user = True
+            else:
+                logger.warning(
+                    "NOTEBOOK_METADATA_FILE detected but failed to get"
+                    "valid domain and user from it."
+                )
+
+    def _validate_job_name(self, job_name: str):
+        """Validate training job name format."""
+        job_name_regex = "^[a-zA-Z0-9](-*[a-zA-Z0-9]){0,62}"
+        if not re.fullmatch(job_name_regex, job_name):
+            raise ValueError(
+                f"Invalid job name. " f"Job name must match regular expression {job_name_regex}"
+            )
+
+    def _validate_domain_id(self):
+        """Validate domain id format."""
+        if self._domain_id is None or len(self._domain_id) > 63:
+            return False
+        return True
+
+    def _validate_user_profile_name(self):
+        """Validate user profile name format."""
+        user_profile_name_regex = "^[a-zA-Z0-9](-*[a-zA-Z0-9]){0,62}"
+        if self._user_profile_name is None or not re.fullmatch(
+            user_profile_name_regex, self._user_profile_name
+        ):
+            return False
+        return True

sagemaker/core/interactive_apps/tensorboard.py

@@ -0,0 +1,149 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+"""Methods for TensorBoard apps hosted on SageMaker.
+
+This module contains methods for starting up and accessing
+TensorBoard apps hosted on SageMaker
+"""
+from __future__ import absolute_import
+
+import logging
+
+from typing import Optional
+
+from sagemaker.core.interactive_apps.base_interactive_app import BaseInteractiveApp
+
+logger = logging.getLogger(__name__)
+
+
+class TensorBoardApp(BaseInteractiveApp):
+    """TensorBoardApp is a class for creating/accessing a TensorBoard app hosted on Studio."""
+
+    def get_app_url(
+        self,
+        training_job_name: Optional[str] = None,
+        open_in_default_web_browser: Optional[bool] = True,
+        create_presigned_domain_url: Optional[bool] = False,
+        domain_id: Optional[str] = None,
+        user_profile_name: Optional[str] = None,
+        optional_create_presigned_url_kwargs: Optional[dict] = None,
+    ):
+        """Generate a URL to help access the TensorBoard application hosted in Studio.
+
+           For users that are already in SageMaker Studio, this method tries to get the
+           domain id and the user profile from the Studio environment. If successful, the generated
+           URL will direct to the TensorBoard application in SageMaker. Otherwise, it will direct
+           to the TensorBoard landing page in the SageMaker console. If a user outside of SageMaker
+           Studio passes in a valid domain ID and user profile name, the generated URL will be
+           presigned - authenticating the user and redirecting to the TensorBoard app once used.
+           Otherwise, the URL will direct to the TensorBoard landing page in the SageMaker console.
+           By default, the generated URL will attempt to open in the environment's default web
+           browser.
+
+        Args:
+            training_job_name (str): Optional. The name of the training job to pre-load in
+                TensorBoard. If nothing provided, the method just returns the TensorBoard
+                application URL. You can add training jobs later by using the SageMaker Data
+                Manager UI.
+                Default: ``None``
+            open_in_default_web_browser (bool): Optional. When True, the URL will attempt to be
+                opened in the environment's default web browser. Otherwise, the resulting URL will
+                be returned by this function.
+                Default: ``True``
+            create_presigned_domain_url (bool): Optional. Determines whether a presigned domain URL
+                should be generated instead of an unsigned URL. This only applies when called from
+                outside of a SageMaker Studio environment. If this is set to True inside of a
+                SageMaker Studio environment, it will be ignored.
+                Default: ``False``
+            domain_id (str): Optional. This parameter should be passed when a user outside of
+                Studio wants a presigned URL to the TensorBoard application. This value will map to
+                'DomainId' in the resulting create_presigned_domain_url call. Must be passed with
+                user_profile_name and create_presigned_domain_url set to True.
+                Default: ``None``
+            user_profile_name (str): Optional. This parameter should be passed when a user outside
+                of Studio wants a presigned URL to the TensorBoard application. This value will
+                map to 'UserProfileName' in the resulting create_presigned_domain_url call. Must be
+                passed with domain_id and create_presigned_domain_url set to True.
+                Default: ``None``
+            optional_create_presigned_url_kwargs (dict): Optional. This parameter
+                should be passed when a user outside of Studio wants a presigned URL to the
+                TensorBoard application and wants to modify the optional parameters of the
+                create_presigned_domain_url call.
+                Default: ``None``
+
+        Returns:
+            str: A URL for TensorBoard hosted on SageMaker.
+        """
+        if training_job_name is not None:
+            self._validate_job_name(training_job_name)
+
+        if (
+            self._in_studio_env
+            and self._validate_domain_id(self._domain_id)
+            and self._validate_user_profile_name(self._user_profile_name)
+        ):
+            if domain_id or user_profile_name:
+                logger.warning(
+                    "Ignoring passed in domain_id and user_profile_name for Studio set values."
+                )
+            url = (
+                f"https://{self._domain_id}.studio.{self.region}."
+                + "sagemaker.aws/tensorboard/default"
+            )
+            if training_job_name is not None:
+                url += (
+                    "/data/plugin/sagemaker_data_manager/"
+                    + f"add_folder_or_job?Redirect=True&Name={training_job_name}"
+                )
+            else:
+                url += "/#sagemaker_data_manager"
+
+        elif (
+            not self._in_studio_env
+            and create_presigned_domain_url
+            and self._validate_domain_id(domain_id)
+            and self._validate_user_profile_name(user_profile_name)
+        ):
+            if optional_create_presigned_url_kwargs is None:
+                optional_create_presigned_url_kwargs = {}
+            optional_create_presigned_url_kwargs["DomainId"] = domain_id
+            optional_create_presigned_url_kwargs["UserProfileName"] = user_profile_name
+
+            redirect = "TensorBoard"
+            state_to_encode = None
+            if training_job_name is not None:
+                state_to_encode = (
+                    "/tensorboard/default/data/plugin/sagemaker_data_manager/"
+                    + f"add_folder_or_job?Redirect=True&Name={training_job_name}"
+                )
+
+            url = self._get_presigned_url(
+                optional_create_presigned_url_kwargs, redirect, state_to_encode
+            )
+        else:
+            if not self._in_studio_env and create_presigned_domain_url:
+                logger.warning(
+                    "A valid domain ID and user profile name were not provided. "
+                    "Providing default landing page URL as a result."
+                )
+            url = (
+                f"https://{self.region}.console.aws.amazon.com/sagemaker/home"
+                + f"?region={self.region}#/tensor-board-landing"
+            )
+            if training_job_name is not None:
+                url += f"/{training_job_name}"
+
+        if open_in_default_web_browser:
+            self._open_url_in_web_browser(url)
+            url = ""
+        return url

sagemaker/core/iterators.py

@@ -0,0 +1,186 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+"""Implements iterators for deserializing data returned from an inference streaming endpoint."""
+from __future__ import absolute_import
+
+from abc import ABC, abstractmethod
+import io
+
+from sagemaker.core.exceptions import ModelStreamError, InternalStreamFailure
+
+
+def handle_stream_errors(chunk):
+    """Handle API Response errors within `invoke_endpoint_with_response_stream` API if any.
+
+    Args:
+        chunk (dict): A chunk of response received as part of `botocore.eventstream.EventStream`
+            response object.
+
+    Raises:
+        ModelStreamError: If `ModelStreamError` error is detected in a chunk of
+            `botocore.eventstream.EventStream` response object.
+        InternalStreamFailure: If `InternalStreamFailure` error is detected in a chunk of
+            `botocore.eventstream.EventStream` response object.
+    """
+    if "ModelStreamError" in chunk:
+        raise ModelStreamError(
+            chunk["ModelStreamError"]["Message"], code=chunk["ModelStreamError"]["ErrorCode"]
+        )
+    if "InternalStreamFailure" in chunk:
+        raise InternalStreamFailure(chunk["InternalStreamFailure"]["Message"])
+
+
+class BaseIterator(ABC):
+    """Abstract base class for Inference Streaming iterators.
+
+    Provides a skeleton for customization requiring the overriding of iterator methods
+    __iter__ and __next__.
+
+    Tenets of iterator class for Streaming Inference API Response
+    (https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/
+    sagemaker-runtime/client/invoke_endpoint_with_response_stream.html):
+    1. Needs to accept an botocore.eventstream.EventStream response.
+    2. Needs to implement logic in __next__ to:
+        2.1. Concatenate and provide next chunk of response from botocore.eventstream.EventStream.
+            While doing so parse the response_chunk["PayloadPart"]["Bytes"].
+        2.2. If PayloadPart not in EventStream response, handle Errors
+            [Recommended to use `iterators.handle_stream_errors` method].
+    """
+
+    def __init__(self, event_stream):
+        """Initialises a Iterator object to help parse the byte event stream input.
+
+        Args:
+            event_stream: (botocore.eventstream.EventStream): Event Stream object to be iterated.
+        """
+        self.event_stream = event_stream
+
+    @abstractmethod
+    def __iter__(self):
+        """Abstract method, returns an iterator object itself"""
+        return self
+
+    @abstractmethod
+    def __next__(self):
+        """Abstract method, is responsible for returning the next element in the iteration"""
+
+
+class ByteIterator(BaseIterator):
+    """A helper class for parsing the byte Event Stream input to provide Byte iteration."""
+
+    def __init__(self, event_stream):
+        """Initialises a BytesIterator Iterator object
+
+        Args:
+            event_stream: (botocore.eventstream.EventStream): Event Stream object to be iterated.
+        """
+        super().__init__(event_stream)
+        self.byte_iterator = iter(event_stream)
+
+    def __iter__(self):
+        """Returns an iterator object itself, which allows the object to be iterated.
+
+        Returns:
+            iter : object
+                    An iterator object representing the iterable.
+        """
+        return self
+
+    def __next__(self):
+        """Returns the next chunk of Byte directly."""
+        # Even with "while True" loop the function still behaves like a generator
+        # and sends the next new byte chunk.
+        while True:
+            chunk = next(self.byte_iterator)
+            if "PayloadPart" not in chunk:
+                # handle API response errors and force terminate.
+                handle_stream_errors(chunk)
+                # print and move on to next response byte
+                print("Unknown event type:" + chunk)
+                continue
+            return chunk["PayloadPart"]["Bytes"]
+
+
+class LineIterator(BaseIterator):
+    """A helper class for parsing the byte Event Stream input to provide Line iteration."""
+
+    def __init__(self, event_stream):
+        """Initialises a LineIterator Iterator object
+
+        Args:
+            event_stream: (botocore.eventstream.EventStream): Event Stream object to be iterated.
+        """
+        super().__init__(event_stream)
+        self.byte_iterator = iter(self.event_stream)
+        self.buffer = io.BytesIO()
+        self.read_pos = 0
+
+    def __iter__(self):
+        """Returns an iterator object itself, which allows the object to be iterated.
+
+        Returns:
+            iter : object
+                    An iterator object representing the iterable.
+        """
+        return self
+
+    def __next__(self):
+        r"""Returns the next Line for an Line iterable.
+
+        The output of the event stream will be in the following format:
+
+        ```
+        b'{"outputs": [" a"]}\n'
+        b'{"outputs": [" challenging"]}\n'
+        b'{"outputs": [" problem"]}\n'
+        ...
+        ```
+
+        While usually each PayloadPart event from the event stream will contain a byte array
+        with a full json, this is not guaranteed and some of the json objects may be split across
+        PayloadPart events. For example:
+        ```
+        {'PayloadPart': {'Bytes': b'{"outputs": '}}
+        {'PayloadPart': {'Bytes': b'[" problem"]}\n'}}
+        ```
+
+        This class accounts for this by concatenating bytes written via the 'write' function
+        and then exposing a method which will return lines (ending with a '\n' character) within
+        the buffer via the 'scan_lines' function. It maintains the position of the last read
+        position to ensure that previous bytes are not exposed again.
+
+        Returns:
+            str: Read and return one line from the event stream.
+        """
+        # Even with "while True" loop the function still behaves like a generator
+        # and sends the next new concatenated line
+        while True:
+            self.buffer.seek(self.read_pos)
+            line = self.buffer.readline()
+            if line and line[-1] == ord("\n"):
+                self.read_pos += len(line)
+                return line[:-1]
+            try:
+                chunk = next(self.byte_iterator)
+            except StopIteration:
+                if self.read_pos < self.buffer.getbuffer().nbytes:
+                    continue
+                raise
+            if "PayloadPart" not in chunk:
+                # handle API response errors and force terminate.
+                handle_stream_errors(chunk)
+                # print and move on to next response byte
+                print("Unknown event type:" + chunk)
+                continue
+            self.buffer.seek(0, io.SEEK_END)
+            self.buffer.write(chunk["PayloadPart"]["Bytes"])