oracle-ads 2.13.9rc0__py3-none-any.whl → 2.13.10rc0__py3-none-any.whl

ads/aqua/extension/ui_handler.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python
+# 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 urllib.parse import urlparse
+
+from tornado.web import HTTPError
+
+from ads.aqua.common.decorator import handle_exceptions
+from ads.aqua.common.enums import Tags
+from ads.aqua.constants import PRIVATE_ENDPOINT_TYPE
+from ads.aqua.extension.base_handler import AquaAPIhandler
+from ads.aqua.extension.errors import Errors
+from ads.aqua.extension.utils import validate_function_parameters
+from ads.aqua.model.entities import ImportModelDetails
+from ads.aqua.ui import AquaUIApp
+from ads.config import COMPARTMENT_OCID, IS_BYOR_ENABLED
+
+
+@dataclass
+class CLIDetails:
+    """Interface to capture payload and command details for generating ads cli command"""
+
+    command: str
+    subcommand: str
+    payload: dict
+
+
+class AquaUIHandler(AquaAPIhandler):
+    """
+    Handler for Aqua UI REST APIs.
+
+    Methods
+    -------
+    get(self, id="")
+        Routes the request to fetch log groups, log ids details or compartments
+    list_log_groups(self, id: str)
+        Reads the AQUA deployment information.
+    list_logs(self, log_group_id: str, **kwargs)
+        Lists the specified log group's log objects.
+    list_compartments(self, **kwargs)
+        Lists the compartments in a compartment specified by ODSC_MODEL_COMPARTMENT_OCID env variable.
+
+    Raises
+    ------
+    HTTPError: For various failure scenarios such as invalid input format, missing data, etc.
+    """
+
+    @handle_exceptions
+    def get(self, id=""):
+        """Handle GET request."""
+        url_parse = urlparse(self.request.path)
+        paths = url_parse.path.strip("/")
+        if paths.startswith("aqua/logging"):
+            if not id:
+                return self.list_log_groups()
+            return self.list_logs(id)
+        elif paths.startswith("aqua/compartments/default"):
+            return self.get_default_compartment()
+        elif paths.startswith("aqua/compartments"):
+            return self.list_compartments()
+        elif paths.startswith("aqua/experiment"):
+            return self.list_experiments()
+        elif paths.startswith("aqua/versionsets"):
+            return self.list_model_version_sets()
+        elif paths.startswith("aqua/buckets"):
+            return self.list_buckets()
+        elif paths.startswith("aqua/job/shapes"):
+            return self.list_job_shapes()
+        elif paths.startswith("aqua/modeldeployment/shapes"):
+            return self.list_model_deployment_shapes()
+        elif paths.startswith("aqua/vcn"):
+            return self.list_vcn()
+        elif paths.startswith("aqua/subnets"):
+            return self.list_subnets()
+        elif paths.startswith("aqua/privateendpoints"):
+            return self.list_private_endpoints()
+        elif paths.startswith("aqua/shapes/limit"):
+            return self.get_shape_availability()
+        elif paths.startswith("aqua/bucket/versioning"):
+            return self.is_bucket_versioned()
+        elif paths.startswith("aqua/containers"):
+            return self.list_containers()
+        elif paths.startswith("aqua/capacityreservations/enabled"):
+            return self.is_capacity_reservations_enabled()
+        elif paths.startswith("aqua/capacityreservations"):
+            return self.list_capacity_reservations()
+        else:
+            raise HTTPError(400, f"The request {self.request.path} is invalid.")
+
+    @handle_exceptions
+    def delete(self, id=""):
+        """Handles DELETE request for clearing cache"""
+        # todo: added for dev work, to be deleted if there's no feature to refresh cache in Aqua
+        url_parse = urlparse(self.request.path)
+        paths = url_parse.path.strip("/")
+        if paths.startswith("aqua/compartments/cache"):
+            return self.finish(AquaUIApp().clear_compartments_list_cache())
+        else:
+            raise HTTPError(400, f"The request {self.request.path} is invalid.")
+
+    def list_log_groups(self, **kwargs):
+        """Lists all log groups for the specified compartment or tenancy."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        return self.finish(
+            AquaUIApp().list_log_groups(compartment_id=compartment_id, **kwargs)
+        )
+
+    def is_capacity_reservations_enabled(self):
+        """Checks if the tenant is whitelisted for BYOR (Bring your own reservation) feature."""
+        return self.finish({"status": str(IS_BYOR_ENABLED).strip().lower() == "true"})
+
+    def list_capacity_reservations(self, **kwargs):
+        """Lists users compute reservations in a specified compartment."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        return self.finish(
+            AquaUIApp().list_capacity_reservations(
+                compartment_id=compartment_id, **kwargs
+            )
+        )
+
+    def list_logs(self, log_group_id: str, **kwargs):
+        """Lists the specified log group's log objects."""
+        return self.finish(AquaUIApp().list_logs(log_group_id=log_group_id, **kwargs))
+
+    def list_compartments(self):
+        """Lists the compartments in a compartment specified by ODSC_MODEL_COMPARTMENT_OCID env variable."""
+        return self.finish(AquaUIApp().list_compartments())
+
+    def list_containers(self):
+        """Lists the AQUA containers."""
+        return self.finish(AquaUIApp().list_containers())
+
+    def get_default_compartment(self):
+        """Returns user compartment ocid."""
+        return self.finish(AquaUIApp().get_default_compartment())
+
+    def list_model_version_sets(self, **kwargs):
+        """Lists all model version sets for the specified compartment or tenancy."""
+
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        return self.finish(
+            AquaUIApp().list_model_version_sets(
+                compartment_id=compartment_id,
+                target_tag=Tags.AQUA_FINE_TUNING,
+                **kwargs,
+            )
+        )
+
+    def list_experiments(self, **kwargs):
+        """Lists all experiments for the specified compartment or tenancy."""
+
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        return self.finish(
+            AquaUIApp().list_model_version_sets(
+                compartment_id=compartment_id,
+                target_tag=Tags.AQUA_EVALUATION,
+                **kwargs,
+            )
+        )
+
+    def list_buckets(self, **kwargs):
+        """Lists all model version sets for the specified compartment or tenancy."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        versioned = self.get_argument("versioned", default=None)
+        versioned = True if versioned and versioned.lower() == "true" else False
+
+        return self.finish(
+            AquaUIApp().list_buckets(
+                compartment_id=compartment_id, versioned=versioned, **kwargs
+            )
+        )
+
+    def list_job_shapes(self, **kwargs):
+        """Lists job shapes available in the specified compartment."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        return self.finish(
+            AquaUIApp().list_job_shapes(compartment_id=compartment_id, **kwargs)
+        )
+
+    def list_model_deployment_shapes(self, **kwargs):
+        """Lists model deployment shapes available in the specified compartment."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        return self.finish(
+            AquaUIApp().list_model_deployment_shapes(
+                compartment_id=compartment_id, **kwargs
+            )
+        )
+
+    def list_vcn(self, **kwargs):
+        """Lists the virtual cloud networks (VCNs) in the specified compartment."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        return self.finish(
+            AquaUIApp().list_vcn(compartment_id=compartment_id, **kwargs)
+        )
+
+    def list_subnets(self, **kwargs):
+        """Lists the subnets in the specified VCN and the specified compartment."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        vcn_id = self.get_argument("vcn_id")
+        return self.finish(
+            AquaUIApp().list_subnets(
+                compartment_id=compartment_id, vcn_id=vcn_id, **kwargs
+            )
+        )
+
+    def list_private_endpoints(self, **kwargs):
+        """Lists the private endpoints in the specified compartment."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        resource_type = self.get_argument(
+            "resource_type", default=PRIVATE_ENDPOINT_TYPE
+        )
+        return self.finish(
+            AquaUIApp().list_private_endpoints(
+                compartment_id=compartment_id, resource_type=resource_type, **kwargs
+            )
+        )
+
+    def get_shape_availability(self, **kwargs):
+        """For a given compartmentId, resource limit name, and scope, returns the number of available resources associated
+        with the given limit."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        instance_shape = self.get_argument("instance_shape")
+        limit_name = self.get_argument("limit_name")
+
+        return self.finish(
+            AquaUIApp().get_shape_availability(
+                compartment_id=compartment_id,
+                instance_shape=instance_shape,
+                limit_name=limit_name,
+                **kwargs,
+            )
+        )
+
+    def is_bucket_versioned(self):
+        """For a given compartmentId, resource limit name, and scope, returns the number of available resources associated
+        with the given limit."""
+        bucket_uri = self.get_argument("bucket_uri")
+        return self.finish(AquaUIApp().is_bucket_versioned(bucket_uri=bucket_uri))
+
+
+class AquaCLIHandler(AquaAPIhandler):
+    """Handler for Aqua model import
+    command_interface_map is a map of command+subcommand to corresponding API dataclas.
+    Eg. In command `ads aqua model register ....`, command is `model` and subcommand is `register`
+    The key in the map will be f"{command}_{sub_command}" and value will be a DataClass
+    """
+
+    command_interface_map = {"model_register": ImportModelDetails}
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):
+        """Handles cli command construction
+
+        Raises
+        ------
+        HTTPError
+            Raises HTTPError if inputs are missing or are invalid.
+        """
+        try:
+            input_data = self.get_json_body()
+        except Exception:
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT)
+
+        if not input_data:
+            raise HTTPError(400, Errors.NO_INPUT_DATA)
+
+        validate_function_parameters(data_class=CLIDetails, input_data=input_data)
+        command_details = CLIDetails(**input_data)
+
+        interface = AquaCLIHandler.command_interface_map[
+            f"{command_details.command}_{command_details.subcommand}"
+        ]
+
+        validate_function_parameters(
+            data_class=interface, input_data=command_details.payload
+        )
+        payload = interface(**command_details.payload)
+        self.finish({"command": payload.build_cli()})
+
+
+__handlers__ = [
+    ("logging/?([^/]*)", AquaUIHandler),
+    ("compartments/?([^/]*)", AquaUIHandler),
+    # TODO: change url to evaluation/experiments/?([^/]*)
+    ("experiment/?([^/]*)", AquaUIHandler),
+    ("modeldeployment/?([^/]*)", AquaUIHandler),
+    ("versionsets/?([^/]*)", AquaUIHandler),
+    ("buckets/?([^/]*)", AquaUIHandler),
+    ("job/shapes/?([^/]*)", AquaUIHandler),
+    ("vcn/?([^/]*)", AquaUIHandler),
+    ("subnets/?([^/]*)", AquaUIHandler),
+    ("privateendpoints/?([^/]*)", AquaUIHandler),
+    ("shapes/limit/?([^/]*)", AquaUIHandler),
+    ("bucket/versioning/?([^/]*)", AquaUIHandler),
+    ("containers/?([^/]*)", AquaUIHandler),
+    ("cli/?([^/]*)", AquaCLIHandler),
+    ("capacityreservations/?([^/]*)", AquaUIHandler),
+]

ads/aqua/extension/ui_websocket_handler.py

@@ -0,0 +1,130 @@
+#!/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/
+import concurrent.futures
+from asyncio.futures import Future
+from concurrent.futures import ThreadPoolExecutor
+from typing import Dict, List, Type, Union
+
+import tornado
+from tornado import httputil
+from tornado.ioloop import IOLoop
+from tornado.websocket import WebSocketHandler
+
+from ads.aqua import logger
+from ads.aqua.extension.aqua_ws_msg_handler import AquaWSMsgHandler
+from ads.aqua.extension.common_ws_msg_handler import AquaCommonWsMsgHandler
+from ads.aqua.extension.deployment_ws_msg_handler import AquaDeploymentWSMsgHandler
+from ads.aqua.extension.evaluation_ws_msg_handler import AquaEvaluationWSMsgHandler
+from ads.aqua.extension.models.ws_models import (
+    AquaWsError,
+    BaseRequest,
+    BaseResponse,
+    ErrorResponse,
+    RequestResponseType,
+)
+from ads.aqua.extension.models_ws_msg_handler import AquaModelWSMsgHandler
+
+MAX_WORKERS = 20
+
+
+def get_aqua_internal_error_response(message_id: str) -> ErrorResponse:
+    error = AquaWsError(
+        status="500",
+        message="Internal Server Error",
+        service_payload={},
+        reason="",
+    )
+    return ErrorResponse(
+        message_id=message_id,
+        kind=RequestResponseType.Error,
+        data=error,
+    )
+
+
+class AquaUIWebSocketHandler(WebSocketHandler):
+    """Handler for Aqua Websocket."""
+
+    _handlers_: List[Type[AquaWSMsgHandler]] = [AquaEvaluationWSMsgHandler,
+                                                AquaDeploymentWSMsgHandler,
+                                                AquaModelWSMsgHandler,
+                                                AquaCommonWsMsgHandler]
+
+    thread_pool: ThreadPoolExecutor
+
+    future_message_map: Dict[Future, BaseRequest]
+    message_type_handler_map: Dict[RequestResponseType, Type[AquaWSMsgHandler]]
+
+    def __init__(
+        self,
+        application: tornado.web.Application,
+        request: httputil.HTTPServerRequest,
+        **kwargs,
+    ):
+        # Create a mapping of message type to handler and check for duplicates
+        self.future_message_map = {}
+        self.message_type_handler_map = {}
+        for handler in self._handlers_:
+            for message_type in handler.get_message_types():
+                if message_type in self.message_type_handler_map:
+                    raise ValueError(
+                        f"Duplicate message type {message_type} in AQUA websocket handlers."
+                    )
+                else:
+                    self.message_type_handler_map[message_type] = handler
+
+        super().__init__(application, request, **kwargs)
+
+    def open(self, *args, **kwargs):
+        self.thread_pool = ThreadPoolExecutor(max_workers=MAX_WORKERS)
+        logger.info("AQUA WebSocket opened")
+
+    def on_message(self, message: Union[str, bytes]):
+        try:
+            request = BaseRequest.from_json(message, ignore_unknown=True)
+        except Exception as e:
+            logger.error(
+                f"Unable to parse WebSocket message {message}\nWith exception: {str(e)}"
+            )
+            raise e
+        # Find the handler for the message type.
+        # Each handler is responsible for some specific message types
+        handler = self.message_type_handler_map.get(request.kind, None)
+        if handler is None:
+            self.write_message(
+                get_aqua_internal_error_response(request.message_id).to_json()
+            )
+            raise ValueError(f"No handler found for message type {request.kind}")
+        else:
+            message_handler = handler(message)
+            future: Future = self.thread_pool.submit(message_handler.process)
+            self.future_message_map[future] = request
+            future.add_done_callback(self.on_message_processed)
+
+    def on_message_processed(self, future: concurrent.futures.Future):
+        """Callback function to handle the response from the various AquaWSMsgHandlers."""
+        try:
+            response: BaseResponse = future.result()
+
+        # Any exception coming here is an unhandled exception in the handler. We should log it and return an internal server error.
+        # In non WebSocket scenarios this would be handled by the tornado webserver
+        except Exception as e:
+            logger.error(
+                f"Unable to handle WebSocket message {self.future_message_map[future]}\nWith exception: {str(e)}"
+            )
+            response: BaseResponse = get_aqua_internal_error_response(
+                self.future_message_map[future].message_id
+            )
+            raise e
+        finally:
+            self.future_message_map.pop(future)
+            # Send the response back to the client on the event thread
+            IOLoop.current().run_sync(lambda: self.write_message(response.to_json()))
+
+    def on_close(self) -> None:
+        self.thread_pool.shutdown()
+        logger.info("AQUA WebSocket closed")
+
+
+__handlers__ = [("ws?([^/]*)", AquaUIWebSocketHandler)]

ads/aqua/extension/utils.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python
+# 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 re
+import traceback
+import uuid
+from dataclasses import fields
+from http.client import responses
+from typing import Dict, Optional
+
+from tornado.web import HTTPError
+
+from ads.aqua import logger
+from ads.aqua.constants import (
+    AQUA_TROUBLESHOOTING_LINK,
+    OCI_OPERATION_FAILURES,
+    STATUS_CODE_MESSAGES,
+)
+from ads.aqua.extension.errors import Errors, ReplyDetails
+
+
+def validate_function_parameters(data_class, input_data: Dict):
+    """Validates if the required parameters are provided in input data."""
+    required_parameters = [
+        field.name for field in fields(data_class) if field.type != Optional[field.type]
+    ]
+
+    for required_parameter in required_parameters:
+        if not input_data.get(required_parameter):
+            raise HTTPError(
+                400, Errors.MISSING_REQUIRED_PARAMETER.format(required_parameter)
+            )
+
+
+def get_default_error_messages(
+    service_payload: dict,
+    status_code: str,
+    default_msg: str = "Unknown HTTP Error.",
+) -> str:
+    """Method that maps the error messages based on the operation performed or the status codes encountered."""
+
+    if service_payload and "operation_name" in service_payload:
+        operation_name = service_payload.get("operation_name")
+
+        if operation_name and status_code in STATUS_CODE_MESSAGES:
+            return f"{STATUS_CODE_MESSAGES[status_code]}\n{service_payload.get('message')}\nOperation Name: {operation_name}."
+
+    return STATUS_CODE_MESSAGES.get(status_code, default_msg)
+
+
+def get_documentation_link(key: str) -> str:
+    """Generates appropriate GitHub link to AQUA Troubleshooting Documentation per the user's error."""
+    github_header = re.sub(r"_", "-", key)
+    return f"{AQUA_TROUBLESHOOTING_LINK}#{github_header}"
+
+
+def get_troubleshooting_tips(service_payload: dict, status_code: str) -> str:
+    """Maps authorization errors to potential solutions on Troubleshooting Page per Aqua Documentation on oci-data-science-ai-samples"""
+
+    tip = f"For general tips on troubleshooting: {AQUA_TROUBLESHOOTING_LINK}"
+
+    if status_code in (404, 400):
+        failed_operation = service_payload.get("operation_name")
+
+        if failed_operation in OCI_OPERATION_FAILURES:
+            link = get_documentation_link(failed_operation)
+            tip = OCI_OPERATION_FAILURES[failed_operation] + link
+
+    return tip
+
+
+def construct_error(status_code: int, **kwargs) -> ReplyDetails:
+    """
+    Formats an error response based on the provided status code and optional details.
+
+    Args:
+        status_code (int): The HTTP status code of the error.
+        **kwargs: Additional optional parameters:
+            - reason (str, optional): A brief reason for the error.
+            - service_payload (dict, optional): Contextual error data from OCI SDK methods
+            - message (str, optional): A custom error message, from error raised from failed AQUA methods calling OCI SDK methods
+            - exc_info (tuple, optional): Exception information (e.g., from `sys.exc_info()`), used for logging.
+
+    Returns:
+        ReplyDetails: A Pydantic object containing details about the formatted error response.
+        kwargs:
+                - "status" (int): The HTTP status code.
+                - "troubleshooting_tips" (str): a GitHub link to AQUA troubleshooting docs, may be linked to a specific header.
+                - "message" (str): error message.
+                - "service_payload" (Dict[str, Any], optional) : Additional context from OCI Python SDK call.
+                - "reason" (str): The reason for the error.
+                - "request_id" (str): A unique identifier for tracking the error.
+
+    Logs:
+        - Logs the error details with a unique request ID.
+        - If `exc_info` is provided and contains an `HTTPError`, updates the response message and reason accordingly.
+
+    """
+    reason = kwargs.get("reason", "Unknown Error")
+    service_payload = kwargs.get("service_payload", {})
+    default_msg = responses.get(status_code, "Unknown HTTP Error")
+    message = get_default_error_messages(
+        service_payload, str(status_code), kwargs.get("message", default_msg)
+    )
+
+    tips = get_troubleshooting_tips(service_payload, status_code)
+
+    reply = ReplyDetails(
+        status=status_code,
+        troubleshooting_tips=tips,
+        message=message,
+        service_payload=service_payload,
+        reason=reason,
+        request_id=str(uuid.uuid4()),
+    )
+
+    exc_info = kwargs.get("exc_info")
+    if exc_info:
+        logger.error(
+            f"Error Request ID: {reply.request_id}\n"
+            f"Error: {''.join(traceback.format_exception(*exc_info))}"
+        )
+        e = exc_info[1]
+        if isinstance(e, HTTPError):
+            reply.message = e.log_message or message
+            reply.reason = e.reason if e.reason else reply.reason
+
+    logger.error(
+        f"Error Request ID: {reply.request_id}\n"
+        f"Error: {reply.message} {reply.reason}"
+    )
+    return reply

