oracle-ads 2.13.18rc0__py3-none-any.whl → 2.13.19__py3-none-any.whl

ads/aqua/common/utils.py

@@ -800,35 +800,49 @@ def is_service_managed_container(container):
 
 
 def get_params_list(params: str) -> List[str]:
-    """Parses the string parameter and returns a list of params.
+    """
+    Parses a string of CLI-style double-dash parameters and returns them as a list.
 
     Parameters
     ----------
-    params
-        string parameters by separated by -- delimiter
+    params : str
+        A single string containing parameters separated by the `--` delimiter.
 
     Returns
     -------
-        list of params
+    List[str]
+        A list of parameter strings, each starting with `--`.
 
+    Example
+    -------
+    >>> get_params_list("--max-model-len 65536 --enforce-eager")
+    ['--max-model-len 65536', '--enforce-eager']
     """
     if not params:
         return []
-    return ["--" + param.strip() for param in params.split("--")[1:]]
+    return [f"--{param.strip()}" for param in params.split("--") if param.strip()]
 
 
 def get_params_dict(params: Union[str, List[str]]) -> dict:
-    """Accepts a string or list of string of double-dash parameters and returns a dict with the parameter keys and values.
+    """
+    Converts CLI-style double-dash parameters (as string or list) into a dictionary.
 
     Parameters
     ----------
-    params:
-        List of parameters or parameter string separated by space.
+    params : Union[str, List[str]]
+        Parameters provided either as:
+        - a single string: "--key1 val1 --key2 val2"
+        - a list of strings: ["--key1 val1", "--key2 val2"]
 
     Returns
     -------
-        dict containing parameter keys and values
+    dict
+        A dictionary mapping parameter names to their values. If no value is found, uses `UNKNOWN`.
 
+    Example
+    -------
+    >>> get_params_dict("--max-model-len 65536 --enforce-eager")
+    {'--max-model-len': '65536', '--enforce-eager': ''}
     """
     params_list = get_params_list(params) if isinstance(params, str) else params
     return {
@@ -839,35 +853,43 @@ def get_params_dict(params: Union[str, List[str]]) -> dict:
     }
 
 
-def get_combined_params(params1: str = None, params2: str = None) -> str:
+def get_combined_params(
+    params1: Optional[str] = None, params2: Optional[str] = None
+) -> str:
     """
-    Combines string of double-dash parameters, and overrides the values from the second string in the first.
+    Merges two double-dash parameter strings (`--param value`) into one, with values from `params2`
+    overriding any duplicates from `params1`.
+
     Parameters
     ----------
-    params1:
-        Parameter string with values
-    params2:
-        Parameter string with values that need to be overridden.
+    params1 : Optional[str]
+        The base parameter string. Can be None.
+    params2 : Optional[str]
+        The override parameter string. Parameters in this string will override those in `params1`.
 
     Returns
     -------
-        A combined list with overridden values from params2.
+    str
+        A combined parameter string with deduplicated keys and overridden values from `params2`.
     """
+    if not params1 and not params2:
+        return ""
+
+    # If only one string is provided, return it directly
     if not params1:
-        return params2
+        return params2.strip()
     if not params2:
-        return params1
-
-    # overwrite values from params2 into params1
-    combined_params = [
-        f"{key} {value}" if value else key
-        for key, value in {
-            **get_params_dict(params1),
-            **get_params_dict(params2),
-        }.items()
-    ]
+        return params1.strip()
+
+    # Combine both dictionaries, with params2 overriding params1
+    merged_dict = {**get_params_dict(params1), **get_params_dict(params2)}
 
