Python SDK

MLAideClient

This is the main entry point to use this library. Creates a connection to the ML Aide server and provides read and write access to all resources.

__init__(self, project_key, options=None) special

Creates a new instance of this class.

Parameters:

Name	Type	Description	Default
project_key	str	The key of the project, that should be accessed. All operations will be made on this project.	required
options	ConnectionOptions	Optional options that will be used to establish a connection.	None

Source code in mlaide/client.py

def __init__(self, project_key: str, options: ConnectionOptions = None):
    """Creates a new instance of this class.

    Arguments:
        project_key: The key of the project, that should be accessed. All operations will be made on this project.
        options: Optional options that will be used to establish a connection.
    """
    if project_key is None:
        raise ValueError("project key must be not None")
    self.__project_key = project_key

    if options is None:
        self.__options = MLAideClient.__get_default_options()
    else:
        self.__options = MLAideClient.__merge_options(MLAideClient.__get_default_options(), options)

    self.__api_client = AuthenticatedClient(base_url=self.__options.server_url,
                                            api_key=self.__options.api_key)

get_artifact(self, name, version)

Gets an existing artifact. The artifact is specified by its name and version. If no version is specified, the latest available version of the artifact will be used.

Parameters:

Name	Type	Description	Default
name	str	The name of the artifact.	required
version	Optional[int]	The (optional) version of the artifact. If no version is specified, the latest available version	required

Returns:

Type	Description
ActiveArtifact	This object encapsulates an artifact and provides functions to interact with the artifact.

Source code in mlaide/client.py

def get_artifact(self, name: str, version: Optional[int]) -> ActiveArtifact:
    """Gets an existing artifact. The artifact is specified by its name and version. If no version
    is specified, the latest available version of the artifact will be used.

    Arguments:
        name: The name of the artifact.
        version: The (optional) version of the artifact. If no version is specified, the latest available version
        will be loaded.

    Returns:
         This object encapsulates an artifact and provides functions to interact with the artifact.
    """

    return ActiveArtifact(self.__api_client, self.__project_key, name, version)

load_model(self, name, version=None, stage=None)

Loads and restores a model. The model is specified by its name and version. If no version is specified, the latest available version of the model will be used.

Parameters:

Name	Type	Description	Default
name	str	The name of the model.	required
version	Optional[int]	The (optional) version of the model. If no version is specified, the latest available version	None
stage	Optional[ModelStage]	This argument can only be used when version is None. In this case the latest model can be filtered	None

Returns:

Type	Description
any	The model. E.g. in the case of a scikit-learn model the return value will be a deserialized model that can be used for predictions using .predict(...).

Source code in mlaide/client.py

def load_model(self,
               name: str,
               version: Optional[int] = None,
               stage: Optional[ModelStage] = None) -> any:
    """Loads and restores a model. The model is specified by its name and version. If no version
    is specified, the latest available version of the model will be used.

    Arguments:
        name: The name of the model.
        version: The (optional) version of the model. If no version is specified, the latest available version
        will be loaded.
        stage: This argument can only be used when version is None. In this case the latest model can be filtered
        by its stage. In reverse this means that all model versions will be ignored when they have not the specified
        stage.

    Returns:
         The model. E.g. in the case of a scikit-learn model the return value will be a deserialized model that
         can be used for predictions using `.predict(...)`.
     """

    if version is not None and stage is not None:
        raise ValueError("Only one argument of version and stage can be not None")

    return ActiveArtifact(self.__api_client, self.__project_key, name, version, stage).load_model()

start_new_run(self, experiment_key=None, run_name=None, used_artifacts=None, auto_create_experiment=True)

Creates and starts a new run, that will be assigned to the specified experiment. The run object can be used to log all necessary information.

Parameters:

Name	Type	Description	Default
experiment_key	str	The key of the experiment, that the new run should be assigned to. If None a new, random	None
run_name	str	The name of the run. The name helps to identify the run for humans. If None a random name will	None
used_artifacts	List[ArtifactRef]	An optional list of ArtifactRef that references artifacts, that are used as input for	None
auto_create_experiment	bool	Specifies whether the experiment (see experiment_key) should be created if it	True

