oracle-ads 2.10.0__py3-none-any.whl → 2.11.0__py3-none-any.whl

ads/aqua/exception.py

@@ -0,0 +1,82 @@
+#!/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.exception
+~~~~~~~~~~~~~~
+
+This module contains the set of Aqua exceptions.
+"""
+
+
+class AquaError(Exception):
+    """AquaError
+
+    The base exception from which all exceptions raised by Aqua
+    will inherit.
+    """
+
+    def __init__(
+        self,
+        reason: str,
+        status: int,
+        service_payload: dict = None,
+    ):
+        """Initializes an AquaError.
+
+        Parameters
+        ----------
+        reason: str
+            User friendly error message.
+        status: int
+            Http status code that are going to raise.
+        service_payload: dict
+            Payload to contain more details related to the error.
+        """
+        self.service_payload = service_payload or {}
+        self.status = status
+        self.reason = reason
+
+
+class AquaValueError(AquaError, ValueError):
+    """Exception raised for unexpected values."""
+
+    def __init__(self, reason, status=403, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaFileNotFoundError(AquaError, FileNotFoundError):
+    """Exception raised for missing target file."""
+
+    def __init__(self, reason, status=404, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaRuntimeError(AquaError, RuntimeError):
+    """Exception raised for generic errors at runtime."""
+
+    def __init__(self, reason, status=400, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaMissingKeyError(AquaError):
+    """Exception raised when missing metadata in resource."""
+
+    def __init__(self, reason, status=400, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaFileExistsError(AquaError, FileExistsError):
+    """Exception raised when file already exists in resource."""
+
+    def __init__(self, reason, status=400, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaResourceAccessError(AquaError):
+    """Exception raised when file already exists in resource."""
+
+    def __init__(self, reason, status=404, service_payload=None):
+        super().__init__(reason, status, service_payload)

ads/aqua/extension/__init__.py

@@ -0,0 +1,40 @@
+#!/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 jupyter_server.utils import url_path_join
+
+from ads.aqua.extension.common_handler import __handlers__ as __common_handlers__
+from ads.aqua.extension.deployment_handler import (
+    __handlers__ as __deployment_handlers__,
+)
+from ads.aqua.extension.evaluation_handler import __handlers__ as __eval_handlers__
+from ads.aqua.extension.finetune_handler import __handlers__ as __finetune_handlers__
+from ads.aqua.extension.model_handler import __handlers__ as __model_handlers__
+from ads.aqua.extension.ui_handler import __handlers__ as __ui_handlers__
+
+__handlers__ = (
+    __finetune_handlers__
+    + __model_handlers__
+    + __common_handlers__
+    + __deployment_handlers__
+    + __ui_handlers__
+    + __eval_handlers__
+)
+
+
+def load_jupyter_server_extension(nb_server_app):
+    web_app = nb_server_app.web_app
+    host_pattern = ".*$"
+    route_pattern = url_path_join(web_app.settings["base_url"], "aqua")
+
+    web_app.add_handlers(
+        host_pattern,
+        [(url_path_join(route_pattern, url), handler) for url, handler in __handlers__],
+    )
+
+
+def _jupyter_server_extension_paths():
+    return [{"module": "ads.aqua.extension"}]

ads/aqua/extension/base_handler.py

@@ -0,0 +1,138 @@
+#!/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 json
+import traceback
+import uuid
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+from notebook.base.handlers import APIHandler
+from tornado.web import HTTPError, Application
+from tornado import httputil
+from ads.telemetry.client import TelemetryClient
+from ads.config import AQUA_TELEMETRY_BUCKET, AQUA_TELEMETRY_BUCKET_NS
+from ads.aqua import logger
+
+
+class AquaAPIhandler(APIHandler):
+    """Base handler for Aqua REST APIs."""
+
+    def __init__(
+        self,
+        application: "Application",
+        request: httputil.HTTPServerRequest,
+        **kwargs: Any,
+    ):
+        super().__init__(application, request, **kwargs)
+
+        try:
+            self.telemetry = TelemetryClient(
+                bucket=AQUA_TELEMETRY_BUCKET, namespace=AQUA_TELEMETRY_BUCKET_NS
+            )
+        except:
+            pass
+
+    @staticmethod
+    def serialize(obj: Any):
+        """Serialize the object.
+        If the object is a dataclass, convert it to dictionary. Otherwise, convert it to string.
+        """
+        if hasattr(obj, "to_dict") and callable(obj.to_dict):
+            return obj.to_dict()
+
+        if is_dataclass(obj):
+            return asdict(obj)
+
+        return str(obj)
+
+    def finish(self, payload=None):  # pylint: disable=W0221
+        """Ending the HTTP request by returning a payload and status code.
+
+        Tornado finish() only takes one argument.
+        Calling finish() with more than one arguments will cause error.
+        """
+        if payload is None:
+            return super().finish()
+        # If the payload is a list, put into a dictionary with key=data
+        if isinstance(payload, list):
+            payload = {"data": payload}
+        # Convert the payload to a JSON serializable object
+        payload = json.loads(json.dumps(payload, default=self.serialize))
+        return super().finish(payload)
+
+    def write_error(self, status_code, **kwargs):
+        """AquaAPIhandler errors are JSON, not human pages."""
+
+        self.set_header("Content-Type", "application/json")
+        reason = kwargs.get("reason")
+        self.set_status(status_code, reason=reason)
+        service_payload = kwargs.get("service_payload", {})
+        message = self.get_default_error_messages(service_payload, str(status_code))
+        reply = {
+            "status": status_code,
+            "message": message,
+            "service_payload": service_payload,
+            "reason": reason,
+        }
+        exc_info = kwargs.get("exc_info")
+        if exc_info:
+            logger.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
+                reply["request_id"] = str(uuid.uuid4())
+            else:
+                reply["request_id"] = str(uuid.uuid4())
+
+        logger.warning(reply["message"])
+
+        # telemetry may not be present if there is an error while initializing
+        if hasattr(self, "telemetry"):
+            self.telemetry.record_event_async(
+                category="aqua/error",
+                action=str(status_code),
+                value=reason,
+            )
+
+        self.finish(json.dumps(reply))
+
+    @staticmethod
+    def get_default_error_messages(service_payload: dict, status_code: str):
+        """Method that maps the error messages based on the operation performed or the status codes encountered."""
+
+        messages = {
+            "400": "Something went wrong with your request.",
+            "403": "We're having trouble processing your request with the information provided.",
+            "404": "Authorization Failed: The resource you're looking for isn't accessible.",
+            "408": "Server is taking too long to response, please try again.",
+            "500": "An error occurred while creating the resource.",
+            "create": "Authorization Failed: Could not create resource.",
+            "get": "Authorization Failed: The resource you're looking for isn't accessible.",
+        }
+
+        if service_payload and "operation_name" in service_payload:
+            operation_name = service_payload["operation_name"]
+            if operation_name:
+                if operation_name.startswith("create"):
+                    return messages["create"]
+                elif operation_name.startswith("list") or operation_name.startswith(
+                    "get"
+                ):
+                    return messages["get"] + f" Operation Name: {operation_name}."
+
+        if status_code in messages:
+            return messages[status_code]
+        else:
+            return "Unknown HTTP Error."
+
+
+# todo: remove after error handler is implemented
+class Errors(str):
+    INVALID_INPUT_DATA_FORMAT = "Invalid format of input data."
+    NO_INPUT_DATA = "No input data provided."
+    MISSING_REQUIRED_PARAMETER = "Missing required parameter: '{}'"

ads/aqua/extension/common_handler.py

@@ -0,0 +1,21 @@
+#!/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 importlib import metadata
+
+from ads.aqua.extension.base_handler import AquaAPIhandler
+
+
+class ADSVersionHandler(AquaAPIhandler):
+    """The handler to get the current version of the ADS."""
+
+    def get(self):
+        self.finish({"data": metadata.version("oracle_ads")})
+
+
+__handlers__ = [
+    ("ads_version", ADSVersionHandler),
+]

ads/aqua/extension/deployment_handler.py

@@ -0,0 +1,202 @@
+#!/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 urllib.parse import urlparse
+
+from tornado.web import HTTPError
+
+from ads.aqua.deployment import AquaDeploymentApp, MDInferenceResponse, ModelParams
+from ads.aqua.extension.base_handler import AquaAPIhandler, Errors
+from ads.config import COMPARTMENT_OCID, PROJECT_OCID
+from ads.aqua.decorator import handle_exceptions
+
+
+class AquaDeploymentHandler(AquaAPIhandler):
+    """
+    Handler for Aqua Deployment REST APIs.
+
+    Methods
+    -------
+    get(self, id="")
+        Retrieves a list of AQUA deployments or model info or logs by ID.
+    post(self, *args, **kwargs)
+        Creates a new AQUA deployment.
+    read(self, id: str)
+        Reads the AQUA deployment information.
+    list(self)
+        Lists all the AQUA deployments.
+    get_deployment_config(self, model_id)
+        Gets the deployment config for Aqua model.
+
+    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/deployments/config"):
+            if not id:
+                raise HTTPError(
+                    400, f"The request {self.request.path} requires model id."
+                )
+            return self.get_deployment_config(id)
+        elif paths.startswith("aqua/deployments"):
+            if not id:
+                return self.list()
+            return self.read(id)
+        else:
+            raise HTTPError(400, f"The request {self.request.path} is invalid.")
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):
+        """
+        Handles post request for the deployment APIs
+        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)
+
+        # required input parameters
+        display_name = input_data.get("display_name")
+        if not display_name:
+            raise HTTPError(
+                400, Errors.MISSING_REQUIRED_PARAMETER.format("display_name")
+            )
+        instance_shape = input_data.get("instance_shape")
+        if not instance_shape:
+            raise HTTPError(
+                400, Errors.MISSING_REQUIRED_PARAMETER.format("instance_shape")
+            )
+        model_id = input_data.get("model_id")
+        if not model_id:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("model_id"))
+
+        compartment_id = input_data.get("compartment_id", COMPARTMENT_OCID)
+        project_id = input_data.get("project_id", PROJECT_OCID)
+        log_group_id = input_data.get("log_group_id")
+        access_log_id = input_data.get("access_log_id")
+        predict_log_id = input_data.get("predict_log_id")
+        description = input_data.get("description")
+        instance_count = input_data.get("instance_count")
+        bandwidth_mbps = input_data.get("bandwidth_mbps")
+
+        self.finish(
+            AquaDeploymentApp().create(
+                compartment_id=compartment_id,
+                project_id=project_id,
+                model_id=model_id,
+                display_name=display_name,
+                description=description,
+                instance_count=instance_count,
+                instance_shape=instance_shape,
+                log_group_id=log_group_id,
+                access_log_id=access_log_id,
+                predict_log_id=predict_log_id,
+                bandwidth_mbps=bandwidth_mbps,
+            )
+        )
+
+    @handle_exceptions
+    def read(self, id):
+        """Read the information of an Aqua model deployment."""
+        return self.finish(AquaDeploymentApp().get(model_deployment_id=id))
+
+    @handle_exceptions
+    def list(self):
+        """List Aqua models."""
+        # If default is not specified,
+        # jupyterlab will raise 400 error when argument is not provided by the HTTP request.
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        # project_id is optional.
+        project_id = self.get_argument("project_id", default=None)
+        return self.finish(
+            AquaDeploymentApp().list(
+                compartment_id=compartment_id, project_id=project_id
+            )
+        )
+
+    @handle_exceptions
+    def get_deployment_config(self, model_id):
+        """Gets the deployment config for Aqua model."""
+        return self.finish(AquaDeploymentApp().get_deployment_config(model_id=model_id))
+
+
+class AquaDeploymentInferenceHandler(AquaAPIhandler):
+    @staticmethod
+    def validate_predict_url(endpoint):
+        try:
+            url = urlparse(endpoint)
+            if url.scheme != "https":
+                return False
+            if not url.netloc:
+                return False
+            if not url.path.endswith("/predict"):
+                return False
+            return True
+        except Exception:
+            return False
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):
+        """
+        Handles inference request for the Active Model Deployments
+        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)
+
+        endpoint = input_data.get("endpoint")
+        if not endpoint:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("endpoint"))
+
+        if not self.validate_predict_url(endpoint):
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT.format("endpoint"))
+
+        prompt = input_data.get("prompt")
+        if not prompt:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("prompt"))
+
+        model_params = (
+            input_data.get("model_params") if input_data.get("model_params") else {}
+        )
+        try:
+            model_params_obj = ModelParams(**model_params)
+        except:
+            raise HTTPError(
+                400, Errors.INVALID_INPUT_DATA_FORMAT.format("model_params")
+            )
+
+        return self.finish(
+            MDInferenceResponse(prompt, model_params_obj).get_model_deployment_response(
+                endpoint
+            )
+        )
+
+
+__handlers__ = [
+    ("deployments/?([^/]*)", AquaDeploymentHandler),
+    ("deployments/config/?([^/]*)", AquaDeploymentHandler),
+    ("inference", AquaDeploymentInferenceHandler),
+]

