oracle-ads 2.11.8__py3-none-any.whl → 2.11.10__py3-none-any.whl

ads/aqua/{utils.py → common/utils.py}

@@ -10,7 +10,6 @@ import logging
 import os
 import random
 import re
-from enum import Enum
 from functools import wraps
 from pathlib import Path
 from string import Template
@@ -20,64 +19,26 @@ import fsspec
 import oci
 from oci.data_science.models import JobRun, Model
 
-from ads.aqua.constants import RqsAdditionalDetails
+from ads.aqua.common.enums import RqsAdditionalDetails
+from ads.aqua.common.errors import (
+    AquaFileNotFoundError,
+    AquaRuntimeError,
+    AquaValueError,
+)
+from ads.aqua.constants import *
 from ads.aqua.data import AquaResourceIdentifier
-from ads.aqua.exception import AquaFileNotFoundError, AquaRuntimeError, AquaValueError
 from ads.common.auth import default_signer
+from ads.common.extended_enum import ExtendedEnumMeta
 from ads.common.object_storage_details import ObjectStorageDetails
 from ads.common.oci_resource import SEARCH_TYPE, OCIResource
-from ads.common.utils import get_console_link, upload_to_os
+from ads.common.utils import get_console_link, upload_to_os, copy_file
 from ads.config import AQUA_SERVICE_MODELS_BUCKET, CONDA_BUCKET_NS, TENANCY_OCID
 from ads.model import DataScienceModel, ModelVersionSet
 
 logger = logging.getLogger("ads.aqua")
 
-UNKNOWN = ""
-UNKNOWN_DICT = {}
-README = "README.md"
-LICENSE_TXT = "config/LICENSE.txt"
-DEPLOYMENT_CONFIG = "deployment_config.json"
-COMPARTMENT_MAPPING_KEY = "service-model-compartment"
-CONTAINER_INDEX = "container_index.json"
-EVALUATION_REPORT_JSON = "report.json"
-EVALUATION_REPORT_MD = "report.md"
-EVALUATION_REPORT = "report.html"
-UNKNOWN_JSON_STR = "{}"
-CONSOLE_LINK_RESOURCE_TYPE_MAPPING = dict(
-    datasciencemodel="models",
-    datasciencemodeldeployment="model-deployments",
-    datasciencemodeldeploymentdev="model-deployments",
-    datasciencemodeldeploymentint="model-deployments",
-    datasciencemodeldeploymentpre="model-deployments",
-    datasciencejob="jobs",
-    datasciencejobrun="job-runs",
-    datasciencejobrundev="job-runs",
-    datasciencejobrunint="job-runs",
-    datasciencejobrunpre="job-runs",
-    datasciencemodelversionset="model-version-sets",
-    datasciencemodelversionsetpre="model-version-sets",
-    datasciencemodelversionsetint="model-version-sets",
-    datasciencemodelversionsetdev="model-version-sets",
-)
-FINE_TUNING_RUNTIME_CONTAINER = "iad.ocir.io/ociodscdev/aqua_ft_cuda121:0.3.17.20"
-DEFAULT_FT_BLOCK_STORAGE_SIZE = 750
-DEFAULT_FT_REPLICA = 1
-DEFAULT_FT_BATCH_SIZE = 1
-DEFAULT_FT_VALIDATION_SET_SIZE = 0.1
-
-HF_MODELS = "/home/datascience/conda/pytorch21_p39_gpu_v1/"
-MAXIMUM_ALLOWED_DATASET_IN_BYTE = 52428800  # 1024 x 1024 x 50 = 50MB
-JOB_INFRASTRUCTURE_TYPE_DEFAULT_NETWORKING = "ME_STANDALONE"
-NB_SESSION_IDENTIFIER = "NB_SESSION_OCID"
-LIFECYCLE_DETAILS_MISSING_JOBRUN = "The asscociated JobRun resource has been deleted."
-READY_TO_DEPLOY_STATUS = "ACTIVE"
-READY_TO_FINE_TUNE_STATUS = "TRUE"
-AQUA_GA_LIST = ["id19sfcrra6z"]
-AQUA_MODEL_TYPE_SERVICE = "service"
-AQUA_MODEL_TYPE_CUSTOM = "custom"
-
-
-class LifecycleStatus(Enum):
+
+class LifecycleStatus(str, metaclass=ExtendedEnumMeta):
     UNKNOWN = ""
 
     @property