Returns:

Type	Description
ActiveRun	This object encapsulates the newly created run and provides functions to log all information that belongs to the run.

Source code in mlaide/client.py

def start_new_run(self,
                  experiment_key: str = None,
                  run_name: str = None,
                  used_artifacts: List[ArtifactRef] = None,
                  auto_create_experiment: bool = True) -> ActiveRun:
    """Creates and starts a new run, that will be assigned to the specified experiment. The run object can be used
    to log all necessary information.

    Arguments:
        experiment_key: The key of the experiment, that the new run should be assigned to. If `None` a new, random
        experiment will be created.
        run_name: The name of the run. The name helps to identify the run for humans. If `None` a random name will
        be used.
        used_artifacts: An optional list of `ArtifactRef` that references artifacts, that are used as input for
        this run. This information will help to create and visualize the experiment lineage.
        auto_create_experiment: Specifies whether the experiment (see `experiment_key`) should be created if it
        does not exist or not. If `auto_create_experiment` is `False` and the experiment does not exist an error
        will be raised.

    Returns:
        This object encapsulates the newly created run and provides functions to log all information \
        that belongs to the run.
    """
    return ActiveRun(self.__api_client,
                     self.__project_key,
                     experiment_key,
                     run_name,
                     used_artifacts,
                     auto_create_experiment)

---

Active Run

This class provides access to runs that are stored in ML Aide

add_artifact_file(self, artifact, file, filename=None)

Add a file to an existing artifact. To add multiple file, specify a directory or invoke this function multiple times.

Parameters:

Name	Type	Description	Default
artifact	Artifact	The artifact to which the file should be added.	required
file	Union[str, _io.BytesIO]	The file that should be added. This can be a io.BytesIO object or a string to a file or directory.	required
filename	str	The filename. If the file is of type BytesIO the filename must be specified. If the file is a string, the original filename will be the default.	None

Source code in mlaide/active_run.py

def add_artifact_file(self, artifact: Artifact, file: Union[str, BytesIO], filename: str = None):
    """Add a file to an existing artifact. To add multiple file, specify a directory or invoke this function
    multiple times.

    Arguments:
        artifact: The artifact to which the file should be added.
        file: The file that should be added. This can be a io.BytesIO object or a string to a file or directory.
        filename: The filename. If the file is of type BytesIO the filename must be specified. If the file is a
            string, the original filename will be the default.
    """
    artifact_api.upload_file(
        client=self.__api_client,
        project_key=self.__project_key,
        artifact_name=artifact.name,
        artifact_version=artifact.version,
        filename=filename if filename is not None else ActiveRun.__extract_filename(file),
        file=ActiveRun.__normalize_file(file))

create_artifact(self, name, artifact_type, metadata)

Creates a new artifact. If an artifact with the same name already exists, a new artifact with the next available version number will be registered.

Parameters:

Name	Type	Description	Default
name	str	The name of the artifact.	required
artifact_type	str	The artifact type.	required
metadata	Optional[Dict[str, str]]	Some optional metadata that will be attached to the artifact.	required

Source code in mlaide/active_run.py

def create_artifact(self, name: str, artifact_type: str, metadata: Optional[Dict[str, str]]) -> Artifact:
    """Creates a new artifact. If an artifact with the same name already exists, a new artifact with the
    next available version number will be registered.

    Arguments:
        name: The name of the artifact.
        artifact_type: The artifact type.
        metadata: Some optional metadata that will be attached to the artifact.
    """
    artifact_dto = ArtifactDto(name=name, type=artifact_type, metadata=metadata, run_key=self.__run.key)

    artifact_dto = artifact_api.create_artifact(
        client=self.__api_client,
        project_key=self.__project_key,
        artifact=artifact_dto)

    return dto_to_artifact(artifact_dto)

log_metric(self, key, value)

Logs a metric

Parameters:

Name	Type	Description	Default
key	str	The key of the metric.	required
value		The value of the metric. The value can be any type that is JSON serializable.	required

Source code in mlaide/active_run.py

