oracle-ads 2.13.11__py3-none-any.whl → 2.13.13__py3-none-any.whl

ads/aqua/app.py

@@ -5,6 +5,7 @@
 import json
 import os
 import traceback
+from concurrent.futures import ThreadPoolExecutor
 from dataclasses import fields
 from datetime import datetime, timedelta
 from itertools import chain
@@ -22,7 +23,7 @@ from ads import set_auth
 from ads.aqua import logger
 from ads.aqua.common.entities import ModelConfigResult
 from ads.aqua.common.enums import ConfigFolder, Tags
-from ads.aqua.common.errors import AquaRuntimeError, AquaValueError
+from ads.aqua.common.errors import AquaValueError
 from ads.aqua.common.utils import (
     _is_valid_mvs,
     get_artifact_path,
@@ -58,6 +59,8 @@ from ads.telemetry.client import TelemetryClient
 class AquaApp:
     """Base Aqua App to contain common components."""
 
+    MAX_WORKERS = 10  # Number of workers for asynchronous resource loading
+
     @telemetry(name="aqua")
     def __init__(self) -> None:
         if OCI_RESOURCE_PRINCIPAL_VERSION:
@@ -128,20 +131,69 @@ class AquaApp:
             update_model_provenance_details=update_model_provenance_details,
         )
 
-    # TODO: refactor model evaluation implementation to use it.
     @staticmethod
     def get_source(source_id: str) -> Union[ModelDeployment, DataScienceModel]:
-        if is_valid_ocid(source_id):
-            if "datasciencemodeldeployment" in source_id:
-                return ModelDeployment.from_id(source_id)
-            elif "datasciencemodel" in source_id:
-                return DataScienceModel.from_id(source_id)
+        """
+        Fetches a model or model deployment based on the provided OCID.
+
+        Parameters
+        ----------
+        source_id : str
+            OCID of the Data Science model or model deployment.
+
+        Returns
+        -------
+        Union[ModelDeployment, DataScienceModel]
+            The corresponding resource object.
 
+        Raises
+        ------
+        AquaValueError
+            If the OCID is invalid or unsupported.
+        """
+        logger.debug(f"Resolving source for ID: {source_id}")
+        if not is_valid_ocid(source_id):
+            logger.error(f"Invalid OCID format: {source_id}")
+            raise AquaValueError(
+                f"Invalid source ID: {source_id}. Please provide a valid model or model deployment OCID."
+            )
+
+        if "datasciencemodeldeployment" in source_id:
+            logger.debug(f"Identified as ModelDeployment OCID: {source_id}")
+            return ModelDeployment.from_id(source_id)
+
+        if "datasciencemodel" in source_id:
+            logger.debug(f"Identified as DataScienceModel OCID: {source_id}")
+            return DataScienceModel.from_id(source_id)
+
+        logger.error(f"Unrecognized OCID type: {source_id}")
         raise AquaValueError(
-            f"Invalid source {source_id}. "
-            "Specify either a model or model deployment id."
+            f"Unsupported source ID type: {source_id}. Must be a model or model deployment OCID."
         )
 
