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

ads/aqua/extension/__init__.py

@@ -0,0 +1,42 @@
+#!/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__
+from ads.aqua.extension.ui_websocket_handler import __handlers__ as __ws_handlers__
+
+__handlers__ = (
+    __finetune_handlers__
+    + __model_handlers__
+    + __common_handlers__
+    + __deployment_handlers__
+    + __ui_handlers__
+    + __eval_handlers__
+    + __ws_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/aqua_ws_msg_handler.py

@@ -0,0 +1,76 @@
+#!/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 abc import abstractmethod
+from typing import List
+
+from ads.aqua.common.decorator import handle_exceptions
+from ads.aqua.extension.models.ws_models import (
+    AquaWsError,
+    BaseRequest,
+    BaseResponse,
+    ErrorResponse,
+    RequestResponseType,
+)
+from ads.aqua.extension.utils import construct_error
+from ads.config import AQUA_TELEMETRY_BUCKET, AQUA_TELEMETRY_BUCKET_NS
+from ads.telemetry.client import TelemetryClient
+
+
+class AquaWSMsgHandler:
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+        try:
+            self.telemetry = TelemetryClient(
+                bucket=AQUA_TELEMETRY_BUCKET, namespace=AQUA_TELEMETRY_BUCKET_NS
+            )
+        except Exception:
+            pass
+
+    @staticmethod
+    @abstractmethod
+    def get_message_types() -> List[RequestResponseType]:
+        """This method should be implemented by the child class.
+        This method should return a list of RequestResponseType that the child class can handle
+        """
+        pass
+
+    @abstractmethod
+    @handle_exceptions
+    def process(self) -> BaseResponse:
+        """This method should be implemented by the child class.
+        This method will contain the core logic to be executed for handling the message
+        """
+        pass
+
+    def write_error(self, status_code, **kwargs):
+        """AquaWSMSGhandler errors are JSON, not human pages."""
+
+        service_payload = kwargs.get("service_payload", {})
+        reply_details = construct_error(status_code, **kwargs)
+
+        # telemetry may not be present if there is an error while initializing
+        if hasattr(self, "telemetry"):
+            aqua_api_details = kwargs.get("aqua_api_details", {})
+            self.telemetry.record_event_async(
+                category="aqua/error",
+                action=str(status_code),
+                value=reply_details.reason,
+                **aqua_api_details,
+            )
+        response = AquaWsError(
+            status=status_code,
+            message=reply_details.message,
+            service_payload=service_payload,
+            reason=reply_details.reason,
+        )
+        base_message = BaseRequest.from_json(self.message, ignore_unknown=True)
+        return ErrorResponse(
+            message_id=base_message.message_id,
+            kind=RequestResponseType.Error,
+            data=response,
+        )

ads/aqua/extension/base_handler.py

@@ -0,0 +1,90 @@
+#!/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 json
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+from notebook.base.handlers import APIHandler
+from tornado import httputil
+from tornado.web import Application
+
+from ads.aqua.common.utils import is_pydantic_model
+from ads.aqua.extension.utils import construct_error
+from ads.config import AQUA_TELEMETRY_BUCKET, AQUA_TELEMETRY_BUCKET_NS
+from ads.telemetry.client import TelemetryClient
+
+
+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 Exception:
+            pass
+
+    def prepare(self, *args, **kwargs):
+        """The base class prepare is not required for Aqua"""
+        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)
+
+        if is_pydantic_model(obj):
+            return obj.model_dump()
+
+        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."""
+
+        reply_details = construct_error(status_code, **kwargs)
+
+        self.set_header("Content-Type", "application/json")
+        self.set_status(status_code, reason=reply_details.reason)
+
+        # telemetry may not be present if there is an error while initializing
+        if hasattr(self, "telemetry"):
+            aqua_api_details = kwargs.get("aqua_api_details", {})
+            self.telemetry.record_event_async(
+                category="aqua/error",
+                action=str(status_code),
+                value=reply_details.reason,
+                **aqua_api_details,
+            )
+
+        self.finish(reply_details)

ads/aqua/extension/common_handler.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python
+# Copyright (c) 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 importlib import metadata
+
+import huggingface_hub
+import requests
+from huggingface_hub import HfApi
+from huggingface_hub.utils import LocalTokenNotFoundError
+from tornado.web import HTTPError
+
+from ads.aqua.common.decorator import handle_exceptions
+from ads.aqua.common.errors import AquaRuntimeError
+from ads.aqua.common.utils import (
+    get_huggingface_login_timeout,
+)
+from ads.aqua.extension.base_handler import AquaAPIhandler
+from ads.aqua.extension.errors import Errors
+
+
+class ADSVersionHandler(AquaAPIhandler):
+    """The handler to get the current version of the ADS."""
+
+    @handle_exceptions
+    def get(self):
+        self.finish({"data": metadata.version("oracle_ads")})
+
+
+class CompatibilityCheckHandler(AquaAPIhandler):
+    """The handler to check if the extension is compatible."""
+
+    @handle_exceptions
+    def get(self):
+        """This method provides the availability status of Aqua. If ODSC_MODEL_COMPARTMENT_OCID environment variable
+        is set, then status `ok` is returned. For regions where Aqua is available but the environment variable is not
+        set due to accesses/policies, we return the `compatible` status to indicate that the extension can be enabled
+        for the selected notebook session.
+
+        Returns
+        -------
+        status dict:
+            ok or compatible
+
+        Raises
+        ------
+            AquaResourceAccessError: raised when aqua is not accessible in the given session/region.
+
+        """
+        return self.finish({"status": "ok"})
+
+
+class NetworkStatusHandler(AquaAPIhandler):
+    """Handler to check internet connection."""
+
+    @handle_exceptions
+    def get(self):
+        requests.get("https://huggingface.com", timeout=get_huggingface_login_timeout())
+        return self.finish({"status": 200, "message": "success"})
+
+
+class HFLoginHandler(AquaAPIhandler):
+    """Handler to login to HF."""
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):
+        """Handles post request for the HF login.
+
+        Raises
+        ------
+        HTTPError
+            Raises HTTPError if inputs are missing or are invalid.
+        """
+        try:
+            input_data = self.get_json_body()
+        except Exception as ex:
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT) from ex
+
+        if not input_data:
+            raise HTTPError(400, Errors.NO_INPUT_DATA)
+
+        token = input_data.get("token")
+
+        if not token:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("token"))
+
+        # Login to HF
+        try:
+            huggingface_hub.login(token=token, new_session=False)
+        except Exception as ex:
+            raise AquaRuntimeError(
+                reason=str(ex), service_payload={"error": type(ex).__name__}
+            ) from ex
+
+        return self.finish({"status": 200, "message": "login successful"})
+
+
+class HFUserStatusHandler(AquaAPIhandler):
+    """Handler to check if user logged in to the HF."""
+
+    @handle_exceptions
+    def get(self):
+        try:
+            HfApi().whoami()
+        except LocalTokenNotFoundError as err:
+            raise AquaRuntimeError(
+                "You are not logged in. Please log in to Hugging Face using the `huggingface-cli login` command."
+                "See https://huggingface.co/settings/tokens.",
+            ) from err
+
+        return self.finish({"status": 200, "message": "logged in"})
+
+
+__handlers__ = [
+    ("ads_version", ADSVersionHandler),
+    ("hello", CompatibilityCheckHandler),
+    ("network_status", NetworkStatusHandler),
+    ("hf_login", HFLoginHandler),
+    ("hf_logged_in", HFUserStatusHandler),
+]

ads/aqua/extension/common_ws_msg_handler.py

@@ -0,0 +1,36 @@
+#!/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 json
+from importlib import metadata
+from typing import List, Optional, Union
+
+from ads.aqua.common.decorator import handle_exceptions
+from ads.aqua.extension.aqua_ws_msg_handler import AquaWSMsgHandler
+from ads.aqua.extension.models.ws_models import (
+    AdsVersionResponse,
+    RequestResponseType,
+)
+
+
+class AquaCommonWsMsgHandler(AquaWSMsgHandler):
+    @staticmethod
+    def get_message_types() -> List[RequestResponseType]:
+        return [RequestResponseType.AdsVersion, RequestResponseType.CompatibilityCheck]
+
+    def __init__(self, message: Union[str, bytes]):
+        super().__init__(message)
+
+    @handle_exceptions
+    def process(self) -> Optional[AdsVersionResponse]:
+        request = json.loads(self.message)
+        if request.get("kind") == "AdsVersion":
+            version = metadata.version("oracle_ads")
+            response = AdsVersionResponse(
+                message_id=request.get("message_id"),
+                kind=RequestResponseType.AdsVersion,
+                data=version,
+            )
+            return response

ads/aqua/extension/deployment_handler.py

@@ -0,0 +1,298 @@
+#!/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 typing import List, Union
+from urllib.parse import urlparse
+
+from tornado.web import HTTPError
+
+from ads.aqua.common.decorator import handle_exceptions
+from ads.aqua.extension.base_handler import AquaAPIhandler
+from ads.aqua.extension.errors import Errors
+from ads.aqua.modeldeployment import AquaDeploymentApp, MDInferenceResponse
+from ads.aqua.modeldeployment.entities import ModelParams
+from ads.config import COMPARTMENT_OCID
+
+
+class AquaDeploymentHandler(AquaAPIhandler):
+    """
+    Handler for Aqua Deployment REST APIs.
+
+    Methods
+    -------
+    get(self, id: Union[str, List[str]])
+        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.
+    list_shapes(self)
+        Lists the valid model deployment shapes.
+
+    Raises
+    ------
+    HTTPError: For various failure scenarios such as invalid input format, missing data, etc.
+    """
+
+    @handle_exceptions
+    def get(self, id: Union[str, List[str]] = None):
+        """Handle GET request."""
+        url_parse = urlparse(self.request.path)
+        paths = url_parse.path.strip("/")
+        if paths.startswith("aqua/deployments/config"):
+            if not id or not isinstance(id, str):
+                raise HTTPError(
+                    400,
+                    f"Invalid request format for {self.request.path}. "
+                    "Expected a single model ID or a comma-separated list of model IDs.",
+                )
+            id = id.replace(" ", "")
+            return self.get_deployment_config(
+                model_id=id.split(",") if "," in id else id
+            )
+        elif paths.startswith("aqua/deployments/shapes"):
+            return self.list_shapes()
+        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 delete(self, model_deployment_id):
+        return self.finish(AquaDeploymentApp().delete(model_deployment_id))
+
+    @handle_exceptions
+    def put(self, *args, **kwargs):  # noqa: ARG002
+        """
+        Handles put request for the activating and deactivating OCI datascience model deployments
+        Raises
+        ------
+        HTTPError
+            Raises HTTPError if inputs are missing or are invalid
+        """
+        url_parse = urlparse(self.request.path)
+        paths = url_parse.path.strip("/").split("/")
+        if len(paths) != 4 or paths[0] != "aqua" or paths[1] != "deployments":
+            raise HTTPError(400, f"The request {self.request.path} is invalid.")
+
+        model_deployment_id = paths[2]
+        action = paths[3]
+        if action == "activate":
+            return self.finish(AquaDeploymentApp().activate(model_deployment_id))
+        elif action == "deactivate":
+            return self.finish(AquaDeploymentApp().deactivate(model_deployment_id))
+        else:
+            raise HTTPError(400, f"The request {self.request.path} is invalid.")
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):  # noqa: ARG002
+        """
+        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 as ex:
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT) from ex
+
+        if not input_data:
+            raise HTTPError(400, Errors.NO_INPUT_DATA)
+
+        self.finish(AquaDeploymentApp().create(**input_data))
+
+    def read(self, id):
+        """Read the information of an Aqua model deployment."""
+        return self.finish(AquaDeploymentApp().get(model_deployment_id=id))
+
+    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
+            )
+        )
+
+    def get_deployment_config(self, model_id: Union[str, List[str]]):
+        """
+        Retrieves the deployment configuration for one or more Aqua models.
+
+        Parameters
+        ----------
+        model_id : Union[str, List[str]]
+            A single model ID (str) or a list of model IDs (List[str]).
+
+        Returns
+        -------
+        None
+            The function sends the deployment configuration as a response.
+        """
+        app = AquaDeploymentApp()
+
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+
+        if isinstance(model_id, list):
+            # Handle multiple model deployment
+            primary_model_id = self.get_argument("primary_model_id", default=None)
+            deployment_config = app.get_multimodel_deployment_config(
+                model_ids=model_id,
+                primary_model_id=primary_model_id,
+                compartment_id=compartment_id,
+            )
+        else:
+            # Handle single model deployment
+            deployment_config = app.get_deployment_config(model_id=model_id)
+
+        return self.finish(deployment_config)
+
+    def list_shapes(self):
+        """
+        Lists the valid model deployment shapes.
+
+        Returns
+        -------
+        List[ComputeShapeSummary]:
+            The list of the model deployment shapes.
+        """
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+
+        return self.finish(
+            AquaDeploymentApp().list_shapes(compartment_id=compartment_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
+            return url.path.endswith("/predict")
+        except Exception:
+            return False
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):  # noqa: ARG002
+        """
+        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 as ex:
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT) from ex
+
+        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 Exception as ex:
+            raise HTTPError(
+                400, Errors.INVALID_INPUT_DATA_FORMAT.format("model_params")
+            ) from ex
+
+        return self.finish(
+            MDInferenceResponse(prompt, model_params_obj).get_model_deployment_response(
+                endpoint
+            )
+        )
+
+
+class AquaDeploymentParamsHandler(AquaAPIhandler):
+    """Handler for Aqua deployment params REST APIs.
+
+    Methods
+    -------
+    get(self, model_id)
+        Retrieves a list of model deployment parameters.
+    post(self, *args, **kwargs)
+        Validates parameters for the given model id.
+    """
+
+    @handle_exceptions
+    def get(self, model_id):
+        """Handle GET request."""
+        instance_shape = self.get_argument("instance_shape")
+        gpu_count = self.get_argument("gpu_count", default=None)
+        return self.finish(
+            AquaDeploymentApp().get_deployment_default_params(
+                model_id=model_id, instance_shape=instance_shape, gpu_count=gpu_count
+            )
+        )
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):  # noqa: ARG002
+        """Handles post request for the deployment param handler API.
+
+        Raises
+        ------
+        HTTPError
+            Raises HTTPError if inputs are missing or are invalid.
+        """
+        try:
+            input_data = self.get_json_body()
+        except Exception as ex:
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT) from ex
+
+        if not input_data:
+            raise HTTPError(400, Errors.NO_INPUT_DATA)
+
+        model_id = input_data.get("model_id")
+        if not model_id:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("model_id"))
+
+        params = input_data.get("params")
+        container_family = input_data.get("container_family")
+        return self.finish(
+            AquaDeploymentApp().validate_deployment_params(
+                model_id=model_id,
+                params=params,
+                container_family=container_family,
+            )
+        )
+
+
+__handlers__ = [
+    ("deployments/?([^/]*)/params", AquaDeploymentParamsHandler),
+    ("deployments/config/?([^/]*)", AquaDeploymentHandler),
+    ("deployments/shapes/?([^/]*)", AquaDeploymentHandler),
+    ("deployments/?([^/]*)", AquaDeploymentHandler),
+    ("deployments/?([^/]*)/activate", AquaDeploymentHandler),
+    ("deployments/?([^/]*)/deactivate", AquaDeploymentHandler),
+    ("inference", AquaDeploymentInferenceHandler),
+]