ads/aqua/extension/evaluation_handler.py

@@ -0,0 +1,135 @@
+#!/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 urllib.parse import urlparse
+
+from requests import HTTPError
+
+from ads.aqua.decorator import handle_exceptions
+from ads.aqua.evaluation import AquaEvaluationApp, CreateAquaEvaluationDetails
+from ads.aqua.exception import AquaError
+from ads.aqua.extension.base_handler import AquaAPIhandler, Errors
+from ads.aqua.extension.utils import validate_function_parameters
+from ads.config import COMPARTMENT_OCID
+
+
+class AquaEvaluationHandler(AquaAPIhandler):
+    """Handler for Aqua Model Evaluation REST APIs."""
+
+    @handle_exceptions
+    def get(self, eval_id=""):
+        """Handle GET request."""
+        url_parse = urlparse(self.request.path)
+        paths = url_parse.path.strip("/")
+        if paths.startswith("aqua/evaluation/metrics"):
+            return self.get_default_metrics()
+        if not eval_id:
+            return self.list()
+        return self.read(eval_id)
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):
+        """Handles post request for the evaluation APIs
+
+        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=CreateAquaEvaluationDetails, input_data=input_data
+        )
+
+        self.finish(
+            # TODO: decide what other kwargs will be needed for create aqua evaluation.
+            AquaEvaluationApp().create(
+                create_aqua_evaluation_details=(
+                    CreateAquaEvaluationDetails(**input_data)
+                )
+            )
+        )
+
+    @handle_exceptions
+    def put(self, eval_id):
+        """Handles PUT request for the evaluation APIs"""
+        eval_id = eval_id.split("/")[0]
+        return self.finish(AquaEvaluationApp().cancel(eval_id))
+
+    @handle_exceptions
+    def delete(self, eval_id):
+        return self.finish(AquaEvaluationApp().delete(eval_id))
+
+    def read(self, eval_id):
+        """Read the information of an Aqua model."""
+        return self.finish(AquaEvaluationApp().get(eval_id))
+
+    def list(self):
+        """List Aqua models."""
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+        # project_id is no needed.
+        project_id = self.get_argument("project_id", default=None)
+        return self.finish(AquaEvaluationApp().list(compartment_id, project_id))
+
+    def get_default_metrics(self):
+        """Lists supported metrics for evaluation."""
+        return self.finish(AquaEvaluationApp().get_supported_metrics())
+
+
+class AquaEvaluationStatusHandler(AquaAPIhandler):
+    """Handler for Aqua Evaluation status REST APIs."""
+
+    @handle_exceptions
+    def get(self, eval_id):
+        """Handle GET request."""
+        eval_id = eval_id.split("/")[0]
+        return self.finish(AquaEvaluationApp().get_status(eval_id))
+
+
+class AquaEvaluationReportHandler(AquaAPIhandler):
+    """Handler for Aqua Evaluation report REST APIs."""
+
+    @handle_exceptions
+    def get(self, eval_id):
+        """Handle GET request."""
+        eval_id = eval_id.split("/")[0]
+        return self.finish(AquaEvaluationApp().download_report(eval_id))
+
+
+class AquaEvaluationMetricsHandler(AquaAPIhandler):
+    """Handler for Aqua Evaluation metrics REST APIs."""
+
+    @handle_exceptions
+    def get(self, eval_id):
+        """Handle GET request."""
+        eval_id = eval_id.split("/")[0]
+        return self.finish(AquaEvaluationApp().load_metrics(eval_id))
+
+
+class AquaEvaluationConfigHandler(AquaAPIhandler):
+    """Handler for Aqua Evaluation Config REST APIs."""
+
+    @handle_exceptions
+    def get(self, model_id):
+        """Handle GET request."""
+
+        return self.finish(AquaEvaluationApp().load_evaluation_config(model_id))
+
+
+__handlers__ = [
+    ("evaluation/config/?([^/]*)", AquaEvaluationConfigHandler),
+    ("evaluation/?([^/]*)", AquaEvaluationHandler),
+    ("evaluation/?([^/]*/report)", AquaEvaluationReportHandler),
+    ("evaluation/?([^/]*/metrics)", AquaEvaluationMetricsHandler),
+    ("evaluation/?([^/]*/status)", AquaEvaluationStatusHandler),
+    ("evaluation/?([^/]*/cancel)", AquaEvaluationHandler),
+]

ads/aqua/extension/finetune_handler.py

@@ -0,0 +1,66 @@
+#!/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 urllib.parse import urlparse
+
+from tornado.web import HTTPError
+
+from ads.aqua.decorator import handle_exceptions
+from ads.aqua.extension.base_handler import AquaAPIhandler, Errors
+from ads.aqua.extension.utils import validate_function_parameters
+from ads.aqua.finetune import AquaFineTuningApp, CreateFineTuningDetails
+
+
+class AquaFineTuneHandler(AquaAPIhandler):
+    """Handler for Aqua fine-tuning job REST APIs."""
+
+    @handle_exceptions
+    def get(self, id=""):
+        """Handle GET request."""
+        url_parse = urlparse(self.request.path)
+        paths = url_parse.path.strip("/")
+        if paths.startswith("aqua/finetuning/config"):
+            if not id:
+                raise HTTPError(
+                    400, f"The request {self.request.path} requires model id."
+                )
+            return self.get_finetuning_config(id)
+        else:
+            raise HTTPError(400, f"The request {self.request.path} is invalid.")
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):
+        """Handles post request for the fine-tuning API
+
+        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=CreateFineTuningDetails, input_data=input_data
+        )
+
+        self.finish(AquaFineTuningApp().create(CreateFineTuningDetails(**input_data)))
+
+    @handle_exceptions
+    def get_finetuning_config(self, model_id):
+        """Gets the finetuning config for Aqua model."""
+        return self.finish(AquaFineTuningApp().get_finetuning_config(model_id=model_id))
+
+
+__handlers__ = [
+    ("finetuning/?([^/]*)", AquaFineTuneHandler),
+    ("finetuning/config/?([^/]*)", AquaFineTuneHandler),
+]