def log_metric(self, key: str, value) -> Run:
    """Logs a metric

    Arguments:
        key: The key of the metric.
        value: The value of the metric. The value can be any type that is JSON serializable.
    """
    self.__run.metrics[key] = value
    run_api.update_run_metrics(
        client=self.__api_client,
        project_key=self.__project_key,
        run_key=self.__run.key,
        metrics={key: value})
    return self.__run

log_model(self, model, model_name, metadata=None)

Creates a new artifact with type 'model'. The artifact will be registered as model.

Parameters:

Name	Type	Description	Default
model		The model. The model must be serializable.	required
model_name	str	The name of the model. The name will be used as artifact filename.	required
metadata	Optional[Dict[str, str]]	Some optional metadata that will be attached to the artifact.	None

Source code in mlaide/active_run.py

def log_model(self, model, model_name: str, metadata: Optional[Dict[str, str]] = None):
    """Creates a new artifact with type 'model'. The artifact will be registered as model.

    Arguments:
        model: The model. The model must be serializable.
        model_name: The name of the model. The name will be used as artifact filename.
        metadata: Some optional metadata that will be attached to the artifact.
    """
    serialized_model = _model_deser.serialize(model)

    artifact = self.create_artifact(name=model_name, artifact_type='model', metadata=metadata)
    self.add_artifact_file(artifact=artifact, file=serialized_model, filename='model.pkl')

    artifact_api.create_model(
        client=self.__api_client,
        project_key=self.__project_key,
        artifact_name=artifact.name,
        artifact_version=artifact.version)

log_parameter(self, key, value)

Logs a parameter

Parameters:

Name	Type	Description	Default
key	str	The key of the parameter.	required
value		The value of the parameter. The value must be a scalar value (e.g. string, int, float, ...).	required

Source code in mlaide/active_run.py

def log_parameter(self, key: str, value) -> Run:
    """Logs a parameter

    Arguments:
        key: The key of the parameter.
        value: The value of the parameter. The value must be a scalar value (e.g. string, int, float, ...).
    """
    self.__run.parameters[key] = value
    run_api.update_run_parameters(
        client=self.__api_client,
        project_key=self.__project_key,
        run_key=self.__run.key,
        parameters={key: value})
    return self.__run

set_completed_status(self)

Sets the status of the current run as completed.

Source code in mlaide/active_run.py

def set_completed_status(self) -> Run:
    """Sets the status of the current run as completed."""
    return self._set_status(RunStatus.COMPLETED)

set_failed_status(self)

Sets the status of the current run as failed.

Source code in mlaide/active_run.py

def set_failed_status(self) -> Run:
    """Sets the status of the current run as failed."""
    return self._set_status(RunStatus.FAILED)

---

Active Artifact

This class provides access to artifacts that are stored in ML Aide

download(self, target_directory)

Downloads all files of this artifact and stores them into the specified directory.

Parameters:

Name	Type	Description	Default
target_directory	str	The path to the directory where all files should be stored.	required

Source code in mlaide/active_artifact.py

def download(self, target_directory: str):
    """Downloads all files of this artifact and stores them into the specified directory.

    Arguments:
        target_directory: The path to the directory where all files should be stored.
    """

    # download
    artifact_bytes, artifact_filename = self.__download_zip()

    # unzip and write to disk
    with ZipFile(artifact_bytes) as z:
        z.extractall(target_directory)

load(self, filename)

Load a specific file of this artifact into memory

Parameters:

Name	Type	Description	Default
filename	str	The name of the file that should be loaded	required

Source code in mlaide/active_artifact.py

def load(self, filename: str) -> BytesIO:
    """Load a specific file of this artifact into memory

    Arguments:
        filename: The name of the file that should be loaded
    """

    # TODO: Do not download whole zip; instead download just the single file
    zip_bytes, zip_filename = self.__download_zip()
    with ZipFile(zip_bytes) as z:
        zip_info = z.infolist()
        desired_file = next(info for info in zip_info if info.filename == filename)
        with z.open(desired_file, 'r') as zip_file:
            return BytesIO(zip_file.read())