oracle-ads 2.13.3__py3-none-any.whl → 2.13.5__py3-none-any.whl

ads/aqua/extension/base_handler.py

@@ -2,19 +2,16 @@
 # 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
-import traceback
-import uuid
 from dataclasses import asdict, is_dataclass
-from http.client import responses
 from typing import Any
 
 from notebook.base.handlers import APIHandler
 from tornado import httputil
-from tornado.web import Application, HTTPError
+from tornado.web import Application
 
-from ads.aqua import logger
+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
 
@@ -40,7 +37,7 @@ class AquaAPIhandler(APIHandler):
     def prepare(self, *args, **kwargs):
         """The base class prepare is not required for Aqua"""
         pass
-        
+
     @staticmethod
     def serialize(obj: Any):
         """Serialize the object.
@@ -52,6 +49,9 @@ class AquaAPIhandler(APIHandler):
         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
@@ -71,37 +71,11 @@ class AquaAPIhandler(APIHandler):
 
     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", {})
-        default_msg = responses.get(status_code, "Unknown HTTP Error")
-        message = self.get_default_error_messages(
-            service_payload, str(status_code), kwargs.get("message", default_msg)
-        )
-
-        reply = {
-            "status": status_code,
-            "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']}"
-        )
+        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"):
@@ -109,40 +83,8 @@ class AquaAPIhandler(APIHandler):
             self.telemetry.record_event_async(
                 category="aqua/error",
                 action=str(status_code),
-                value=reason,
+                value=reply_details.reason,
                 **aqua_api_details,
             )
 
-        self.finish(json.dumps(reply))
-
-    @staticmethod
-    def get_default_error_messages(
-        service_payload: dict,
-        status_code: str,
-        default_msg: str = "Unknown HTTP Error.",
-    ):
-        """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.",
-            "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"] + f" Operation Name: {operation_name}."
-                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 default_msg
+        self.finish(reply_details)

ads/aqua/extension/deployment_handler.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python
-# Copyright (c) 2024 Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
+from typing import List, Union
 from urllib.parse import urlparse
 
 from tornado.web import HTTPError
@@ -11,7 +12,7 @@ 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, PROJECT_OCID
+from ads.config import COMPARTMENT_OCID
 
 
 class AquaDeploymentHandler(AquaAPIhandler):
@@ -20,7 +21,7 @@ class AquaDeploymentHandler(AquaAPIhandler):
 
     Methods
     -------
-    get(self, id="")
+    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.
@@ -30,6 +31,8 @@ class AquaDeploymentHandler(AquaAPIhandler):
         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
     ------
@@ -37,16 +40,23 @@ class AquaDeploymentHandler(AquaAPIhandler):
     """
 
     @handle_exceptions
-    def get(self, id=""):
+    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:
+            if not id or not isinstance(id, str):
                 raise HTTPError(
-                    400, f"The request {self.request.path} requires model id."
+                    400,
+                    f"Invalid request format for {self.request.path}. "
+                    "Expected a single model ID or a comma-separated list of model IDs.",
                 )
-            return self.get_deployment_config(id)
+            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()
@@ -98,71 +108,7 @@ class AquaDeploymentHandler(AquaAPIhandler):
         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")
-        web_concurrency = input_data.get("web_concurrency")
-        server_port = input_data.get("server_port")
-        health_check_port = input_data.get("health_check_port")
-        env_var = input_data.get("env_var")
-        container_family = input_data.get("container_family")
-        ocpus = input_data.get("ocpus")
-        memory_in_gbs = input_data.get("memory_in_gbs")
-        model_file = input_data.get("model_file")
-        private_endpoint_id = input_data.get("private_endpoint_id")
-        container_image_uri = input_data.get("container_image_uri")
-        cmd_var = input_data.get("cmd_var")
-        freeform_tags = input_data.get("freeform_tags")
-        defined_tags = input_data.get("defined_tags")
-
-        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,
-                web_concurrency=web_concurrency,
-                server_port=server_port,
-                health_check_port=health_check_port,
-                env_var=env_var,
-                container_family=container_family,
-                ocpus=ocpus,
-                memory_in_gbs=memory_in_gbs,
-                model_file=model_file,
-                private_endpoint_id=private_endpoint_id,
-                container_image_uri=container_image_uri,
-                cmd_var=cmd_var,
-                freeform_tags=freeform_tags,
-                defined_tags=defined_tags,
-            )
-        )
+        self.finish(AquaDeploymentApp().create(**input_data))
 
     def read(self, id):
         """Read the information of an Aqua model deployment."""
@@ -181,9 +127,52 @@ class AquaDeploymentHandler(AquaAPIhandler):
             )
         )
 
-    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))
+    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):
@@ -259,9 +248,10 @@ class AquaDeploymentParamsHandler(AquaAPIhandler):
     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
+                model_id=model_id, instance_shape=instance_shape, gpu_count=gpu_count
             )
         )
 
@@ -300,6 +290,7 @@ class AquaDeploymentParamsHandler(AquaAPIhandler):
 __handlers__ = [
     ("deployments/?([^/]*)/params", AquaDeploymentParamsHandler),
     ("deployments/config/?([^/]*)", AquaDeploymentHandler),
+    ("deployments/shapes/?([^/]*)", AquaDeploymentHandler),
     ("deployments/?([^/]*)", AquaDeploymentHandler),
     ("deployments/?([^/]*)/activate", AquaDeploymentHandler),
     ("deployments/?([^/]*)/deactivate", AquaDeploymentHandler),

ads/aqua/extension/errors.py

@@ -1,7 +1,16 @@
 #!/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 uuid
+from typing import Any, Dict, List, Optional
 
+from pydantic import Field
+
+from ads.aqua.config.utils.serializer import Serializable
+
+from ads.aqua.constants import (
+    AQUA_TROUBLESHOOTING_LINK
+)
 
 class Errors(str):
     INVALID_INPUT_DATA_FORMAT = "Invalid format of input data."
@@ -9,3 +18,13 @@ class Errors(str):
     MISSING_REQUIRED_PARAMETER = "Missing required parameter: '{}'"
     MISSING_ONEOF_REQUIRED_PARAMETER = "Either '{}' or '{}' is required."
     INVALID_VALUE_OF_PARAMETER = "Invalid value of parameter: '{}'"
+
+class ReplyDetails(Serializable):
+    """Structured reply to be returned to the client."""
+    status: int
+    troubleshooting_tips: str = Field(f"For general tips on troubleshooting: {AQUA_TROUBLESHOOTING_LINK}",
+                                      description="GitHub Link for troubleshooting documentation")
+    message: str = Field("Unknown HTTP Error.", description="GitHub Link for troubleshooting documentation")
+    service_payload: Optional[Dict[str, Any]] = Field(default_factory=dict)
+    reason: str = Field("Unknown error", description="Reason for Error")
+    request_id: str = Field(str(uuid.uuid4()), description="Unique ID for tracking the error.")

ads/aqua/extension/utils.py

@@ -1,16 +1,26 @@
 #!/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 re
+import traceback
+import uuid
 from dataclasses import fields
 from datetime import datetime, timedelta
+from http.client import responses
 from typing import Dict, Optional
 
 from cachetools import TTLCache, cached
 from tornado.web import HTTPError
 
-from ads.aqua import ODSC_MODEL_COMPARTMENT_OCID
+from ads.aqua import ODSC_MODEL_COMPARTMENT_OCID, logger
 from ads.aqua.common.utils import fetch_service_compartment
-from ads.aqua.extension.errors import Errors
+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):
@@ -32,3 +42,105 @@ def ui_compatability_check():
     fetched from the configuration. The cached result is returned when multiple calls are made in quick succession
     from the UI to avoid multiple config file loads."""
     return ODSC_MODEL_COMPARTMENT_OCID or fetch_service_compartment()
+
+
+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/finetuning.py

@@ -87,13 +87,62 @@ class AquaFineTuningApp(AquaApp):
     def create(
         self, create_fine_tuning_details: CreateFineTuningDetails = None, **kwargs
     ) -> "AquaFineTuningSummary":