@@ -136,8 +97,6 @@ LIFECYCLE_DETAILS_MAPPING = {
     JobRun.LIFECYCLE_STATE_FAILED: "The evaluation failed.",
     JobRun.LIFECYCLE_STATE_NEEDS_ATTENTION: "Missing jobrun information.",
 }
-SUPPORTED_FILE_FORMATS = ["jsonl"]
-MODEL_BY_REFERENCE_OSS_PATH_KEY = "artifact_location"
 
 
 def random_color_generator(word: str):
@@ -201,22 +160,28 @@ def get_artifact_path(custom_metadata_list: List) -> str:
     Parameters
     ----------
     custom_metadata_list: List
-        A list of custom metadata of model.
+        A list of custom metadata of OCI model.
 
     Returns
     -------
     str:
         The artifact path from model.
     """
-    for custom_metadata in custom_metadata_list:
-        if custom_metadata.key == MODEL_BY_REFERENCE_OSS_PATH_KEY:
-            if ObjectStorageDetails.is_oci_path(custom_metadata.value):
-                artifact_path = custom_metadata.value
-            else:
-                artifact_path = ObjectStorageDetails(
-                    AQUA_SERVICE_MODELS_BUCKET, CONDA_BUCKET_NS, custom_metadata.value
-                ).path
-            return artifact_path
+    try:
+        for custom_metadata in custom_metadata_list:
+            if custom_metadata.key == MODEL_BY_REFERENCE_OSS_PATH_KEY:
+                if ObjectStorageDetails.is_oci_path(custom_metadata.value):
+                    artifact_path = custom_metadata.value
+                else:
+                    artifact_path = ObjectStorageDetails(
+                        AQUA_SERVICE_MODELS_BUCKET,
+                        CONDA_BUCKET_NS,
+                        custom_metadata.value,
+                    ).path
+                return artifact_path
+    except Exception as ex:
+        logger.debug(ex)
+
     logger.debug("Failed to get artifact path from custom metadata.")
     return UNKNOWN
 
@@ -260,12 +225,10 @@ def is_valid_ocid(ocid: str) -> bool:
     bool:
         Whether the given ocid is valid.
     """
-    # TODO: revisit pattern
-    pattern = (
-        r"^ocid1\.([a-z0-9_]+)\.([a-z0-9]+)\.([a-z0-9-]*)(\.[^.]+)?\.([a-z0-9_]+)$"
-    )
-    match = re.match(pattern, ocid)
-    return True
+
+    if not ocid:
+        return False
+    return ocid.lower().startswith("ocid")
 
 
 def get_resource_type(ocid: str) -> str:
@@ -520,6 +483,19 @@ def _build_job_identifier(
         return AquaResourceIdentifier()
 
 
+def container_config_path():
+    return f"oci://{AQUA_SERVICE_MODELS_BUCKET}@{CONDA_BUCKET_NS}/service_models/config"
+
+
+def get_container_config():
+    config = load_config(
+        file_path=container_config_path(),
+        config_file_name=CONTAINER_INDEX,
+    )
+
+    return config
+
+
 def get_container_image(
     config_file_name: str = None, container_type: str = None
 ) -> str:
@@ -537,14 +513,8 @@ def get_container_image(
         A dict of allowed configs.
     """
 
-    config_file_name = (
-        f"oci://{AQUA_SERVICE_MODELS_BUCKET}@{CONDA_BUCKET_NS}/service_models/config"
-    )
-
-    config = load_config(
-        file_path=config_file_name,
-        config_file_name=CONTAINER_INDEX,
-    )
+    config = config_file_name or get_container_config()
+    config_file_name = container_config_path()
 
     if container_type not in config:
         raise AquaValueError(
@@ -582,9 +552,10 @@ def fetch_service_compartment() -> Union[str, None]:
             file_path=config_file_name,
             config_file_name=CONTAINER_INDEX,
         )
-    except AquaFileNotFoundError:
-        logger.error(
-            f"Config file {config_file_name}/{CONTAINER_INDEX} to fetch service compartment OCID could not be found."
+    except Exception as e:
+        logger.debug(
+            f"Config file {config_file_name}/{CONTAINER_INDEX} to fetch service compartment OCID could not be found. "
+            f"\n{str(e)}."
         )
         return
     compartment_mapping = config.get(COMPARTMENT_MAPPING_KEY)
@@ -749,3 +720,124 @@ def get_ocid_substring(ocid: str, key_len: int) -> str:
     """This helper function returns the last n characters of the ocid specified by key_len parameter.
     If ocid is None or length is less than key_len, it returns an empty string."""
     return ocid[-key_len:] if ocid and len(ocid) > key_len else ""
+
+
+def is_service_managed_container(container):
+    return container and container.startswith(SERVICE_MANAGED_CONTAINER_URI_SCHEME)
+
+
+def get_params_list(params: str) -> List[str]:
+    """Parses the string parameter and returns a list of params.
+
+    Parameters
+    ----------
+    params
+        string parameters by separated by -- delimiter
+
+    Returns
+    -------
+        list of params
+
+    """
+    if not params:
+        return []
+    return ["--" + param.strip() for param in params.split("--")[1:]]
+
+
+def get_params_dict(params: Union[str, List[str]]) -> dict:
+    """Accepts a string or list of string of double-dash parameters and returns a dict with the parameter keys and values.
+
+    Parameters
+    ----------
+    params:
+        List of parameters or parameter string separated by space.
+
+    Returns
+    -------
+        dict containing parameter keys and values
+
+    """
+    params_list = get_params_list(params) if isinstance(params, str) else params
+    return {
+        split_result[0]: split_result[1] if len(split_result) > 1 else UNKNOWN
+        for split_result in (x.split() for x in params_list)
+    }
+
+
+def get_combined_params(params1: str = None, params2: str = None) -> str:
+    """
+    Combines string of double-dash parameters, and overrides the values from the second string in the first.
+    Parameters
+    ----------
+    params1:
+        Parameter string with values
+    params2:
+        Parameter string with values that need to be overridden.
+
+    Returns
+    -------
+        A combined list with overridden values from params2.
+    """
+    if not params1:
+        return params2
+    if not params2:
+        return params1
+
+    # overwrite values from params2 into params1
+    combined_params = [
+        f"{key} {value}" if value else key
+        for key, value in {
+            **get_params_dict(params1),
+            **get_params_dict(params2),
+        }.items()
+    ]
+
+    return " ".join(combined_params)
+
+
+def copy_model_config(artifact_path: str, os_path: str, auth: dict = None):
+    """Copies the aqua model config folder from the artifact path to the user provided object storage path.
+    The config folder is overwritten if the files already exist at the destination path.
+
+    Parameters
+    ----------
+    artifact_path:
+        Path of the aqua model where config folder is available.
+    os_path:
+        User provided path where config folder will be copied.
+    auth: (Dict, optional). Defaults to None.
+        The default authentication is set using `ads.set_auth` API. If you need to override the
+        default, use the `ads.common.auth.api_keys` or `ads.common.auth.resource_principal` to create appropriate
+        authentication signer and kwargs required to instantiate IdentityClient object.
+
+    Returns
+    -------
+    None
+        Nothing.
+    """
+
+    try:
+        source_dir = ObjectStorageDetails(
+            AQUA_SERVICE_MODELS_BUCKET,
+            CONDA_BUCKET_NS,
+            f"{os.path.dirname(artifact_path).rstrip('/')}/config",
+        ).path
+        dest_dir = f"{os_path.rstrip('/')}/config"
+
+        oss_details = ObjectStorageDetails.from_path(source_dir)
+        objects = oss_details.list_objects(fields="name").objects
+
+        for obj in objects:
+            source_path = ObjectStorageDetails(
+                AQUA_SERVICE_MODELS_BUCKET, CONDA_BUCKET_NS, obj.name
+            ).path
+            destination_path = os.path.join(dest_dir, os.path.basename(obj.name))
+            copy_file(
+                uri_src=source_path,
+                uri_dst=destination_path,
+                force_overwrite=True,
+                auth=auth,
+            )
+    except Exception as ex:
+        logger.debug(ex)
+        logger.debug(f"Failed to copy config folder from {artifact_path} to {os_path}.")

ads/aqua/config/config.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright (c) 2024 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+
+# TODO: move this to global config.json in object storage
+def get_finetuning_config_defaults():
+    """Generate and return the fine-tuning default configuration dictionary."""
+    return {
+        "shape": {
+            "VM.GPU.A10.1": {"batch_size": 1, "replica": "1-10"},
+            "VM.GPU.A10.2": {"batch_size": 1, "replica": "1-10"},
+            "BM.GPU.A10.4": {"batch_size": 1, "replica": 1},
+            "BM.GPU4.8": {"batch_size": 4, "replica": 1},
+            "BM.GPU.A100-v2.8": {"batch_size": 6, "replica": 1},
+        }
+    }

ads/aqua/constants.py

@@ -3,43 +3,61 @@
 # Copyright (c) 2024 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 """This module defines constants used in ads.aqua module."""
-from enum import Enum
 
+UNKNOWN = ""
 UNKNOWN_VALUE = ""
-
-
-class RqsAdditionalDetails:
-    METADATA = "metadata"
-    CREATED_BY = "createdBy"
-    DESCRIPTION = "description"
-    MODEL_VERSION_SET_ID = "modelVersionSetId"
-    MODEL_VERSION_SET_NAME = "modelVersionSetName"
-    PROJECT_ID = "projectId"
-    VERSION_LABEL = "versionLabel"
-
-
-class FineTuningDefinedMetadata(Enum):
-    """Represents the defined metadata keys used in Fine Tuning."""
-
-    VAL_SET_SIZE = "val_set_size"
-    TRAINING_DATA = "training_data"
-
-
-class FineTuningCustomMetadata(Enum):
-    """Represents the custom metadata keys used in Fine Tuning."""
-
-    FT_SOURCE = "fine_tune_source"
-    FT_SOURCE_NAME = "fine_tune_source_name"
-    FT_OUTPUT_PATH = "fine_tune_output_path"
-    FT_JOB_ID = "fine_tune_job_id"
-    FT_JOB_RUN_ID = "fine_tune_jobrun_id"
-    TRAINING_METRICS_FINAL = "train_metrics_final"
-    VALIDATION_METRICS_FINAL = "val_metrics_final"
-    TRAINING_METRICS_EPOCH = "train_metrics_epoch"
-    VALIDATION_METRICS_EPOCH = "val_metrics_epoch"
-
+READY_TO_IMPORT_STATUS = "TRUE"
+UNKNOWN_DICT = {}
+README = "README.md"
+LICENSE_TXT = "config/LICENSE.txt"
+DEPLOYMENT_CONFIG = "deployment_config.json"
+COMPARTMENT_MAPPING_KEY = "service-model-compartment"
+CONTAINER_INDEX = "container_index.json"
+EVALUATION_REPORT_JSON = "report.json"
+EVALUATION_REPORT_MD = "report.md"
+EVALUATION_REPORT = "report.html"
+UNKNOWN_JSON_STR = "{}"
+FINE_TUNING_RUNTIME_CONTAINER = "iad.ocir.io/ociodscdev/aqua_ft_cuda121:0.3.17.20"
+DEFAULT_FT_BLOCK_STORAGE_SIZE = 750
+DEFAULT_FT_REPLICA = 1
+DEFAULT_FT_BATCH_SIZE = 1
+DEFAULT_FT_VALIDATION_SET_SIZE = 0.1
+
+MAXIMUM_ALLOWED_DATASET_IN_BYTE = 52428800  # 1024 x 1024 x 50 = 50MB
+JOB_INFRASTRUCTURE_TYPE_DEFAULT_NETWORKING = "ME_STANDALONE"
+NB_SESSION_IDENTIFIER = "NB_SESSION_OCID"
+LIFECYCLE_DETAILS_MISSING_JOBRUN = "The asscociated JobRun resource has been deleted."
+READY_TO_DEPLOY_STATUS = "ACTIVE"
+READY_TO_FINE_TUNE_STATUS = "TRUE"
+AQUA_GA_LIST = ["id19sfcrra6z"]
+AQUA_MODEL_TYPE_SERVICE = "service"
+AQUA_MODEL_TYPE_CUSTOM = "custom"
+AQUA_MODEL_ARTIFACT_CONFIG = "config.json"
+AQUA_MODEL_ARTIFACT_CONFIG_MODEL_NAME = "_name_or_path"
+AQUA_MODEL_ARTIFACT_CONFIG_MODEL_TYPE = "model_type"
 
 TRAINING_METRICS_FINAL = "training_metrics_final"
 VALIDATION_METRICS_FINAL = "validation_metrics_final"
 TRINING_METRICS = "training_metrics"
 VALIDATION_METRICS = "validation_metrics"
+
+SERVICE_MANAGED_CONTAINER_URI_SCHEME = "dsmc://"
+SUPPORTED_FILE_FORMATS = ["jsonl"]
+MODEL_BY_REFERENCE_OSS_PATH_KEY = "artifact_location"
+
+CONSOLE_LINK_RESOURCE_TYPE_MAPPING = dict(
+    datasciencemodel="models",
+    datasciencemodeldeployment="model-deployments",
+    datasciencemodeldeploymentdev="model-deployments",
+    datasciencemodeldeploymentint="model-deployments",
+    datasciencemodeldeploymentpre="model-deployments",
+    datasciencejob="jobs",
+    datasciencejobrun="job-runs",
+    datasciencejobrundev="job-runs",
+    datasciencejobrunint="job-runs",
+    datasciencejobrunpre="job-runs",
+    datasciencemodelversionset="model-version-sets",
+    datasciencemodelversionsetpre="model-version-sets",
+    datasciencemodelversionsetint="model-version-sets",
+    datasciencemodelversionsetdev="model-version-sets",
+)

ads/aqua/data.py

@@ -3,8 +3,7 @@
 # Copyright (c) 2024 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
-from dataclasses import dataclass
-from enum import Enum
+from dataclasses import dataclass, field
 
 from ads.common.serializer import DataClassSerializable
 
@@ -16,27 +15,17 @@ class AquaResourceIdentifier(DataClassSerializable):
     url: str = ""
 
 
-class Resource(Enum):
-    JOB = "jobs"
-    JOBRUN = "jobruns"
-    MODEL = "models"
-    MODEL_DEPLOYMENT = "modeldeployments"
-    MODEL_VERSION_SET = "model-version-sets"
-
-
-class DataScienceResource(Enum):
-    MODEL_DEPLOYMENT = "datasciencemodeldeployment"
-    MODEL = "datasciencemodel"
-
-
-class Tags(Enum):
-    TASK = "task"
-    LICENSE = "license"
-    ORGANIZATION = "organization"
-    AQUA_TAG = "OCI_AQUA"
-    AQUA_SERVICE_MODEL_TAG = "aqua_service_model"
-    AQUA_FINE_TUNED_MODEL_TAG = "aqua_fine_tuned_model"
-    AQUA_MODEL_NAME_TAG = "aqua_model_name"
-    AQUA_EVALUATION = "aqua_evaluation"
-    AQUA_FINE_TUNING = "aqua_finetuning"
-    READY_TO_FINE_TUNE = "ready_to_fine_tune"
+@dataclass(repr=False)
+class AquaJobSummary(DataClassSerializable):
+    """Represents an Aqua job summary."""
+
+    id: str
+    name: str
+    console_url: str
+    lifecycle_state: str
+    lifecycle_details: str
+    time_created: str
+    tags: dict
+    experiment: AquaResourceIdentifier = field(default_factory=AquaResourceIdentifier)
+    source: AquaResourceIdentifier = field(default_factory=AquaResourceIdentifier)
+    job: AquaResourceIdentifier = field(default_factory=AquaResourceIdentifier)

ads/aqua/evaluation/__init__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2024 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+from ads.aqua.evaluation.evaluation import AquaEvaluationApp
+
+__all__ = ["AquaEvaluationApp"]

ads/aqua/evaluation/constants.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright (c) 2024 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""
+aqua.evaluation.const
+~~~~~~~~~~~~~~
+
+This module contains constants/enums used in Aqua Evaluation.
+"""
+from oci.data_science.models import JobRun
+
+from ads.common.extended_enum import ExtendedEnumMeta
+
+EVAL_TERMINATION_STATE = [
+    JobRun.LIFECYCLE_STATE_SUCCEEDED,
+    JobRun.LIFECYCLE_STATE_FAILED,
+]
+
+
+class EvaluationCustomMetadata(str, metaclass=ExtendedEnumMeta):
+    EVALUATION_SOURCE = "evaluation_source"
+    EVALUATION_JOB_ID = "evaluation_job_id"
+    EVALUATION_JOB_RUN_ID = "evaluation_job_run_id"
+    EVALUATION_OUTPUT_PATH = "evaluation_output_path"
+    EVALUATION_SOURCE_NAME = "evaluation_source_name"
+    EVALUATION_ERROR = "aqua_evaluate_error"
+
+
+class EvaluationConfig(str, metaclass=ExtendedEnumMeta):
+    PARAMS = "model_params"
+
+
+class EvaluationReportJson(str, metaclass=ExtendedEnumMeta):
+    """Contains evaluation report.json fields name."""
+
+    METRIC_SUMMARY_RESULT = "metric_summary_result"
+    METRIC_RESULT = "metric_results"
+    MODEL_PARAMS = "model_params"
+    MODEL_DETAILS = "model_details"
+    DATA = "data"
+    DATASET = "dataset"
+
+
+class EvaluationMetricResult(str, metaclass=ExtendedEnumMeta):
+    """Contains metric result's fields name in report.json."""
+
+    SHORT_NAME = "key"
+    NAME = "name"
+    DESCRIPTION = "description"
+    SUMMARY_DATA = "summary_data"
+    DATA = "data"