oracle-ads 2.13.11__py3-none-any.whl → 2.13.13__py3-none-any.whl

ads/aqua/verify_policies/verify.py

@@ -0,0 +1,345 @@
+import logging
+
+import click
+import oci.exceptions
+
+from ads.aqua.verify_policies.constants import POLICY_HELP_LINK, TEST_JOB_NAME, TEST_JOB_RUN_NAME, TEST_LIMIT_NAME, \
+    TEST_MVS_NAME, TEST_MD_NAME, TEST_VM_SHAPE
+from ads.aqua.verify_policies.messages import operation_messages
+from ads.aqua.verify_policies.entities import OperationResultSuccess, OperationResultFailure, PolicyStatus
+from ads.aqua.verify_policies.utils import PolicyValidationError, VerifyPoliciesUtils, RichStatusLog
+from functools import wraps
+
+logger = logging.getLogger("aqua.policies")
+
+
+def with_spinner(func):
+    """Decorator to wrap execution of a function with a rich UI spinner.
+
+       Displays status while the operation runs and logs success or failure messages
+       based on the policy verification result.
+    """
+
+    @wraps(func)
+    def wrapper(self, function, **kwargs):
+        operation_message = operation_messages[function.__name__]
+        ignore_spinner = kwargs.pop("ignore_spinner", False)
+
+        def run_func():
+            return_value, result_status = func(self, function, **kwargs)
+            result_message = f"{self._rich_ui.get_status_emoji(result_status.status)} {result_status.operation}"
+            if result_status.status == PolicyStatus.SUCCESS:
+                logger.info(result_message)
+            else:
+                logger.warning(result_message)
+                logger.info(result_status.error)
+                logger.info(f"Policy hint: {result_status.policy_hint}")
+                logger.info(f"Refer to: {POLICY_HELP_LINK}")
+                
+            return return_value, result_status
+
+        if ignore_spinner:
+            return run_func()
+        else:
+            with self._rich_ui.console.status(f"Verifying {operation_message['name']}") as status:
+                return run_func()
+
+    return wrapper
+
+
+class AquaVerifyPoliciesApp:
+    """
+    AquaVerifyPoliciesApp provides methods to verify IAM policies required for
+    various operations in OCI Data Science's AQUA (Accelerated Data Science) platform.
+
+    This utility is intended to help users validate whether they have the necessary
+    permissions to perform common AQUA workflows such as model registration,
+    deployment, evaluation, and fine-tuning.
+
+    Methods
+    -------
+    `common_policies()`: Validates basic read-level policies across AQUA components.
+    `model_register()`: Checks policies for object storage access and model registration.
+    `model_deployment()`: Validates policies for registering and deploying models.
+    `evaluation()`: Confirms ability to manage model version sets, jobs, and storage for evaluation.
+    `finetune()`: Verifies access required to fine-tune models.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._util = VerifyPoliciesUtils()
+        self._rich_ui = RichStatusLog()
+        self.model_id = None
+        logger.propagate = False
+        logger.setLevel(logging.INFO)
+
+    def _get_operation_result(self, operation, status):
+        """Maps a function and policy status to a corresponding result object.
+
+            Parameters:
+                operation (function): The operation being verified.
+                status (PolicyStatus): The outcome of the policy verification.
+
+            Returns:
+                OperationResultSuccess or OperationResultFailure based on status.
+        """
+        operation_message = operation_messages[operation.__name__]
+        if status == PolicyStatus.SUCCESS:
+            return OperationResultSuccess(operation=operation_message["name"])
+        if status == PolicyStatus.UNVERIFIED:
+            return OperationResultSuccess(operation=operation_message["name"], status=status)
+        if status == PolicyStatus.FAILURE:
+            return OperationResultFailure(operation=operation_message["name"], error=operation_message["error"],
+                                          policy_hint=f"{operation_message['policy_hint']}" )
+
+    @with_spinner
+    def _execute(self, function, **kwargs):
+        """Executes a given operation function with policy validation and error handling.
+            Parameters:
+                function (callable): The function to execute.
+                kwargs (dict): Keyword arguments to pass to the function.
+
+            Returns:
+                Tuple: (result, OperationResult)
+        """
+        result = None
+        try:
+            result = function(**kwargs)
+            status = PolicyStatus.SUCCESS
+        except oci.exceptions.ServiceError as oci_error:
+            if oci_error.status == 404:
+                logger.debug(oci_error)
+                status = PolicyStatus.FAILURE
+            else:
+                logger.error(oci_error)
+                raise oci_error
+        except PolicyValidationError as policy_error:
+            status = PolicyStatus.FAILURE
+        except Exception as e:
+            logger.error(e)
+            raise e
+        return result, self._get_operation_result(function, status)
+
+    def _test_model_register(self, **kwargs):
+        """Verifies policies required to manage an object storage bucket and register a model.
+
+           Returns:
+               List of result dicts for bucket management and model registration.
+        """
+        result = []
+        bucket = kwargs.pop("bucket")
+        _, test_manage_obs_policy = self._execute(self._util.manage_bucket, bucket=bucket, **kwargs)
+        result.append(test_manage_obs_policy.to_dict())
+
+        if test_manage_obs_policy.status == PolicyStatus.SUCCESS:
+            self.model_id, test_model_register = self._execute(self._util.register_model)
+            result.append(test_model_register.to_dict())
+        return result
+
+    def _test_delete_model(self, **kwargs):
+        """Attempts to delete the test model created during model registration.
+
+            Returns:
+                List containing the result of model deletion.
+        """
+        if self.model_id is not None:
+            _, test_delete_model_test = self._execute(self._util.aqua_model.ds_client.delete_model,
+                                                      model_id=self.model_id, **kwargs)
+            return [test_delete_model_test.to_dict()]
+        else:
+            return [self._get_operation_result(self._util.aqua_model.ds_client.delete_model,
+                                               PolicyStatus.UNVERIFIED).to_dict()]
+
+    def _test_model_deployment(self, **kwargs):
+        """Verifies policies required to create and delete a model deployment.
+
+           Returns:
+               List of result dicts for deployment creation and deletion.
+        """
+        logger.info(f"Creating Model Deployment with name {TEST_MD_NAME}")
+        md_ocid, test_model_deployment = self._execute(self._util.create_model_deployment, model_id=self.model_id,
+                                                       instance_shape=TEST_VM_SHAPE)
+        _, test_delete_md = self._execute(self._util.aqua_model.ds_client.delete_model_deployment, model_deployment_id=md_ocid)
+        return [test_model_deployment.to_dict(), test_delete_md.to_dict()]
+
+    def _test_manage_mvs(self, **kwargs):
+        """Verifies policies required to create and delete a model version set (MVS).
+
+            Returns:
+                List of result dicts for MVS creation and deletion.
+        """
+        logger.info(f"Creating ModelVersionSet with name {TEST_MVS_NAME}")
+
+        model_mvs, test_create_mvs = self._execute(self._util.create_model_version_set, name=TEST_MVS_NAME)
+        model_mvs_id = model_mvs[0]
+        if model_mvs_id:
+            logger.info(f"Deleting ModelVersionSet {TEST_MVS_NAME}")
+            _, delete_mvs = self._execute(self._util.aqua_model.ds_client.delete_model_version_set,
+                                          model_version_set_id=model_mvs_id)
+        else:
+            delete_mvs = self._get_operation_result(self._util.aqua_model.ds_client.delete_model_version_set,
+                                                    PolicyStatus.UNVERIFIED)
+        return [test_create_mvs.to_dict(), delete_mvs.to_dict()]
+
+    def _test_manage_job(self, **kwargs):
+        """Verifies policies required to create a job, create a job run, and delete the job.
+
+            Returns:
+                List of result dicts for job creation, job run creation, and job deletion.
+        """
+        
+        logger.info(f"Creating Job with name {TEST_JOB_NAME}")
+        
+        # Create Job & JobRun.
+        job_id, test_create_job = self._execute(self._util.create_job, display_name=TEST_JOB_NAME,
+                                                           **kwargs)
+        
+        logger.info(f"Creating JobRun with name {TEST_JOB_RUN_NAME}")
+        
+        _, test_create_job_run = self._execute(self._util.create_job_run, display_name=TEST_JOB_RUN_NAME,
+                                               job_id=job_id, **kwargs)
+
+        # Delete Job Run
+        if job_id:
+            _, delete_job = self._execute(self._util.aqua_model.ds_client.delete_job, job_id=job_id, delete_related_job_runs=True)
+        else:
+            delete_job = self._get_operation_result(self._util.aqua_model.ds_client.delete_job, PolicyStatus.UNVERIFIED)
+
+        return [test_create_job.to_dict(), test_create_job_run.to_dict(), delete_job.to_dict()]
+
+    def _prompt(self, message, bool=False):
+        """Wrapper for Click prompt or confirmation.
+
+            Parameters:
+                message (str): The prompt message.
+                bool (bool): Whether to ask for confirmation instead of input.
+
+            Returns:
+                User input or confirmation (bool/str).
+        """
+        if bool:
+            return click.confirm(message, default=False)
+        else:
+            return click.prompt(message, type=str)
+
+    def _consent(self):
+        """
+           Prompts the user for confirmation before performing actions.
+           Exits if the user does not consent.
+        """
+        answer = self._prompt("Do you want to continue?", bool=True)
+        if not answer:
+            exit(0)
+
+    def common_policies(self, **kwargs):
+        """Verifies basic read-level policies across various AQUA components
+           (e.g. compartments, models, jobs, buckets, logs).
+
+           Returns:
+               List of result dicts for each verified operation.
+        """
+        logger.info("[magenta]Verifying Common Policies")
+        basic_operations = [self._util.list_compartments, self._util.list_models, self._util.list_model_version_sets,
+                            self._util.list_project, self._util.list_jobs, self._util.list_job_runs,
+                            self._util.list_buckets,
+                            self._util.list_log_groups
+                            ]
+        result = []
+        for op in basic_operations:
+            _, status = self._execute(op, **kwargs)
+            result.append(status.to_dict())
+
+        _, get_resource_availability_status = self._execute(self._util.get_resource_availability,
+                                                            limit_name=TEST_LIMIT_NAME)
+        result.append(get_resource_availability_status.to_dict())
+        return result
+
+    def model_register(self, **kwargs):
+        """Verifies policies required to register a model, including object storage access.
+
+            Returns:
+                List of result dicts for registration and cleanup.
+        """
+        logger.info("[magenta]Verifying Model Register")
+        logger.info("Object and Model will be created.")
+        kwargs.pop("consent", None) == True or self._consent()
+
+        model_save_bucket = kwargs.pop("bucket", None) or self._prompt(
+            "Provide bucket name where model artifacts will be saved")
+        register_model_result = self._test_model_register(bucket=model_save_bucket)
+        delete_model_result = self._test_delete_model(**kwargs)
+        return [*register_model_result, *delete_model_result]
+
+    def model_deployment(self, **kwargs):
+        """Verifies policies required to register and deploy a model, and perform cleanup.
+
+            Returns:
+                List of result dicts for registration, deployment, and cleanup.
+        """
+        logger.info("[magenta]Verifying Model Deployment")
+        logger.info("Object, Model, Model deployment will be created.")
+        kwargs.pop("consent", None) == True or self._consent()
+        model_save_bucket = kwargs.pop("bucket", None) or self._prompt(
+            "Provide bucket name where model artifacts will be saved")
+        model_register = self._test_model_register(bucket=model_save_bucket)
+        model_deployment = self._test_model_deployment()
+        delete_model_result = self._test_delete_model(**kwargs)
+
+        return [*model_register, *model_deployment, *delete_model_result]
+
+    def evaluation(self, **kwargs):
+        """Verifies policies for evaluation workloads including model version set,
+            job and job runs, and object storage access.
+
+            Returns:
+                List of result dicts for all evaluation steps.
+        """
+        logger.info("[magenta]Verifying Evaluation")
+        logger.info("Model Version Set, Model, Object, Job and JobRun will be created.")
+        kwargs.pop("consent", None) == True or self._consent()
+
+        # Create & Delete MVS
+        test_manage_mvs = self._test_manage_mvs(**kwargs)
+
+        # Create & Model
+        model_save_bucket = kwargs.pop("bucket", None) or self._prompt(
+            "Provide bucket name where model artifacts will be saved")
+        register_model_result = self._test_model_register(bucket=model_save_bucket)
+        delete_model_result = self._test_delete_model(**kwargs)
+
+        # Manage Jobs & Job Runs
+        test_job_and_job_run = self._test_manage_job(**kwargs)
+
+        return [*test_manage_mvs, *register_model_result, *delete_model_result, *test_job_and_job_run]
+
+    def finetune(self, **kwargs):
+        """Verifies policies for fine-tuning jobs, including managing object storage,
+            MVS.
+
+            Returns:
+                List of result dicts for each fine-tuning operation.
+        """
+        logger.info("[magenta]Verifying Finetuning")
+        logger.info("Object, Model Version Set, Job and JobRun will be created. VCN will be used.")
+        kwargs.pop("consent", None) == True or self._consent()
+
+        # Manage bucket
+        bucket = kwargs.pop("bucket", None) or self._prompt(
+            "Provide bucket name required to save training datasets, scripts, and fine-tuned model outputs")
+        
+        subnet_id = kwargs.pop("subnet_id", None)
+        ignore_subnet = kwargs.pop("ignore_subnet", False)
+        
+        if subnet_id is None and not ignore_subnet and self._prompt("Do you want to use custom subnet", bool=True):
+            subnet_id = self._prompt("Provide subnet id")
+        
+        _, test_manage_obs_policy = self._execute(self._util.manage_bucket, bucket=bucket, **kwargs)
+
+        # Create & Delete MVS
+        test_manage_mvs = self._test_manage_mvs(**kwargs)
+
+        # Manage Jobs & Job Runs
+        test_job_and_job_run = self._test_manage_job(subnet_id = subnet_id, **kwargs)
+
+        return [*test_manage_mvs, *test_job_and_job_run, test_manage_obs_policy.to_dict()]
+

ads/aqua/version.json

@@ -0,0 +1,3 @@
+{
+  "aqua": "1.0.7"
+}

ads/common/oci_logging.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# -*- coding: utf-8; -*-
 
 # Copyright (c) 2021, 2024 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
@@ -7,16 +6,16 @@
 import datetime
 import logging
 import time
-from typing import Dict, Union, List
+from typing import Dict, List, Union
 
+import oci.exceptions
 import oci.logging
 import oci.loggingsearch
-import oci.exceptions
+
 from ads.common.decorator.utils import class_or_instance_method
 from ads.common.oci_mixin import OCIModelMixin, OCIWorkRequestMixin
 from ads.common.oci_resource import OCIResource, ResourceNotFoundError
 
-
 logger = logging.getLogger(__name__)
 
 # Maximum number of log records to be returned by default.
@@ -862,9 +861,7 @@ class ConsolidatedLog:
             time_start=time_start,
             log_filter=log_filter,
         )
-        self._print(
-            sorted(tail_logs, key=lambda log: log["time"])
-        )
+        self._print(sorted(tail_logs, key=lambda log: log["time"]))
 
     def head(
         self,

ads/common/work_request.py

@@ -1,7 +1,5 @@
 #!/usr/bin/env python
-# -*- coding: utf-8; -*-
-
-# Copyright (c) 2024 Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
 import logging
@@ -12,6 +10,7 @@ from typing import Callable
 import oci
 from oci import Signer
 from tqdm.auto import tqdm
+
 from ads.common.oci_datascience import OCIDataScienceMixin
 
 logger = logging.getLogger(__name__)
@@ -20,10 +19,10 @@ WORK_REQUEST_STOP_STATE = ("SUCCEEDED", "FAILED", "CANCELED")
 DEFAULT_WAIT_TIME = 1200
 DEFAULT_POLL_INTERVAL = 10
 WORK_REQUEST_PERCENTAGE = 100
-# default tqdm progress bar format: 
+# default tqdm progress bar format:
 # {l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, ' '{rate_fmt}{postfix}]
 # customize the bar format to remove the {n_fmt}/{total_fmt} from the right side
-DEFAULT_BAR_FORMAT = '{l_bar}{bar}| [{elapsed}<{remaining}, ' '{rate_fmt}{postfix}]'
+DEFAULT_BAR_FORMAT = "{l_bar}{bar}| [{elapsed}<{remaining}, " "{rate_fmt}{postfix}]"
 
 
 class DataScienceWorkRequest(OCIDataScienceMixin):
@@ -32,13 +31,13 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
     """
 
     def __init__(
-        self, 
-        id: str, 
+        self,
+        id: str,
         description: str = "Processing",
-        config: dict = None, 
-        signer: Signer = None, 
-        client_kwargs: dict = None, 
-        **kwargs
+        config: dict = None,
+        signer: Signer = None,
+        client_kwargs: dict = None,
+        **kwargs,
     ) -> None:
         """Initializes ADSWorkRequest object.
 
@@ -49,41 +48,43 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
         description: str
             Progress bar initial step description (Defaults to `Processing`).
         config : dict, optional
-            OCI API key config dictionary to initialize 
+            OCI API key config dictionary to initialize
             oci.data_science.DataScienceClient (Defaults to None).
         signer : oci.signer.Signer, optional
-            OCI authentication signer to initialize 
+            OCI authentication signer to initialize
             oci.data_science.DataScienceClient (Defaults to None).
         client_kwargs : dict, optional
-            Additional client keyword arguments to initialize 
+            Additional client keyword arguments to initialize
             oci.data_science.DataScienceClient (Defaults to None).
         kwargs:
-            Additional keyword arguments to initialize 
+            Additional keyword arguments to initialize
             oci.data_science.DataScienceClient.
         """
         self.id = id
         self._description = description
         self._percentage = 0
         self._status = None
+        self._error_message = ""
         super().__init__(config, signer, client_kwargs, **kwargs)
-        
 
     def _sync(self):
         """Fetches the latest work request information to ADSWorkRequest object."""
         work_request = self.client.get_work_request(self.id).data
-        work_request_logs = self.client.list_work_request_logs(
-            self.id
-        ).data
+        work_request_logs = self.client.list_work_request_logs(self.id).data
 
-        self._percentage= work_request.percent_complete
+        self._percentage = work_request.percent_complete
         self._status = work_request.status
-        self._description = work_request_logs[-1].message if work_request_logs else "Processing"
+        self._description = (
+            work_request_logs[-1].message if work_request_logs else "Processing"
+        )
+        if work_request.status == "FAILED":
+            self._error_message = self.client.list_work_request_errors(self.id).data
 
     def watch(
-        self, 
+        self,
         progress_callback: Callable,
-        max_wait_time: int=DEFAULT_WAIT_TIME,
-        poll_interval: int=DEFAULT_POLL_INTERVAL,
+        max_wait_time: int = DEFAULT_WAIT_TIME,
+        poll_interval: int = DEFAULT_POLL_INTERVAL,
     ):
         """Updates the progress bar with realtime message and percentage until the process is completed.
 
@@ -92,10 +93,10 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
         progress_callback: Callable
             Progress bar callback function.
             It must accept `(percent_change, description)` where `percent_change` is the
-            work request percent complete and `description` is the latest work request log message. 
+            work request percent complete and `description` is the latest work request log message.
         max_wait_time: int
             Maximum amount of time to wait in seconds (Defaults to 1200).
-            Negative implies infinite wait time. 
+            Negative implies infinite wait time.
         poll_interval: int
             Poll interval in seconds (Defaults to 10).
 
@@ -107,7 +108,6 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
 
         start_time = time.time()
         while self._percentage < 100:
-
             seconds_since = time.time() - start_time
             if max_wait_time > 0 and seconds_since >= max_wait_time:
                 logger.error(f"Exceeded max wait time of {max_wait_time} seconds.")
@@ -124,12 +124,14 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
             percent_change = self._percentage - previous_percent_complete
             previous_percent_complete = self._percentage
             progress_callback(
-                percent_change=percent_change,
-                description=self._description
+                percent_change=percent_change, description=self._description
             )
 
             if self._status in WORK_REQUEST_STOP_STATE:
-                if self._status != oci.work_requests.models.WorkRequest.STATUS_SUCCEEDED:
+                if (
+                    self._status
+                    != oci.work_requests.models.WorkRequest.STATUS_SUCCEEDED
+                ):
                     if self._description:
                         raise Exception(self._description)
                     else:
@@ -145,12 +147,12 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
 
     def wait_work_request(
         self,
-        progress_bar_description: str="Processing",
-        max_wait_time: int=DEFAULT_WAIT_TIME,
-        poll_interval: int=DEFAULT_POLL_INTERVAL
+        progress_bar_description: str = "Processing",
+        max_wait_time: int = DEFAULT_WAIT_TIME,
+        poll_interval: int = DEFAULT_POLL_INTERVAL,
     ):
         """Waits for the work request progress bar to be completed.
-        
+
         Parameters
         ----------
         progress_bar_description: str
@@ -160,7 +162,7 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
             Negative implies infinite wait time.
         poll_interval: int
             Poll interval in seconds (Defaults to 10).
-        
+
         Returns
         -------
         None
@@ -172,7 +174,7 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
             mininterval=0,
             file=sys.stdout,
             desc=progress_bar_description,
-            bar_format=DEFAULT_BAR_FORMAT
+            bar_format=DEFAULT_BAR_FORMAT,
         ) as pbar:
 
             def progress_callback(percent_change, description):
@@ -184,6 +186,5 @@ class DataScienceWorkRequest(OCIDataScienceMixin):
             self.watch(
                 progress_callback=progress_callback,
                 max_wait_time=max_wait_time,
-                poll_interval=poll_interval
+                poll_interval=poll_interval,
             )
-