+    def get_multi_source(
+        self,
+        ids: List[str],
+    ) -> Dict[str, Union[ModelDeployment, DataScienceModel]]:
+        """
+        Retrieves multiple DataScience resources concurrently.
+
+        Parameters
+        ----------
+        ids : List[str]
+            A list of DataScience OCIDs.
+
+        Returns
+        -------
+        Dict[str, Union[ModelDeployment, DataScienceModel]]
+            A mapping from OCID to the corresponding resolved resource object.
+        """
+        logger.debug(f"Fetching {ids} sources in parallel.")
+        with ThreadPoolExecutor(max_workers=self.MAX_WORKERS) as executor:
+            results = list(executor.map(self.get_source, ids))
+
+        return dict(zip(ids, results))
+
     # TODO: refactor model evaluation implementation to use it.
     @staticmethod
     def create_model_version_set(
@@ -284,8 +336,11 @@ class AquaApp:
                 logger.info(f"Artifact not found in model {model_id}.")
                 return False
 
+    @cached(cache=TTLCache(maxsize=5, ttl=timedelta(minutes=1), timer=datetime.now))
     def get_config_from_metadata(
-        self, model_id: str, metadata_key: str
+        self,
+        model_id: str,
+        metadata_key: str,
     ) -> ModelConfigResult:
         """Gets the config for the given Aqua model from model catalog metadata content.
 
@@ -300,8 +355,9 @@ class AquaApp:
         ModelConfigResult
             A Pydantic model containing the model_details (extracted from OCI) and the config dictionary.
         """
-        config = {}
+        config: Dict[str, Any] = {}
         oci_model = self.ds_client.get_model(model_id).data
+
         try:
             config = self.ds_client.get_model_defined_metadatum_artifact_content(
                 model_id, metadata_key
@@ -321,7 +377,7 @@ class AquaApp:
             )
         return ModelConfigResult(config=config, model_details=oci_model)
 
-    @cached(cache=TTLCache(maxsize=1, ttl=timedelta(minutes=1), timer=datetime.now))
+    @cached(cache=TTLCache(maxsize=1, ttl=timedelta(minutes=5), timer=datetime.now))
     def get_config(
         self,
         model_id: str,
@@ -346,8 +402,10 @@ class AquaApp:
         ModelConfigResult
             A Pydantic model containing the model_details (extracted from OCI) and the config dictionary.
         """
-        config_folder = config_folder or ConfigFolder.CONFIG
+        config: Dict[str, Any] = {}
         oci_model = self.ds_client.get_model(model_id).data
+
+        config_folder = config_folder or ConfigFolder.CONFIG
         oci_aqua = (
             (
                 Tags.AQUA_TAG in oci_model.freeform_tags
@@ -357,9 +415,9 @@ class AquaApp:
             else False
         )
         if not oci_aqua:
-            raise AquaRuntimeError(f"Target model {oci_model.id} is not an Aqua model.")
+            logger.debug(f"Target model {oci_model.id} is not an Aqua model.")
+            return ModelConfigResult(config=config, model_details=oci_model)
 
-        config: Dict[str, Any] = {}
         artifact_path = get_artifact_path(oci_model.custom_metadata_list)
         if not artifact_path:
             logger.debug(

ads/aqua/cli.py

@@ -14,6 +14,7 @@ from ads.aqua.evaluation import AquaEvaluationApp
 from ads.aqua.finetuning import AquaFineTuningApp
 from ads.aqua.model import AquaModelApp
 from ads.aqua.modeldeployment import AquaDeploymentApp
+from ads.aqua.verify_policies import AquaVerifyPoliciesApp
 from ads.common.utils import LOG_LEVELS
 
 
@@ -29,6 +30,7 @@ class AquaCommand:
     fine_tuning = AquaFineTuningApp
     deployment = AquaDeploymentApp
     evaluation = AquaEvaluationApp
+    verify_policies = AquaVerifyPoliciesApp
 
     def __init__(
         self,
@@ -94,3 +96,18 @@ class AquaCommand:
                 "If you intend to chain a function call to the result, please separate the "
                 "flag and the subsequent function call with separator `-`."
             )
+    
+    @staticmethod
+    def install():
+        """Install ADS Aqua Extension from wheel file. Set enviroment variable `AQUA_EXTENSTION_PATH` to change the wheel file path.
+
+        Return 
+        ------
+        int:
+            Installatation status.
+        """
+        import subprocess
+
+        wheel_file_path = os.environ.get("AQUA_EXTENSTION_PATH", "/ads/extension/adsjupyterlab_aqua_extension*.whl")
+        status =  subprocess.run(f"pip install {wheel_file_path}",shell=True)
+        return status.check_returncode

ads/aqua/client/client.py

@@ -61,13 +61,20 @@ class HttpxOCIAuth(httpx.Auth):
 
     def __init__(self, signer: Optional[oci.signer.Signer] = None):
         """
-        Initialize the HttpxOCIAuth instance.
+        Initializes the authentication handler with the given or default OCI signer.
 
-        Args:
-            signer (oci.signer.Signer): The OCI signer to use for signing requests.
+        Parameters
+        ----------
+        signer : oci.signer.Signer, optional
+            The OCI signer instance to use. If None, a default signer will be retrieved.
         """
-
-        self.signer = signer or authutil.default_signer().get("signer")
+        try:
+            self.signer = signer or authutil.default_signer().get("signer")
+            if not self.signer:
+                raise ValueError("OCI signer could not be initialized.")
+        except Exception as e:
+            logger.error("Failed to initialize OCI signer: %s", e)
+            raise
 
     def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
         """
@@ -80,21 +87,31 @@ class HttpxOCIAuth(httpx.Auth):
             httpx.Request: The signed HTTPX request.
         """
         # Create a requests.Request object from the HTTPX request
-        req = requests.Request(
-            method=request.method,
-            url=str(request.url),
-            headers=dict(request.headers),
-            data=request.content,
-        )
-        prepared_request = req.prepare()
+        try:
+            req = requests.Request(
+                method=request.method,
+                url=str(request.url),
+                headers=dict(request.headers),
+                data=request.content,
+            )
+            prepared_request = req.prepare()
+            self.signer.do_request_sign(prepared_request)
+
+            # Replace headers on the original HTTPX request with signed headers
+            request.headers.update(prepared_request.headers)
+            logger.debug("Successfully signed request to %s", request.url)
 
-        # Sign the request using the OCI Signer
-        self.signer.do_request_sign(prepared_request)
+            # Fix for GET/DELETE requests that OCI Gateway expects with Content-Length
+            if (
+                request.method in ["GET", "DELETE"]
+                and "content-length" not in request.headers
+            ):
+                request.headers["content-length"] = "0"
 
-        # Update the original HTTPX request with the signed headers
-        request.headers.update(prepared_request.headers)
+        except Exception as e:
+            logger.error("Failed to sign request to %s: %s", request.url, e)
+            raise
 
-        # Proceed with the request
         yield request
 
 
@@ -330,8 +347,8 @@ class BaseClient:
             "Content-Type": "application/json",
             "Accept": "text/event-stream" if stream else "application/json",
         }
-        if stream:
-            default_headers["enable-streaming"] = "true"
+        # if stream:
+        #     default_headers["enable-streaming"] = "true"
         if headers:
             default_headers.update(headers)
 
@@ -495,7 +512,7 @@ class Client(BaseClient):
         prompt: str,
         payload: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = None,
-        stream: bool = True,
+        stream: bool = False,
     ) -> Union[Dict[str, Any], Iterator[Mapping[str, Any]]]:
         """
         Generate text completion for the given prompt.
@@ -521,7 +538,7 @@ class Client(BaseClient):
         messages: List[Dict[str, Any]],
         payload: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = None,
-        stream: bool = True,
+        stream: bool = False,
     ) -> Union[Dict[str, Any], Iterator[Mapping[str, Any]]]:
         """
         Perform a chat interaction with the model.

ads/aqua/client/openai_client.py

@@ -32,7 +32,7 @@ class ModelDeploymentBaseEndpoint(ExtendedEnum):
     """Supported base endpoints for model deployments."""
 
     PREDICT = "predict"
-    PREDICT_WITH_RESPONSE_STREAM = "predictwithresponsestream"
+    PREDICT_WITH_RESPONSE_STREAM = "predictWithResponseStream"
 
 
 class AquaOpenAIMixin:
@@ -51,9 +51,9 @@ class AquaOpenAIMixin:
         Returns:
             str: The normalized OpenAI-compatible route path (e.g., '/v1/chat/completions').
         """
-        normalized_path = original_path.lower().rstrip("/")
+        normalized_path = original_path.rstrip("/")
 
-        match = re.search(r"/predict(withresponsestream)?", normalized_path)
+        match = re.search(r"/predict(WithResponseStream)?", normalized_path)
         if not match:
             logger.debug("Route header cannot be resolved from path: %s", original_path)
             return ""
@@ -71,7 +71,7 @@ class AquaOpenAIMixin:
                 "Route suffix does not start with a version prefix (e.g., '/v1'). "
                 "This may lead to compatibility issues with OpenAI-style endpoints. "
                 "Consider updating the URL to include a version prefix, "
-                "such as '/predict/v1' or '/predictwithresponsestream/v1'."
+                "such as '/predict/v1' or '/predictWithResponseStream/v1'."
             )
             # route_suffix = f"v1/{route_suffix}"
 