-        """Creates Aqua fine tuning for model.
+        """Creates Aqua fine tuning for model.\n
+        For detailed information about CLI flags see: https://github.com/oracle-samples/oci-data-science-ai-samples/blob/f271ca63d12e3c256718f23a14d93da4b4fc086b/ai-quick-actions/cli-tips.md#create-fine-tuned-model
 
         Parameters
         ----------
         create_fine_tuning_details: CreateFineTuningDetails
             The CreateFineTuningDetails data class which contains all
             required and optional fields to create the aqua fine tuning.
+            kwargs:
+                ft_source_id: str The fine tuning source id. Must be model OCID.
+                ft_name: str
+                    The name for fine tuning.
+                dataset_path: str
+                    The dataset path for fine tuning. Could be either a local path from notebook session
+                    or an object storage path.
+                report_path: str
+                    The report path for fine tuning. Must be an object storage path.
+                ft_parameters: dict
+                    The parameters for fine tuning.
+                shape_name: str
+                    The shape name for fine tuning job infrastructure.
+                replica: int
+                    The replica for fine tuning job runtime.
+                validation_set_size: float
+                    The validation set size for fine tuning job. Must be a float in between [0,1).
+                ft_description: (str, optional). Defaults to `None`.
+                    The description for fine tuning.
+                compartment_id: (str, optional). Defaults to `None`.
+                    The compartment id for fine tuning.
+                project_id: (str, optional). Defaults to `None`.
+                    The project id for fine tuning.
+                experiment_id: (str, optional). Defaults to `None`.
+                    The fine tuning model version set id. If provided,
+                    fine tuning model will be associated with it.
+                experiment_name: (str, optional). Defaults to `None`.
+                    The fine tuning model version set name. If provided,
+                    the fine tuning version set with the same name will be used if exists,
+                    otherwise a new model version set will be created with the name.
+                experiment_description: (str, optional). Defaults to `None`.
+                    The description for fine tuning model version set.
+                block_storage_size: (int, optional). Defaults to 256.
+                    The storage for fine tuning job infrastructure.
+                subnet_id: (str, optional). Defaults to `None`.
+                    The custom egress for fine tuning job.
+                log_group_id: (str, optional). Defaults to `None`.
+                    The log group id for fine tuning job infrastructure.
+                log_id: (str, optional). Defaults to `None`.
+                    The log id for fine tuning job infrastructure.
+                watch_logs: (bool, optional). Defaults to `False`.
+                    The flag to watch the job run logs when a fine-tuning job is created.
+                force_overwrite: (bool, optional). Defaults to `False`.
+                    Whether to force overwrite the existing file in object storage.
+                freeform_tags: (dict, optional)
+                    Freeform tags for the fine-tuning model
+                defined_tags: (dict, optional)
+                    Defined tags for the fine-tuning model
         kwargs:
             The kwargs for creating CreateFineTuningDetails instance if
             no create_fine_tuning_details provided.

ads/aqua/model/constants.py

@@ -18,6 +18,8 @@ class ModelCustomMetadataFields(ExtendedEnum):
     EVALUATION_CONTAINER = "evaluation-container"
     FINETUNE_CONTAINER = "finetune-container"
     DEPLOYMENT_CONTAINER_URI = "deployment-container-uri"
+    MULTIMODEL_GROUP_COUNT = "model_group_count"
+    MULTIMODEL_METADATA = "multi_model_metadata"
 
 
 class ModelTask(ExtendedEnum):
@@ -34,6 +36,7 @@ class FineTuningMetricCategories(ExtendedEnum):
 class ModelType(ExtendedEnum):
     FT = "FT"  # Fine Tuned Model
     BASE = "BASE"  # Base model
+    MULTIMODEL = "MULTIMODEL"
 
 
 # TODO: merge metadata key used in create FT

ads/aqua/model/enums.py

@@ -23,3 +23,8 @@ class FineTuningCustomMetadata(ExtendedEnum):
     VALIDATION_METRICS_FINAL = "val_metrics_final"
     TRAINING_METRICS_EPOCH = "train_metrics_epoch"
     VALIDATION_METRICS_EPOCH = "val_metrics_epoch"
+
+
+class MultiModelSupportedTaskType(ExtendedEnum):
+    TEXT_GENERATION = "text-generation"
+    TEXT_GENERATION_ALT = "text_generation"