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

ads/aqua/extension/finetune_handler.py

@@ -0,0 +1,96 @@
+#!/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 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.finetuning import AquaFineTuningApp
+
+
+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):  # noqa: ARG002
+        """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 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(AquaFineTuningApp().create(**input_data))
+
+    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))
+
+
+class AquaFineTuneParamsHandler(AquaAPIhandler):
+    """Handler for Aqua finetuning params REST APIs."""
+
+    @handle_exceptions
+    def get(self, model_id):
+        """Handle GET request."""
+        return self.finish(
+            AquaFineTuningApp().get_finetuning_default_params(model_id=model_id)
+        )
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):  # noqa: ARG002
+        """Handles post request for the finetuning 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)
+
+        params = input_data.get("params", None)
+        return self.finish(
+            AquaFineTuningApp().validate_finetuning_params(
+                params=params,
+            )
+        )
+
+
+__handlers__ = [
+    ("finetuning/?([^/]*)/params", AquaFineTuneParamsHandler),
+    ("finetuning/?([^/]*)", AquaFineTuneHandler),
+    ("finetuning/config/?([^/]*)", AquaFineTuneHandler),
+]

ads/aqua/extension/model_handler.py

@@ -0,0 +1,390 @@
+#!/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 Optional
+from urllib.parse import urlparse
+
+from tornado.web import HTTPError
+
+from ads.aqua.common.decorator import handle_exceptions
+from ads.aqua.common.enums import CustomInferenceContainerTypeFamily
+from ads.aqua.common.errors import AquaRuntimeError
+from ads.aqua.common.utils import get_hf_model_info, is_valid_ocid, list_hf_models
+from ads.aqua.extension.base_handler import AquaAPIhandler
+from ads.aqua.extension.errors import Errors
+from ads.aqua.model import AquaModelApp
+from ads.aqua.model.entities import AquaModelSummary, HFModelSummary
+from ads.config import SERVICE
+from ads.model.common.utils import MetadataArtifactPathType
+
+
+class AquaModelHandler(AquaAPIhandler):
+    """Handler for Aqua Model REST APIs."""
+
+    @handle_exceptions
+    def get(
+        self,
+        model_id="",
+    ):
+        """Handle GET request."""
+        url_parse = urlparse(self.request.path)
+        paths = url_parse.path.strip("/")
+        if paths.startswith("aqua/model/files"):
+            os_path = self.get_argument("os_path", None)
+            model_name = self.get_argument("model_name", None)
+
+            model_format = self.get_argument("model_format")
+            if not model_format:
+                raise HTTPError(
+                    400, Errors.MISSING_REQUIRED_PARAMETER.format("model_format")
+                )
+
+            model_format = model_format.upper()
+
+            if os_path:
+                return self.finish(AquaModelApp.get_model_files(os_path, model_format))
+            elif model_name:
+                return self.finish(
+                    AquaModelApp.get_hf_model_files(model_name, model_format)
+                )
+            else:
+                raise HTTPError(
+                    400,
+                    Errors.MISSING_ONEOF_REQUIRED_PARAMETER.format(
+                        "os_path", "model_name"
+                    ),
+                )
+        elif not model_id:
+            return self.list()
+
+        return self.read(model_id)
+
+    def read(self, model_id):
+        """Read the information of an Aqua model."""
+        return self.finish(AquaModelApp().get(model_id))
+
+    @handle_exceptions
+    def delete(self, id=""):
+        """Handles DELETE request for clearing cache"""
+        url_parse = urlparse(self.request.path)
+        paths = url_parse.path.strip("/")
+        if paths.startswith("aqua/model/cache"):
+            return self.finish(AquaModelApp().clear_model_list_cache())
+        elif id:
+            return self.finish(AquaModelApp().delete_model(id))
+        else:
+            raise HTTPError(400, f"The request {self.request.path} is invalid.")
+
+    def list(self):
+        """List Aqua models."""
+        compartment_id = self.get_argument("compartment_id", default=None)
+        # project_id is no needed.
+        project_id = self.get_argument("project_id", default=None)
+        model_type = self.get_argument("model_type", default=None)
+        category = self.get_argument("category", default=SERVICE)
+        return self.finish(
+            AquaModelApp().list(
+                compartment_id=compartment_id,
+                project_id=project_id,
+                model_type=model_type,
+                category=category,
+            )
+        )
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):  # noqa: ARG002
+        """
+        Handles post request for the registering any Aqua model.
+        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)
+
+        # required input parameters
+        model = input_data.get("model")
+        if not model:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("model"))
+        os_path = input_data.get("os_path")
+        if not os_path:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("os_path"))
+
+        inference_container = input_data.get("inference_container")
+        finetuning_container = input_data.get("finetuning_container")
+        compartment_id = input_data.get("compartment_id")
+        project_id = input_data.get("project_id")
+        model_file = input_data.get("model_file")
+        download_from_hf = (
+            str(input_data.get("download_from_hf", "false")).lower() == "true"
+        )
+        local_dir = input_data.get("local_dir")
+        cleanup_model_cache = (
+            str(input_data.get("cleanup_model_cache", "false")).lower() == "true"
+        )
+        inference_container_uri = input_data.get("inference_container_uri")
+        allow_patterns = input_data.get("allow_patterns")
+        ignore_patterns = input_data.get("ignore_patterns")
+        freeform_tags = input_data.get("freeform_tags")
+        defined_tags = input_data.get("defined_tags")
+        ignore_model_artifact_check = (
+            str(input_data.get("ignore_model_artifact_check", "false")).lower()
+            == "true"
+        )
+
+        return self.finish(
+            AquaModelApp().register(
+                model=model,
+                os_path=os_path,
+                download_from_hf=download_from_hf,
+                local_dir=local_dir,
+                cleanup_model_cache=cleanup_model_cache,
+                inference_container=inference_container,
+                finetuning_container=finetuning_container,
+                compartment_id=compartment_id,
+                project_id=project_id,
+                model_file=model_file,
+                inference_container_uri=inference_container_uri,
+                allow_patterns=allow_patterns,
+                ignore_patterns=ignore_patterns,
+                freeform_tags=freeform_tags,
+                defined_tags=defined_tags,
+                ignore_model_artifact_check=ignore_model_artifact_check,
+            )
+        )
+
+    @handle_exceptions
+    def put(self, id):
+        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)
+
+        inference_container = input_data.get("inference_container")
+        inference_container_uri = input_data.get("inference_container_uri")
+        inference_containers = AquaModelApp.list_valid_inference_containers()
+        inference_containers.extend(CustomInferenceContainerTypeFamily.values())
+        if (
+            inference_container is not None
+            and inference_container not in inference_containers
+        ):
+            raise HTTPError(
+                400, Errors.INVALID_VALUE_OF_PARAMETER.format("inference_container")
+            )
+
+        enable_finetuning = input_data.get("enable_finetuning")
+        task = input_data.get("task")
+        app = AquaModelApp()
+        self.finish(
+            app.edit_registered_model(
+                id,
+                inference_container,
+                inference_container_uri,
+                enable_finetuning,
+                task,
+            )
+        )
+        app.clear_model_details_cache(model_id=id)
+
+
+class AquaModelLicenseHandler(AquaAPIhandler):
+    """Handler for Aqua Model license REST APIs."""
+
+    @handle_exceptions
+    def get(self, model_id):
+        """Handle GET request."""
+
+        model_id = model_id.split("/")[0]
+        return self.finish(AquaModelApp().load_license(model_id))
+
+
+class AquaModelReadmeHandler(AquaAPIhandler):
+    """
+    Handler for fetching model card for AQUA models
+    """
+
+    def get(self, model_id):
+        model_id = model_id.split("/")[0]
+        return self.finish(AquaModelApp().load_readme(model_id).model_dump())
+
+
+class AquaHuggingFaceHandler(AquaAPIhandler):
+    """Handler for Aqua Hugging Face REST APIs."""
+
+    @staticmethod
+    def _find_matching_aqua_model(model_id: str) -> Optional[AquaModelSummary]:
+        """
+        Finds a matching model in AQUA based on the model ID from Hugging Face.
+
+        Parameters
+        ----------
+        model_id (str): The Hugging Face model ID to match.
+
+        Returns
+        -------
+        Optional[AquaModelSummary]
+            Returns the matching AquaModelSummary object if found, else None.
+        """
+        # Convert the Hugging Face model ID to lowercase once
+        model_id_lower = model_id.lower()
+
+        aqua_model_app = AquaModelApp()
+        model_ocid = aqua_model_app._find_matching_aqua_model(model_id=model_id_lower)
+        if model_ocid:
+            return aqua_model_app.get(model_ocid, load_model_card=False)
+
+        return None
+
+    @handle_exceptions
+    def get(self, *args, **kwargs):  # noqa: ARG002
+        """
+        Finds a list of matching models from hugging face based on query string provided from users.
+
+        Parameters
+        ----------
+        query (str): The Hugging Face model name to search for.
+
+        Returns
+        -------
+        List[str]
+            Returns the matching model ids string
+        """
+
+        query = self.get_argument("query", default=None)
+        if not query:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("query"))
+        models = list_hf_models(query)
+        return self.finish({"models": models})
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):  # noqa: ARG002
+        """Handles post request for the HF Models 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)
+
+        model_id = input_data.get("model_id")
+
+        if not model_id:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("model_id"))
+
+        # Get model info from the HF
+        hf_model_info = get_hf_model_info(repo_id=model_id)
+
+        # Check if model is not disabled
+        if hf_model_info.disabled:
+            raise AquaRuntimeError(
+                f"The chosen model '{hf_model_info.id}' is currently disabled and cannot be imported into AQUA. "
+                "Please verify the model's status on the Hugging Face Model Hub or select a different model."
+            )
+
+        # Commented the validation below to let users to register any model type.
+        # # Check pipeline_tag, it should be `text-generation`
+        # if not (
+        #     hf_model_info.pipeline_tag
+        #     and hf_model_info.pipeline_tag.lower() in ModelTask
+        # ):
+        #     raise AquaRuntimeError(
+        #         f"Unsupported pipeline tag for the chosen model: '{hf_model_info.pipeline_tag}'. "
+        #         f"AQUA currently supports the following tasks only: {', '.join(ModelTask.values())}. "
+        #         "Please select a model with a compatible pipeline tag."
+        #     )
+
+        # Check if it is a service/verified model
+        aqua_model_info: AquaModelSummary = self._find_matching_aqua_model(
+            model_id=hf_model_info.id
+        )
+
+        return self.finish(
+            HFModelSummary(model_info=hf_model_info, aqua_model_info=aqua_model_info)
+        )
+
+
+class AquaModelTokenizerConfigHandler(AquaAPIhandler):
+    def get(self, model_id):
+        """
+        Handles requests for retrieving the Hugging Face tokenizer configuration of a specified model.
+        Expected request format: GET /aqua/models/<model-ocid>/tokenizer
+
+        """
+
+        path_list = urlparse(self.request.path).path.strip("/").split("/")
+        # Path should be /aqua/models/ocid1.iad.ahdxxx/tokenizer
+        # path_list=['aqua','models','<model-ocid>','tokenizer']
+        if (
+            len(path_list) == 4
+            and is_valid_ocid(path_list[2])
+            and path_list[3] == "tokenizer"
+        ):
+            return self.finish(AquaModelApp().get_hf_tokenizer_config(model_id))
+
+        raise HTTPError(400, f"The request {self.request.path} is invalid.")
+
+
+class AquaModelDefinedMetadataArtifactHandler(AquaAPIhandler):
+    """
+    Handler for Model Defined metadata artifact content
+
+    Raises
+    ------
+    HTTPError
+        Raises HTTPError if inputs are missing or are invalid.
+    """
+
+    @handle_exceptions
+    def get(self, model_id: str, metadata_key: str):
+        """
+        model_id: ocid of the model
+        metadata_key: the metadata key for which artifact content needs to be downloaded.
+        Can be any of Readme, License , FinetuneConfiguration , DeploymentConfiguration
+        """
+
+        return self.finish(
+            AquaModelApp().get_defined_metadata_artifact_content(model_id, metadata_key)
+        )
+
+    @handle_exceptions
+    def post(self, model_id: str, metadata_key: str):
+        input_body = self.get_json_body()
+        path_type = input_body.get("path_type")
+        artifact_path_or_content = input_body.get("artifact_path_or_content")
+        if path_type not in MetadataArtifactPathType.values():
+            raise HTTPError(400, f"Invalid value of path_type: {path_type}")
+        return self.finish(
+            AquaModelApp().create_defined_metadata_artifact(
+                model_id, metadata_key, path_type, artifact_path_or_content
+            )
+        )
+
+
+__handlers__ = [
+    ("model/?([^/]*)", AquaModelHandler),
+    ("model/?([^/]*)/license", AquaModelLicenseHandler),
+    ("model/?([^/]*)/readme", AquaModelReadmeHandler),
+    ("model/?([^/]*)/tokenizer", AquaModelTokenizerConfigHandler),
+    ("model/hf/search/?([^/]*)", AquaHuggingFaceHandler),
+    (
+        "model/?([^/]*)/definedMetadata/?([^/]*)",
+        AquaModelDefinedMetadataArtifactHandler,
+    ),
+]

ads/aqua/extension/models/ws_models.py

@@ -0,0 +1,145 @@
+#!/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 dataclasses import dataclass
+from typing import List, Optional
+
+import ads.config
+from ads.aqua.evaluation.entities import AquaEvaluationDetail, AquaEvaluationSummary
+from ads.aqua.model.entities import AquaModel, AquaModelSummary
+from ads.aqua.modeldeployment.entities import AquaDeployment, AquaDeploymentDetail
+from ads.common.extended_enum import ExtendedEnum
+from ads.common.serializer import DataClassSerializable
+
+
+class RequestResponseType(ExtendedEnum):
+    ListEvaluations = "ListEvaluations"
+    EvaluationDetails = "EvaluationDetails"
+    ListDeployments = "ListDeployments"
+    DeploymentDetails = "DeploymentDetails"
+    ListModels = "ListModels"
+    ModelDetails = "ModelDetails"
+    AdsVersion = "AdsVersion"
+    CompatibilityCheck = "CompatibilityCheck"
+    Error = "Error"
+
+
+@dataclass
+class BaseResponse(DataClassSerializable):
+    message_id: str
+    kind: RequestResponseType
+    data: Optional[object]
+
+
+@dataclass
+class BaseRequest(DataClassSerializable):
+    message_id: str
+    kind: RequestResponseType
+
+
+@dataclass
+class ListEvaluationsRequest(BaseRequest):
+    compartment_id: Optional[str] = None
+    limit: Optional[int] = None
+    project_id: Optional[str] = None
+    kind = RequestResponseType.ListEvaluations
+
+
+@dataclass
+class EvaluationDetailsRequest(BaseRequest):
+    kind = RequestResponseType.EvaluationDetails
+    evaluation_id: str
+
+
+@dataclass
+class ListModelsRequest(BaseRequest):
+    compartment_id: Optional[str] = None
+    project_id: Optional[str] = None
+    model_type: Optional[str] = None
+    category: str = ads.config.USER
+    kind = RequestResponseType.ListDeployments
+
+
+@dataclass
+class ModelDetailsRequest(BaseRequest):
+    kind = RequestResponseType.ModelDetails
+    model_id: str
+
+
+@dataclass
+class ListDeploymentRequest(BaseRequest):
+    compartment_id: str
+    project_id: Optional[str] = None
+    kind = RequestResponseType.ListDeployments
+
+
+@dataclass
+class DeploymentDetailsRequest(BaseRequest):
+    model_deployment_id: str
+    kind = RequestResponseType.DeploymentDetails
+
+
+@dataclass
+class ListEvaluationsResponse(BaseResponse):
+    data: List[AquaEvaluationSummary]
+
+
+@dataclass
+class EvaluationDetailsResponse(BaseResponse):
+    data: AquaEvaluationDetail
+
+
+@dataclass
+class ListDeploymentResponse(BaseResponse):
+    data: List[AquaDeployment]
+
+
+@dataclass
+class ModelDeploymentDetailsResponse(BaseResponse):
+    data: AquaDeploymentDetail
+
+
+@dataclass
+class ListModelsResponse(BaseResponse):
+    data: List[AquaModelSummary]
+
+
+@dataclass
+class ModelDetailsResponse(BaseResponse):
+    data: AquaModel
+
+
+@dataclass
+class AdsVersionRequest(BaseRequest):
+    kind: RequestResponseType.AdsVersion
+
+
+@dataclass
+class AdsVersionResponse(BaseResponse):
+    data: str
+
+
+@dataclass
+class CompatibilityCheckRequest(BaseRequest):
+    kind: RequestResponseType.CompatibilityCheck
+
+
+@dataclass
+class CompatibilityCheckResponse(BaseResponse):
+    data: object
+
+
+@dataclass
+class AquaWsError(DataClassSerializable):
+    status: str
+    message: str
+    service_payload: Optional[dict]
+    reason: Optional[str]
+
+
+@dataclass
+class ErrorResponse(BaseResponse):
+    data: AquaWsError
+    kind = RequestResponseType.Error

ads/aqua/extension/models_ws_msg_handler.py

@@ -0,0 +1,50 @@
+#!/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/
+
+import json
+from typing import List, 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 (
+    ListModelsResponse,
+    ModelDetailsResponse,
+    RequestResponseType,
+)
+from ads.aqua.model import AquaModelApp
+
+
+class AquaModelWSMsgHandler(AquaWSMsgHandler):
+    def __init__(self, message: Union[str, bytes]):
+        super().__init__(message)
+
+    @staticmethod
+    def get_message_types() -> List[RequestResponseType]:
+        return [RequestResponseType.ListModels, RequestResponseType.ModelDetails]
+
+    @handle_exceptions
+    def process(self) -> Union[ListModelsResponse, ModelDetailsResponse]:
+        request = json.loads(self.message)
+        if request.get("kind") == "ListModels":
+            models_list = AquaModelApp().list(
+                compartment_id=request.get("compartment_id"),
+                project_id=request.get("project_id"),
+                model_type=request.get("model_type"),
+                category=request.get("category"),
+            )
+            response = ListModelsResponse(
+                message_id=request.get("message_id"),
+                kind=RequestResponseType.ListModels,
+                data=models_list,
+            )
+            return response
+        elif request.get("kind") == "ModelDetails":
+            model_id = request.get("model_id")
+            response = AquaModelApp().get(model_id)
+            return ModelDetailsResponse(
+                message_id=request.get("message_id"),
+                kind=RequestResponseType.ModelDetails,
+                data=response,
+            )