@@ -124,13 +124,13 @@ class AquaOpenAIMixin:
 
     def _patch_url(self) -> httpx.URL:
         """
-        Strips any suffixes from the base URL to retain only the `/predict` or `/predictwithresponsestream` path.
+        Strips any suffixes from the base URL to retain only the `/predict` or `/predictWithResponseStream` path.
 
         Returns:
             httpx.URL: The normalized base URL with the correct model deployment path.
         """
-        base_path = f"{self.base_url.path.lower().rstrip('/')}/"
-        match = re.search(r"/predict(withresponsestream)?/", base_path)
+        base_path = f"{self.base_url.path.rstrip('/')}/"
+        match = re.search(r"/predict(WithResponseStream)?/", base_path)
         if match:
             trimmed = base_path[: match.end() - 1]
             return self.base_url.copy_with(path=trimmed)
@@ -144,7 +144,7 @@ class AquaOpenAIMixin:
 
         This includes:
         - Patching headers with streaming and routing info.
-        - Normalizing the URL path to include only `/predict` or `/predictwithresponsestream`.
+        - Normalizing the URL path to include only `/predict` or `/predictWithResponseStream`.
 
         Args:
             request (httpx.Request): The outgoing HTTPX request.
@@ -176,6 +176,7 @@ class OpenAI(openai.OpenAI, AquaOpenAIMixin):
         http_client: Optional[httpx.Client] = None,
         http_client_kwargs: Optional[Dict[str, Any]] = None,
         _strict_response_validation: bool = False,