-    return " ".join(combined_params)
+    # Reconstruct the string
+    combined = " ".join(
+        f"{key} {value}" if value else key for key, value in merged_dict.items()
+    )
+
+    return combined.strip()
 
 
 def find_restricted_params(
@@ -905,28 +927,46 @@ def find_restricted_params(
     return restricted_params
 
 
-def build_params_string(params: dict) -> str:
-    """Builds params string from params dict
+def build_params_string(params: Optional[Dict[str, Any]]) -> str:
+    """
+    Converts a dictionary of CLI parameters into a command-line friendly string.
+
+    This is typically used to transform framework-specific model parameters (e.g., vLLM or TGI flags)
+    into a space-separated string that can be passed to container startup commands.
 
     Parameters
     ----------
-    params:
-        Parameter dict with key-value pairs
+    params : Optional[Dict[str, Any]]
+        Dictionary containing parameter name as keys (e.g., "--max-model-len") and their corresponding values.
+        If a parameter does not require a value (e.g., a boolean flag), its value can be None or an empty string.
 
     Returns
     -------
-        A params string.
+    str
+        A space-separated string of CLI arguments.
+        Returns "<unknown>" if the input dictionary is None or empty.
+
+    Example
+    -------
+    >>> build_params_string({"--max-model-len": 4096, "--enforce-eager": None})
+    '--max-model-len 4096 --enforce-eager'
     """
-    return (
-        " ".join(
-            f"{name} {value}" if value else f"{name}" for name, value in params.items()
-        ).strip()
-        if params
-        else UNKNOWN
-    )
+    if not params:
+        return UNKNOWN
+
+    parts = []
+    for key, value in params.items():
+        if value is None or value == "":
+            parts.append(str(key))
+        else:
+            parts.append(f"{key} {value}")
+
+    return " ".join(parts).strip()
 
 
-def copy_model_config(artifact_path: str, os_path: str, auth: dict = None):
+def copy_model_config(
+    artifact_path: str, os_path: str, auth: Optional[Dict[str, Any]] = None
+):
     """Copies the aqua model config folder from the artifact path to the user provided object storage path.
     The config folder is overwritten if the files already exist at the destination path.
 
@@ -1202,36 +1242,45 @@ def parse_cmd_var(cmd_list: List[str]) -> dict:
     return parsed_cmd
 
 
-def validate_cmd_var(cmd_var: List[str], overrides: List[str]) -> List[str]:
-    """This function accepts two lists of parameters and combines them. If the second list shares the common parameter
-    names/keys, then it raises an error.
+def validate_cmd_var(
+    cmd_var: Optional[List[str]], overrides: Optional[List[str]]
+) -> List[str]:
+    """
+    Validates and combines two lists of command-line parameters. Raises an error if any parameter
+    key in the `overrides` list already exists in the `cmd_var` list, preventing unintended overrides.
+
     Parameters
     ----------
-    cmd_var: List[str]
-        Default list of parameters
-    overrides: List[str]
-        List of parameters to override
+    cmd_var : Optional[List[str]]
+        The default list of command-line parameters (e.g., ["--param1", "value1", "--flag"]).
+    overrides : Optional[List[str]]
+        The list of overriding command-line parameters.
+
     Returns
     -------
-        List[str] of combined parameters
+    List[str]
+        A validated and combined list of parameters, with overrides appended.
+
+    Raises
+    ------
+    AquaValueError
+        If `overrides` contain any parameter keys that already exist in `cmd_var`.
     """
-    cmd_var = [str(x) for x in cmd_var]
-    if not overrides:
-        return cmd_var
-    overrides = [str(x) for x in overrides]
+    cmd_var = [str(x).strip() for x in cmd_var or []]
+    overrides = [str(x).strip() for x in overrides or []]
 
     cmd_dict = parse_cmd_var(cmd_var)
     overrides_dict = parse_cmd_var(overrides)
 
-    # check for conflicts
-    common_keys = set(cmd_dict.keys()) & set(overrides_dict.keys())
-    if common_keys:
+    # Check for conflicting keys
+    conflicting_keys = set(cmd_dict.keys()) & set(overrides_dict.keys())
+    if conflicting_keys:
         raise AquaValueError(
-            f"The following CMD input cannot be overridden for model deployment: {', '.join(common_keys)}"
+            f"Cannot override the following model deployment parameters: {', '.join(sorted(conflicting_keys))}"
         )
 
-    combined_cmd_var = cmd_var + overrides
-    return combined_cmd_var
+    combined_params = cmd_var + overrides
+    return combined_params
 
 
 def build_pydantic_error_message(ex: ValidationError):
@@ -1267,10 +1316,10 @@ def load_gpu_shapes_index(
     auth: Optional[Dict[str, Any]] = None,
 ) -> GPUShapesIndex:
     """
-    Load the GPU shapes index, preferring the OS bucket copy over the local one.
+    Load the GPU shapes index, merging based on freshness.
 
-    Attempts to read `gpu_shapes_index.json` from OCI Object Storage first;
-    if that succeeds, those entries will override the local defaults.
+    Compares last-modified timestamps of local and remote files,
+    merging the shapes from the fresher file on top of the older one.
 
     Parameters
     ----------
@@ -1291,7 +1340,9 @@ def load_gpu_shapes_index(
     file_name = "gpu_shapes_index.json"
 
     # Try remote load
-    remote_data: Dict[str, Any] = {}
+    local_data, remote_data = {}, {}
+    local_mtime, remote_mtime = None, None
+
     if CONDA_BUCKET_NS:
         try:
             auth = auth or authutil.default_signer()
@@ -1301,8 +1352,24 @@ def load_gpu_shapes_index(
             logger.debug(
                 "Loading GPU shapes index from Object Storage: %s", storage_path
             )
-            with fsspec.open(storage_path, mode="r", **auth) as f:
+
+            fs = fsspec.filesystem("oci", **auth)
+            with fs.open(storage_path, mode="r") as f:
                 remote_data = json.load(f)
+
+            remote_info = fs.info(storage_path)
+            remote_mtime_str = remote_info.get("timeModified", None)
+            if remote_mtime_str:
+                # Convert OCI timestamp (e.g., 'Mon, 04 Aug 2025 06:37:13 GMT') to epoch time
+                remote_mtime = datetime.strptime(
+                    remote_mtime_str, "%a, %d %b %Y %H:%M:%S %Z"
+                ).timestamp()
+
+                logger.debug(
+                    "Remote GPU shapes last-modified time: %s",
+                    datetime.fromtimestamp(remote_mtime).strftime("%Y-%m-%d %H:%M:%S"),
+                )
+
             logger.debug(
                 "Loaded %d shapes from Object Storage",
                 len(remote_data.get("shapes", {})),
@@ -1311,12 +1378,19 @@ def load_gpu_shapes_index(
             logger.debug("Remote load failed (%s); falling back to local", ex)
 
     # Load local copy
-    local_data: Dict[str, Any] = {}
     local_path = os.path.join(os.path.dirname(__file__), "../resources", file_name)
     try:
         logger.debug("Loading GPU shapes index from local file: %s", local_path)
         with open(local_path) as f:
             local_data = json.load(f)
+
+        local_mtime = os.path.getmtime(local_path)
+
+        logger.debug(
+            "Local GPU shapes last-modified time: %s",
+            datetime.fromtimestamp(local_mtime).strftime("%Y-%m-%d %H:%M:%S"),
+        )
+
         logger.debug(
             "Loaded %d shapes from local file", len(local_data.get("shapes", {}))
         )
@@ -1326,7 +1400,24 @@ def load_gpu_shapes_index(
     # Merge: remote shapes override local
     local_shapes = local_data.get("shapes", {})
     remote_shapes = remote_data.get("shapes", {})
-    merged_shapes = {**local_shapes, **remote_shapes}
+    merged_shapes = {}
+
+    if local_mtime and remote_mtime:
+        if remote_mtime >= local_mtime:
+            logger.debug("Remote data is fresher or equal; merging remote over local.")
+            merged_shapes = {**local_shapes, **remote_shapes}
+        else:
+            logger.debug("Local data is fresher; merging local over remote.")
+            merged_shapes = {**remote_shapes, **local_shapes}
+    elif remote_shapes:
+        logger.debug("Only remote shapes available.")
+        merged_shapes = remote_shapes
+    elif local_shapes:
+        logger.debug("Only local shapes available.")
+        merged_shapes = local_shapes
+    else:
+        logger.error("No GPU shapes data found in either source.")
+        merged_shapes = {}
 
     return GPUShapesIndex(shapes=merged_shapes)
 

ads/aqua/constants.py

@@ -56,6 +56,9 @@ SUPPORTED_FILE_FORMATS = ["jsonl"]
 MODEL_BY_REFERENCE_OSS_PATH_KEY = "artifact_location"
 
 AQUA_CHAT_TEMPLATE_METADATA_KEY = "chat_template"
+UNKNOWN_ENUM_VALUE = "UNKNOWN_ENUM_VALUE"
+MODEL_GROUP = "MODEL_GROUP"
+SINGLE_MODEL_FLEX = "SINGLE_MODEL_FLEX"
 
 CONSOLE_LINK_RESOURCE_TYPE_MAPPING = {
     "datasciencemodel": "models",

ads/aqua/extension/deployment_handler.py

@@ -57,6 +57,15 @@ class AquaDeploymentHandler(AquaAPIhandler):
             return self.get_deployment_config(
                 model_id=id.split(",") if "," in id else id
             )
+        elif paths.startswith("aqua/deployments/recommend_shapes"):
+            if not id or not isinstance(id, str):
+                raise HTTPError(
+                    400,
+                    f"Invalid request format for {self.request.path}. "
+                    "Expected a single model OCID specified as --model_id",
+                )
+            id = id.replace(" ", "")
+            return self.get_recommend_shape(model_id=id)
         elif paths.startswith("aqua/deployments/shapes"):
             return self.list_shapes()
         elif paths.startswith("aqua/deployments"):
@@ -161,6 +170,32 @@ class AquaDeploymentHandler(AquaAPIhandler):
 
         return self.finish(deployment_config)
 
+    def get_recommend_shape(self, model_id: str):
+        """
+        Retrieves the valid shape and deployment parameter configuration for one Aqua Model.
+
+        Parameters
+        ----------
+        model_id : str
+            A single model ID (str).
+
+        Returns
+        -------
+        None
+            The function sends the ShapeRecommendReport (generate_table = False) or Rich Diff Table (generate_table = True)
+        """
+        app = AquaDeploymentApp()
+
+        compartment_id = self.get_argument("compartment_id", default=COMPARTMENT_OCID)
+
+        recommend_report = app.recommend_shape(
+            model_id=model_id,
+            compartment_id=compartment_id,
+            generate_table=False,
+        )
+
+        return self.finish(recommend_report)
+
     def list_shapes(self):
         """
         Lists the valid model deployment shapes.
@@ -408,6 +443,7 @@ __handlers__ = [
     ("deployments/?([^/]*)/params", AquaDeploymentParamsHandler),
     ("deployments/config/?([^/]*)", AquaDeploymentHandler),
     ("deployments/shapes/?([^/]*)", AquaDeploymentHandler),
+    ("deployments/recommend_shapes/?([^/]*)", AquaDeploymentHandler),
     ("deployments/?([^/]*)", AquaDeploymentHandler),
     ("deployments/?([^/]*)/activate", AquaDeploymentHandler),
     ("deployments/?([^/]*)/deactivate", AquaDeploymentHandler),

ads/aqua/modeldeployment/constants.py

@@ -11,3 +11,4 @@ This module contains constants used in Aqua Model Deployment.
 
 DEFAULT_WAIT_TIME = 12000
 DEFAULT_POLL_INTERVAL = 10
+

ads/aqua/modeldeployment/deployment.py

@@ -8,11 +8,12 @@ import re
 import shlex
 import threading
 from datetime import datetime, timedelta
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Union
 
 from cachetools import TTLCache, cached
 from oci.data_science.models import ModelDeploymentShapeSummary
 from pydantic import ValidationError
+from rich.table import Table
 
 from ads.aqua.app import AquaApp, logger
 from ads.aqua.common.entities import (
@@ -44,8 +45,11 @@ from ads.aqua.constants import (
     AQUA_MODEL_TYPE_SERVICE,
     AQUA_MULTI_MODEL_CONFIG,
     MODEL_BY_REFERENCE_OSS_PATH_KEY,
+    MODEL_GROUP,
     MODEL_NAME_DELIMITER,
+    SINGLE_MODEL_FLEX,
     UNKNOWN_DICT,
+    UNKNOWN_ENUM_VALUE,
 )
 from ads.aqua.data import AquaResourceIdentifier
 from ads.aqua.model import AquaModelApp
@@ -72,6 +76,11 @@ from ads.aqua.modeldeployment.entities import (
     CreateModelDeploymentDetails,
 )
 from ads.aqua.modeldeployment.model_group_config import ModelGroupConfig
+from ads.aqua.shaperecommend.recommend import AquaShapeRecommend
+from ads.aqua.shaperecommend.shape_report import (
+    RequestRecommend,
+    ShapeRecommendationReport,
+)
 from ads.common.object_storage_details import ObjectStorageDetails
 from ads.common.utils import UNKNOWN, get_log_links
 from ads.common.work_request import DataScienceWorkRequest
@@ -511,12 +520,23 @@ class AquaDeploymentApp(AquaApp):
 
         deployment_config = self.get_deployment_config(model_id=config_source_id)
 
+        # Loads frameworks specific default params from the configuration
         config_params = deployment_config.configuration.get(
             create_deployment_details.instance_shape, ConfigurationItem()
         ).parameters.get(get_container_params_type(container_type_key), UNKNOWN)
 
+        # Loads default environment variables from the configuration
+        config_env = deployment_config.configuration.get(
+            create_deployment_details.instance_shape, ConfigurationItem()
+        ).env.get(get_container_params_type(container_type_key), {})
+
+        # Merges user provided environment variables with the ones provided in the deployment config
+        # The values provided by user will override the ones provided by default config
+        env_var = {**config_env, **env_var}
+
         # validate user provided params
         user_params = env_var.get("PARAMS", UNKNOWN)
+
         if user_params:
             # todo: remove this check in the future version, logic to be moved to container_index
             if (
@@ -542,6 +562,18 @@ class AquaDeploymentApp(AquaApp):
         deployment_params = get_combined_params(config_params, user_params)
 
         params = f"{params} {deployment_params}".strip()
+
+        if create_deployment_details.model_name:
+            # Replace existing --served-model-name argument if present, otherwise add it
+            if "--served-model-name" in params:
+                params = re.sub(
+                    r"--served-model-name\s+\S+",
+                    f"--served-model-name {create_deployment_details.model_name}",
+                    params,
+                )
+            else:
+                params += f" --served-model-name {create_deployment_details.model_name}"
+
         if params:
             env_var.update({"PARAMS": params})
         env_vars = container_spec.env_vars if container_spec else []
@@ -621,8 +653,8 @@ class AquaDeploymentApp(AquaApp):
 
         env_var.update({AQUA_MULTI_MODEL_CONFIG: multi_model_config.model_dump_json()})
 
-        env_vars = container_spec.env_vars if container_spec else []
-        for env in env_vars:
+        container_spec_env_vars = container_spec.env_vars if container_spec else []
+        for env in container_spec_env_vars:
             if isinstance(env, dict):
                 env = {k: v for k, v in env.items() if v}
                 for key, _ in env.items():
@@ -864,21 +896,26 @@ class AquaDeploymentApp(AquaApp):
 
             if oci_aqua:
                 # skipping the AQUA model deployments that are created from model group
-                # TODO: remove this checker after AQUA deployment is integrated with model group
-                aqua_model_id = model_deployment.freeform_tags.get(
-                    Tags.AQUA_MODEL_ID_TAG, UNKNOWN
-                )
                 if (
-                    "datasciencemodelgroup" in aqua_model_id
-                    or model_deployment.model_deployment_configuration_details.deployment_type
-                    == "UNKNOWN_ENUM_VALUE"
+                    model_deployment.model_deployment_configuration_details.deployment_type
+                    in [UNKNOWN_ENUM_VALUE, MODEL_GROUP, SINGLE_MODEL_FLEX]
                 ):
                     continue
-                results.append(
-                    AquaDeployment.from_oci_model_deployment(
-                        model_deployment, self.region
+                try:
+                    results.append(
+                        AquaDeployment.from_oci_model_deployment(
+                            model_deployment, self.region
+                        )
                     )
-                )
+                except Exception as e:
+                    logger.error(
+                        f"There was an issue processing the list of model deployments . Error: {str(e)}",
+                        exc_info=True,
+                    )
+                    raise AquaRuntimeError(
+                        f"There was an issue processing the list of model deployments . Error: {str(e)}"
+                    ) from e
+
                 # log telemetry if MD is in active or failed state
                 deployment_id = model_deployment.id
                 state = model_deployment.lifecycle_state.upper()
@@ -1249,6 +1286,50 @@ class AquaDeploymentApp(AquaApp):
             )
         return {"valid": True}
 
+    def recommend_shape(self, **kwargs) -> Union[Table, ShapeRecommendationReport]:
+        """
+        For the CLI (set generate_table = True), generates the table (in rich diff) with valid
+        GPU deployment shapes for the provided model and configuration.
+
+        For the API (set generate_table = False), generates the JSON with valid
+        GPU deployment shapes for the provided model and configuration.
+
+        Validates if recommendations are generated, calls method to construct the rich diff
+        table with the recommendation data.
+
+        Parameters
+        ----------
+        model_ocid : str
+        OCID of the model to recommend feasible compute shapes.
+
+        Returns
+        -------
+        Table (generate_table = True)
+            A table format for the recommendation report with compatible deployment shapes
+            or troubleshooting info citing the largest shapes if no shape is suitable.
+
+        ShapeRecommendationReport (generate_table = False)
+            A recommendation report with compatible deployment shapes, or troubleshooting info
+            citing the largest shapes if no shape is suitable.
+
+        Raises
+        ------
+        AquaValueError
+            If model type is unsupported by tool (no recommendation report generated)
+        """
+        try:
+            request = RequestRecommend(**kwargs)
+        except ValidationError as e:
+            custom_error = build_pydantic_error_message(e)
+            raise AquaValueError(  # noqa: B904
+                f"Failed to request shape recommendation due to invalid input parameters: {custom_error}"
+            )
+
+        shape_recommend = AquaShapeRecommend()
+        shape_recommend_report = shape_recommend.which_shapes(request)
+
+        return shape_recommend_report
+
     @telemetry(entry_point="plugin=deployment&action=list_shapes", name="aqua")
     @cached(cache=TTLCache(maxsize=1, ttl=timedelta(minutes=5), timer=datetime.now))
     def list_shapes(self, **kwargs) -> List[ComputeShapeSummary]:

ads/aqua/modeldeployment/entities.py

@@ -233,6 +233,9 @@ class CreateModelDeploymentDetails(BaseModel):
         None, description="The description of the deployment."
     )
     model_id: Optional[str] = Field(None, description="The model OCID to deploy.")
+    model_name: Optional[str] = Field(
+        None, description="The model name specified by user to deploy."
+    )
 
     models: Optional[List[AquaMultiModelRef]] = Field(
         None, description="List of models for multimodel deployment."

ads/aqua/modeldeployment/model_group_config.py

@@ -130,7 +130,7 @@ class ModelGroupConfig(Serializable):
         Validates if user-provided parameters override pre-set parameters by AQUA.
         Updates model name and TP size parameters to user-provided parameters.
         """
-        user_params = build_params_string(model.env_var)
+        user_params = build_params_string(model.params)
         if user_params:
             restricted_params = find_restricted_params(
                 container_params, user_params, container_type_key
@@ -138,8 +138,8 @@ class ModelGroupConfig(Serializable):
             if restricted_params:
                 selected_model = model.model_name or model.model_id
                 raise AquaValueError(
-                    f"Parameters {restricted_params} are set by Aqua "
-                    f"and cannot be overridden or are invalid."
+                    f"Parameters {restricted_params} are set by AI Quick Actions "
+                    f"and cannot be overridden or are invalid. "
                     f"Select other parameters for model {selected_model}."
                 )