ads/aqua/finetuning/__init__.py

@@ -0,0 +1,7 @@
+#!/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.finetuning.finetuning import AquaFineTuningApp
+
+__all__ = ["AquaFineTuningApp"]

ads/aqua/finetuning/constants.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+# 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/
+
+from ads.common.extended_enum import ExtendedEnum
+
+
+class FineTuneCustomMetadata(ExtendedEnum):
+    FINE_TUNE_SOURCE = "fine_tune_source"
+    FINE_TUNE_SOURCE_NAME = "fine_tune_source_name"
+    FINE_TUNE_OUTPUT_PATH = "fine_tune_output_path"
+    FINE_TUNE_JOB_ID = "fine_tune_job_id"
+    FINE_TUNE_JOB_RUN_ID = "fine_tune_job_run_id"
+    SERVICE_MODEL_ARTIFACT_LOCATION = "artifact_location"
+    SERVICE_MODEL_DEPLOYMENT_CONTAINER = "deployment-container"
+    SERVICE_MODEL_FINE_TUNE_CONTAINER = "finetune-container"
+
+
+class FineTuningRestrictedParams(ExtendedEnum):
+    OPTIMIZER = "optimizer"
+
+
+ENV_AQUA_FINE_TUNING_CONTAINER = "AQUA_FINE_TUNING_CONTAINER"