+        patch_headers: bool = False,
         **kwargs: Any,
     ) -> None:
         """
@@ -196,6 +197,7 @@ class OpenAI(openai.OpenAI, AquaOpenAIMixin):
             http_client (httpx.Client, optional): Custom HTTP client; if not provided, one will be auto-created.
             http_client_kwargs (dict[str, Any], optional): Extra kwargs for auto-creating the HTTP client.
             _strict_response_validation (bool, optional): Enable strict response validation.
+            patch_headers (bool, optional): If True, redirects the requests by modifying the headers.
             **kwargs: Additional keyword arguments passed to the parent __init__.
         """
         if http_client is None:
@@ -207,6 +209,8 @@ class OpenAI(openai.OpenAI, AquaOpenAIMixin):
             logger.debug("API key not provided; using default placeholder for OCI.")
             api_key = "OCI"
 
+        self.patch_headers = patch_headers
+
         super().__init__(
             api_key=api_key,
             organization=organization,
@@ -229,7 +233,8 @@ class OpenAI(openai.OpenAI, AquaOpenAIMixin):
         Args:
             request (httpx.Request): The outgoing HTTP request.
         """
-        self._prepare_request_common(request)
+        if self.patch_headers:
+            self._prepare_request_common(request)
 
 
 class AsyncOpenAI(openai.AsyncOpenAI, AquaOpenAIMixin):
@@ -248,6 +253,7 @@ class AsyncOpenAI(openai.AsyncOpenAI, AquaOpenAIMixin):
         http_client: Optional[httpx.Client] = None,
         http_client_kwargs: Optional[Dict[str, Any]] = None,
         _strict_response_validation: bool = False,
+        patch_headers: bool = False,
         **kwargs: Any,
     ) -> None:
         """
@@ -269,6 +275,7 @@ class AsyncOpenAI(openai.AsyncOpenAI, AquaOpenAIMixin):
             http_client (httpx.AsyncClient, optional): Custom asynchronous HTTP client; if not provided, one will be auto-created.
             http_client_kwargs (dict[str, Any], optional): Extra kwargs for auto-creating the HTTP client.
             _strict_response_validation (bool, optional): Enable strict response validation.
+            patch_headers (bool, optional): If True, redirects the requests by modifying the headers.
             **kwargs: Additional keyword arguments passed to the parent __init__.
         """
         if http_client is None:
@@ -280,6 +287,8 @@ class AsyncOpenAI(openai.AsyncOpenAI, AquaOpenAIMixin):
             logger.debug("API key not provided; using default placeholder for OCI.")
             api_key = "OCI"
 
+        self.patch_headers = patch_headers
+
         super().__init__(
             api_key=api_key,
             organization=organization,
@@ -302,4 +311,5 @@ class AsyncOpenAI(openai.AsyncOpenAI, AquaOpenAIMixin):
         Args:
             request (httpx.Request): The outgoing HTTP request.
         """
-        self._prepare_request_common(request)
+        if self.patch_headers:
+            self._prepare_request_common(request)

ads/aqua/common/entities.py

@@ -3,10 +3,10 @@
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
 import re
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from oci.data_science.models import Model
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from ads.aqua import logger
 from ads.aqua.config.utils.serializer import Serializable
@@ -80,24 +80,29 @@ class GPUShapesIndex(Serializable):
 
 class ComputeShapeSummary(Serializable):
     """
-    Represents the specifications of a compute instance's shape.
+    Represents the specifications of a compute instance shape,
+    including CPU, memory, and optional GPU characteristics.
     """
 
     core_count: Optional[int] = Field(
-        default=None, description="The number of CPU cores available."
+        default=None,
+        description="Total number of CPU cores available for the compute shape.",
     )
     memory_in_gbs: Optional[int] = Field(
-        default=None, description="The amount of memory (in GB) available."
+        default=None,
+        description="Amount of memory (in GB) available for the compute shape.",
     )
     name: Optional[str] = Field(
-        default=None, description="The name identifier of the compute shape."
+        default=None,
+        description="Full name of the compute shape, e.g., 'VM.GPU.A10.2'.",
     )
     shape_series: Optional[str] = Field(
-        default=None, description="The series or category of the compute shape."
+        default=None,
+        description="Shape family or series, e.g., 'GPU', 'Standard', etc.",
     )
     gpu_specs: Optional[GPUSpecs] = Field(
         default=None,
-        description="The GPU specifications associated with the compute shape.",
+        description="Optional GPU specifications associated with the shape.",
     )
 
     @model_validator(mode="after")
@@ -136,6 +141,47 @@ class ComputeShapeSummary(Serializable):
         return model
 
 
+class LoraModuleSpec(BaseModel):
+    """
+    Descriptor for a LoRA (Low-Rank Adaptation) module used in fine-tuning base models.
+
+    This class is used to define a single fine-tuned module that can be loaded during
+    multi-model deployment alongside a base model.
+
+    Attributes
+    ----------
+    model_id : str
+        The OCID of the fine-tuned model registered in the OCI Model Catalog.
+    model_name : Optional[str]
+        The unique name used to route inference requests to this model variant.
+    model_path : Optional[str]
+        The relative path within the artifact pointing to the LoRA adapter weights.
+    """
+
+    model_config = ConfigDict(protected_namespaces=(), extra="allow")
+
+    model_id: str = Field(
+        ...,
+        description="OCID of the fine-tuned model (must be registered in the Model Catalog).",
+    )
+    model_name: Optional[str] = Field(
+        default=None,
+        description="Name assigned to the fine-tuned model for serving (used as inference route).",
+    )
+    model_path: Optional[str] = Field(
+        default=None,
+        description="Relative path to the LoRA weights inside the model artifact.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_lora_module(cls, data: dict) -> dict:
+        """Validates that required structure exists for a LoRA module."""
+        if "model_id" not in data or not data["model_id"]:
+            raise ValueError("Missing required field: 'model_id' for fine-tuned model.")
+        return data
+
+
 class AquaMultiModelRef(Serializable):
     """
     Lightweight model descriptor used for multi-model deployment.
@@ -157,7 +203,7 @@ class AquaMultiModelRef(Serializable):
         Optional environment variables to override during deployment.
     artifact_location : Optional[str]
         Artifact path of model in the multimodel group.
-    fine_tune_weights_location : Optional[str]
+    fine_tune_weights : Optional[List[LoraModuleSpec]]
         For fine tuned models, the artifact path of the modified model weights
     """
 
@@ -166,17 +212,37 @@ class AquaMultiModelRef(Serializable):
     gpu_count: Optional[int] = Field(
         None, description="The gpu count allocation for the model."
     )
-    model_task: Optional[str] = Field(None, description="The task that model operates on. Supported tasks are in MultiModelSupportedTaskType")
+    model_task: Optional[str] = Field(
+        None,
+        description="The task that model operates on. Supported tasks are in MultiModelSupportedTaskType",
+    )
     env_var: Optional[dict] = Field(
         default_factory=dict, description="The environment variables of the model."
     )
     artifact_location: Optional[str] = Field(
         None, description="Artifact path of model in the multimodel group."
     )
-    fine_tune_weights_location: Optional[str] = Field(
-        None, description="For fine tuned models, the artifact path of the modified model weights"
+    fine_tune_weights: Optional[List[LoraModuleSpec]] = Field(
+        None,
+        description="For fine tuned models, the artifact path of the modified model weights",
     )
 
+    def all_model_ids(self) -> List[str]:
+        """
+        Returns all associated model OCIDs, including the base model and any fine-tuned models.
+
+        Returns
+        -------
+        List[str]
+            A list of all model OCIDs associated with this multi-model reference.
+        """
+        ids = {self.model_id}
+        if self.fine_tune_weights:
+            ids.update(
+                module.model_id for module in self.fine_tune_weights if module.model_id
+            )
+        return list(ids)
+
     class Config:
         extra = "ignore"
         protected_namespaces = ()

ads/aqua/common/utils.py

@@ -870,6 +870,41 @@ def get_combined_params(params1: str = None, params2: str = None) -> str:
     return " ".join(combined_params)
 
 
+def find_restricted_params(
+    default_params: Union[str, List[str]],
+    user_params: Union[str, List[str]],
+    container_family: str,
+) -> List[str]:
+    """Returns a list of restricted params that user chooses to override when creating an Aqua deployment.
+    The default parameters coming from the container index json file cannot be overridden.
+
+    Parameters
+    ----------
+    default_params:
+        Inference container parameter string with default values.
+    user_params:
+        Inference container parameter string with user provided values.
+    container_family: str
+        The image family of model deployment container runtime.
+
+    Returns
+    -------
+        A list with params keys common between params1 and params2.
+
+    """
+    restricted_params = []
+    if default_params and user_params:
+        default_params_dict = get_params_dict(default_params)
+        user_params_dict = get_params_dict(user_params)
+
+        restricted_params_set = get_restricted_params_by_container(container_family)
+        for key, _items in user_params_dict.items():
+            if key in default_params_dict or key in restricted_params_set:
+                restricted_params.append(key.lstrip("-"))
+
+    return restricted_params
+
+
 def build_params_string(params: dict) -> str:
     """Builds params string from params dict
 

ads/aqua/constants.py

@@ -55,6 +55,8 @@ SERVICE_MANAGED_CONTAINER_URI_SCHEME = "dsmc://"
 SUPPORTED_FILE_FORMATS = ["jsonl"]
 MODEL_BY_REFERENCE_OSS_PATH_KEY = "artifact_location"
 
+AQUA_CHAT_TEMPLATE_METADATA_KEY = "chat_template"
+
 CONSOLE_LINK_RESOURCE_TYPE_MAPPING = {
     "datasciencemodel": "models",
     "datasciencemodeldeployment": "model-deployments",

ads/aqua/evaluation/evaluation.py

@@ -727,10 +727,11 @@ class AquaEvaluationApp(AquaApp):
             raise AquaRuntimeError(error_message) from ex
 
         # Build the list of valid model names from custom metadata.
-        model_names = [
-            AquaMultiModelRef(**metadata).model_name
-            for metadata in multi_model_metadata
-        ]
+        model_names = []
+        for metadata in multi_model_metadata:
+            model = AquaMultiModelRef(**metadata)
+            model_names.append(model.model_name)
+            model_names.extend(ft.model_name for ft in (model.fine_tune_weights or []) if ft.model_name)
 
         # Check if the provided model name is among the valid names.
         if user_model_name not in model_names: