oracle-ads 2.13.4__py3-none-any.whl → 2.13.6__py3-none-any.whl

ads/aqua/app.py

@@ -6,9 +6,11 @@ import json
 import os
 import traceback
 from dataclasses import fields
+from datetime import datetime, timedelta
 from typing import Any, Dict, Optional, Union
 
 import oci
+from cachetools import TTLCache, cached
 from oci.data_science.models import UpdateModelDetails, UpdateModelProvenanceDetails
 
 from ads import set_auth
@@ -269,6 +271,7 @@ class AquaApp:
                 logger.info(f"Artifact not found in model {model_id}.")
                 return False
 
+    @cached(cache=TTLCache(maxsize=1, ttl=timedelta(minutes=1), timer=datetime.now))
     def get_config(
         self,
         model_id: str,
@@ -337,6 +340,9 @@ class AquaApp:
         config_file_path = os.path.join(config_path, config_file_name)
         if is_path_exists(config_file_path):
             try:
+                logger.debug(
+                    f"Loading config: `{config_file_name}` from `{config_path}`"
+                )
                 config = load_config(
                     config_path,
                     config_file_name=config_file_name,

ads/aqua/client/openai_client.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python
+# Copyright (c) 2025 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+import json
+import logging
+import re
+from typing import Any, Dict, Optional
+
+import httpx
+from git import Union
+
+from ads.aqua.client.client import get_async_httpx_client, get_httpx_client
+from ads.common.extended_enum import ExtendedEnum
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT = httpx.Timeout(timeout=600, connect=5.0)
+DEFAULT_MAX_RETRIES = 2
+
+
+try:
+    import openai
+except ImportError as e:
+    raise ModuleNotFoundError(
+        "The custom OpenAI client requires the `openai-python` package. "
+        "Please install it with `pip install openai`."
+    ) from e
+
+
+class ModelDeploymentBaseEndpoint(ExtendedEnum):
+    """Supported base endpoints for model deployments."""
+
+    PREDICT = "predict"
+    PREDICT_WITH_RESPONSE_STREAM = "predictwithresponsestream"
+
+
+class AquaOpenAIMixin:
+    """
+    Mixin that provides common logic to patch HTTP request headers and URLs
+    for compatibility with the OCI Model Deployment service using the OpenAI API schema.
+    """
+
+    def _patch_route(self, original_path: str) -> str:
+        """
+        Extracts and formats the OpenAI-style route path from a full request path.
+
+        Args:
+            original_path (str): The full URL path from the incoming request.
+
+        Returns:
+            str: The normalized OpenAI-compatible route path (e.g., '/v1/chat/completions').
+        """
+        normalized_path = original_path.lower().rstrip("/")
+
+        match = re.search(r"/predict(withresponsestream)?", normalized_path)
+        if not match:
+            logger.debug("Route header cannot be resolved from path: %s", original_path)
+            return ""
+
+        route_suffix = normalized_path[match.end() :].lstrip("/")
+        if not route_suffix:
+            logger.warning(
+                "Missing OpenAI route suffix after '/predict'. "
+                "Expected something like '/v1/completions'."
+            )
+            return ""
+
+        if not route_suffix.startswith("v"):
+            logger.warning(
+                "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'."
+            )
+            # route_suffix = f"v1/{route_suffix}"
+
+        return f"/{route_suffix}"
+
+    def _patch_streaming(self, request: httpx.Request) -> None:
+        """
+        Sets the 'enable-streaming' header based on the JSON request body contents.
+
+        If the request body contains `"stream": true`, the `enable-streaming` header is set to "true".
+        Otherwise, it defaults to "false".
+
+        Args:
+            request (httpx.Request): The outgoing HTTPX request.
+        """
+        streaming_enabled = "false"
+        content_type = request.headers.get("Content-Type", "")
+
+        if "application/json" in content_type and request.content:
+            try:
+                body = (
+                    request.content.decode("utf-8")
+                    if isinstance(request.content, bytes)
+                    else request.content
+                )
+                payload = json.loads(body)
+                if payload.get("stream") is True:
+                    streaming_enabled = "true"
+            except Exception as e:
+                logger.exception(
+                    "Failed to parse request JSON body for streaming flag: %s", e
+                )
+
+        request.headers.setdefault("enable-streaming", streaming_enabled)
+        logger.debug("Patched 'enable-streaming' header: %s", streaming_enabled)
+
+    def _patch_headers(self, request: httpx.Request) -> None:
+        """
+        Patches request headers by injecting OpenAI-compatible values:
+        - `enable-streaming` for streaming-aware endpoints
+        - `route` for backend routing
+
+        Args:
+            request (httpx.Request): The outgoing HTTPX request.
+        """
+        self._patch_streaming(request)
+        route_header = self._patch_route(request.url.path)
+        request.headers.setdefault("route", route_header)
+        logger.debug("Patched 'route' header: %s", route_header)
+
+    def _patch_url(self) -> httpx.URL:
+        """
+        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)
+        if match:
+            trimmed = base_path[: match.end() - 1]
+            return self.base_url.copy_with(path=trimmed)
+
+        logger.debug("Could not determine a valid endpoint from path: %s", base_path)
+        return self.base_url
+
+    def _prepare_request_common(self, request: httpx.Request) -> None:
+        """
+        Common preparation routine for all requests.
+
+        This includes:
+        - Patching headers with streaming and routing info.
+        - Normalizing the URL path to include only `/predict` or `/predictwithresponsestream`.
+
+        Args:
+            request (httpx.Request): The outgoing HTTPX request.
+        """
+        # Patch headers
+        logger.debug("Original headers: %s", request.headers)
+        self._patch_headers(request)
+        logger.debug("Headers after patching: %s", request.headers)
+
+        # Patch URL
+        logger.debug("URL before patching: %s", request.url)
+        request.url = self._patch_url()
+        logger.debug("URL after patching: %s", request.url)
+
+
+class OpenAI(openai.OpenAI, AquaOpenAIMixin):
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        organization: Optional[str] = None,
+        project: Optional[str] = None,
+        base_url: Optional[Union[str, httpx.URL]] = None,
+        websocket_base_url: Optional[Union[str, httpx.URL]] = None,
+        timeout: Optional[Union[float, httpx.Timeout]] = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Dict[str, str]] = None,
+        default_query: Optional[Dict[str, object]] = None,
+        http_client: Optional[httpx.Client] = None,
+        http_client_kwargs: Optional[Dict[str, Any]] = None,
+        _strict_response_validation: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Construct a new synchronous OpenAI client instance.
+
+        If no http_client is provided, one will be automatically created using ads.aqua.get_httpx_client().
+
+        Args:
+            api_key (str, optional): API key for authentication. Defaults to env variable OPENAI_API_KEY.
+            organization (str, optional): Organization ID. Defaults to env variable OPENAI_ORG_ID.
+            project (str, optional): Project ID. Defaults to env variable OPENAI_PROJECT_ID.
+            base_url (str | httpx.URL, optional): Base URL for the API.
+            websocket_base_url (str | httpx.URL, optional): Base URL for WebSocket connections.
+            timeout (float | httpx.Timeout, optional): Timeout for API requests.
+            max_retries (int, optional): Maximum number of retries for API requests.
+            default_headers (dict[str, str], optional): Additional headers.
+            default_query (dict[str, object], optional): Additional query parameters.
+            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.
+            **kwargs: Additional keyword arguments passed to the parent __init__.
+        """
+        if http_client is None:
+            logger.debug(
+                "No http_client provided; auto-creating one using ads.aqua.get_httpx_client()"
+            )
+            http_client = get_httpx_client(**(http_client_kwargs or {}))
+        if not api_key:
+            logger.debug("API key not provided; using default placeholder for OCI.")
+            api_key = "OCI"
+
+        super().__init__(
+            api_key=api_key,
+            organization=organization,
+            project=project,
+            base_url=base_url,
+            websocket_base_url=websocket_base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+            http_client=http_client,
+            _strict_response_validation=_strict_response_validation,
+            **kwargs,
+        )
+
+    def _prepare_request(self, request: httpx.Request) -> None:
+        """
+        Prepare the synchronous HTTP request by applying common modifications.
+
+        Args:
+            request (httpx.Request): The outgoing HTTP request.
+        """
+        self._prepare_request_common(request)
+
+
+class AsyncOpenAI(openai.AsyncOpenAI, AquaOpenAIMixin):
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        organization: Optional[str] = None,
+        project: Optional[str] = None,
+        base_url: Optional[Union[str, httpx.URL]] = None,
+        websocket_base_url: Optional[Union[str, httpx.URL]] = None,
+        timeout: Optional[Union[float, httpx.Timeout]] = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Dict[str, str]] = None,
+        default_query: Optional[Dict[str, object]] = None,
+        http_client: Optional[httpx.Client] = None,
+        http_client_kwargs: Optional[Dict[str, Any]] = None,
+        _strict_response_validation: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Construct a new asynchronous AsyncOpenAI client instance.
+
+        If no http_client is provided, one will be automatically created using
+        ads.aqua.get_async_httpx_client().
+
+        Args:
+            api_key (str, optional): API key for authentication. Defaults to env variable OPENAI_API_KEY.
+            organization (str, optional): Organization ID.
+            project (str, optional): Project ID.
+            base_url (str | httpx.URL, optional): Base URL for the API.
+            websocket_base_url (str | httpx.URL, optional): Base URL for WebSocket connections.
+            timeout (float | httpx.Timeout, optional): Timeout for API requests.
+            max_retries (int, optional): Maximum number of retries for API requests.
+            default_headers (dict[str, str], optional): Additional headers.
+            default_query (dict[str, object], optional): Additional query parameters.
+            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.
+            **kwargs: Additional keyword arguments passed to the parent __init__.
+        """
+        if http_client is None:
+            logger.debug(
+                "No async http_client provided; auto-creating one using ads.aqua.get_async_httpx_client()"
+            )
+            http_client = get_async_httpx_client(**(http_client_kwargs or {}))
+        if not api_key:
+            logger.debug("API key not provided; using default placeholder for OCI.")
+            api_key = "OCI"
+
+        super().__init__(
+            api_key=api_key,
+            organization=organization,
+            project=project,
+            base_url=base_url,
+            websocket_base_url=websocket_base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+            http_client=http_client,
+            _strict_response_validation=_strict_response_validation,
+            **kwargs,
+        )
+
+    async def _prepare_request(self, request: httpx.Request) -> None:
+        """
+        Asynchronously prepare the HTTP request by applying common modifications.
+
+        Args:
+            request (httpx.Request): The outgoing HTTP request.
+        """
+        self._prepare_request_common(request)

ads/aqua/common/entities.py

@@ -2,10 +2,14 @@
 # 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 re
 from typing import Any, Dict, Optional
 
 from oci.data_science.models import Model
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
+
+from ads.aqua import logger
+from ads.aqua.config.utils.serializer import Serializable
 
 
 class ContainerSpec:
@@ -25,7 +29,6 @@ class ContainerSpec:
 class ModelConfigResult(BaseModel):
     """
     Represents the result of getting the AQUA model configuration.
-
     Attributes:
         model_details (Dict[str, Any]): A dictionary containing model details extracted from OCI.
         config (Dict[str, Any]): A dictionary of the loaded configuration.
@@ -42,3 +45,222 @@ class ModelConfigResult(BaseModel):
         extra = "ignore"
         arbitrary_types_allowed = True
         protected_namespaces = ()
+
+
+class GPUSpecs(Serializable):
+    """
+    Represents the GPU specifications for a compute instance.
+    """
+
+    gpu_memory_in_gbs: Optional[int] = Field(
+        default=None, description="The amount of GPU memory available (in GB)."
+    )
+    gpu_count: Optional[int] = Field(
+        default=None, description="The number of GPUs available."
+    )
+    gpu_type: Optional[str] = Field(
+        default=None, description="The type of GPU (e.g., 'V100, A100, H100')."
+    )
+
+
+class GPUShapesIndex(Serializable):
+    """
+    Represents the index of GPU shapes.
+
+    Attributes
+    ----------
+    shapes (Dict[str, GPUSpecs]): A mapping of compute shape names to their GPU specifications.
+    """
+
+    shapes: Dict[str, GPUSpecs] = Field(
+        default_factory=dict,
+        description="Mapping of shape names to GPU specifications.",
+    )
+
+
+class ComputeShapeSummary(Serializable):
+    """
+    Represents the specifications of a compute instance's shape.
+    """
+
+    core_count: Optional[int] = Field(
+        default=None, description="The number of CPU cores available."
+    )
+    memory_in_gbs: Optional[int] = Field(
+        default=None, description="The amount of memory (in GB) available."
+    )
+    name: Optional[str] = Field(
+        default=None, description="The name identifier of the compute shape."
+    )
+    shape_series: Optional[str] = Field(
+        default=None, description="The series or category of the compute shape."
+    )
+    gpu_specs: Optional[GPUSpecs] = Field(
+        default=None,
+        description="The GPU specifications associated with the compute shape.",
+    )
+
+    @model_validator(mode="after")
+    @classmethod
+    def set_gpu_specs(cls, model: "ComputeShapeSummary") -> "ComputeShapeSummary":
+        """
+        Validates and populates GPU specifications if the shape_series indicates a GPU-based shape.
+
+        - If the shape_series contains "GPU", the validator first checks if the shape name exists
+          in the GPU_SPECS dictionary. If found, it creates a GPUSpecs instance with the corresponding data.
+        - If the shape is not found in the GPU_SPECS, it attempts to extract the GPU count from the shape name
+          using a regex pattern (looking for a number following a dot at the end of the name).
+
+        The information about shapes is taken from: https://docs.oracle.com/en-us/iaas/data-science/using/supported-shapes.htm
+
+        Returns:
+            ComputeShapeSummary: The updated instance with gpu_specs populated if applicable.
+        """
+        try:
+            if (
+                model.shape_series
+                and "GPU" in model.shape_series.upper()
+                and model.name
+                and not model.gpu_specs
+            ):
+                # Try to extract gpu_count from the shape name using a regex (e.g., "VM.GPU3.2" -> gpu_count=2)
+                match = re.search(r"\.(\d+)$", model.name)
+                if match:
+                    gpu_count = int(match.group(1))
+                    model.gpu_specs = GPUSpecs(gpu_count=gpu_count)
+        except Exception as err:
+            logger.debug(
+                f"Error occurred in attempt to extract GPU specification for the f{model.name}. "
+                f"Details: {err}"
+            )
+        return model
+
+
+class AquaMultiModelRef(Serializable):
+    """
+    Lightweight model descriptor used for multi-model deployment.
+
+    This class only contains essential details
+    required to fetch complete model metadata and deploy models.
+
+    Attributes
+    ----------
+    model_id : str
+        The unique identifier of the model.
+    model_name : Optional[str]
+        The name of the model.
+    gpu_count : Optional[int]
+        Number of GPUs required for deployment.
+    env_var : Optional[Dict[str, Any]]
+        Optional environment variables to override during deployment.
+    artifact_location : Optional[str]
+        Artifact path of model in the multimodel group.
+    """
+
+    model_id: str = Field(..., description="The model OCID to deploy.")
+    model_name: Optional[str] = Field(None, description="The name of model.")
+    gpu_count: Optional[int] = Field(
+        None, description="The gpu count allocation for the model."
+    )
+    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."
+    )
+
+    class Config:
+        extra = "ignore"
+        protected_namespaces = ()
+
+
+class ContainerPath(Serializable):
+    """
+    Represents a parsed container path, extracting the path, name, and version.
+
+    This model is designed to parse a container path string of the format
+    '<image_path>:<version>'. It extracts the following components:
+    - `path`: The full path up to the version.
+    - `name`: The last segment of the path, representing the image name.
+    - `version`: The version number following the final colon.
+
+    Example Usage:
+    --------------
+    >>> container = ContainerPath(full_path="iad.ocir.io/ociodscdev/odsc-llm-evaluate:0.1.2.9")
+    >>> container.path
+    'iad.ocir.io/ociodscdev/odsc-llm-evaluate'
+    >>> container.name
+    'odsc-llm-evaluate'
+    >>> container.version
+    '0.1.2.9'
+
+    >>> container = ContainerPath(full_path="custom-scheme://path/to/versioned-model:2.5.1")
+    >>> container.path
+    'custom-scheme://path/to/versioned-model'
+    >>> container.name
+    'versioned-model'
+    >>> container.version
+    '2.5.1'
+
+    Attributes
+    ----------
+    full_path : str
+        The complete container path string to be parsed.
+    path : Optional[str]
+        The full path up to the version (e.g., 'iad.ocir.io/ociodscdev/odsc-llm-evaluate').
+    name : Optional[str]
+        The image name, which is the last segment of `path` (e.g., 'odsc-llm-evaluate').
+    version : Optional[str]
+        The version number following the final colon in the path (e.g., '0.1.2.9').
+
+    Methods
+    -------
+    validate(values: Any) -> Any
+        Validates and parses the `full_path`, extracting `path`, `name`, and `version`.
+    """
+
+    full_path: str
+    path: Optional[str] = None
+    name: Optional[str] = None
+    version: Optional[str] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate(cls, values: Any) -> Any:
+        """
+        Validates and parses the full container path, extracting the image path, image name, and version.
+
+        Parameters
+        ----------
+        values : dict
+            The dictionary of values being validated, containing 'full_path'.
+
+        Returns
+        -------
+        dict
+            Updated values dictionary with extracted 'path', 'name', and 'version'.
+        """
+        full_path = values.get("full_path", "").strip()
+
+        # Regex to parse <image_path>:<version>
+        match = re.match(
+            r"^(?P<image_path>.+?)(?::(?P<image_version>[\w\.]+))?$", full_path
+        )
+
+        if not match:
+            raise ValueError(
+                "Invalid container path format. Expected format: '<image_path>:<version>'"
+            )
+
+        # Extract image_path and version
+        values["path"] = match.group("image_path")
+        values["version"] = match.group("image_version")
+
+        # Extract image_name as the last segment of image_path
+        values["name"] = values["path"].split("/")[-1]
+
+        return values
+
+    class Config:
+        extra = "ignore"
+        protected_namespaces = ()

ads/aqua/common/enums.py

@@ -2,6 +2,8 @@
 # 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 Dict, List
+
 from ads.common.extended_enum import ExtendedEnum
 
 
@@ -25,6 +27,7 @@ class Tags(ExtendedEnum):
     AQUA_TAG = "OCI_AQUA"
     AQUA_SERVICE_MODEL_TAG = "aqua_service_model"
     AQUA_FINE_TUNED_MODEL_TAG = "aqua_fine_tuned_model"
+    AQUA_MODEL_ID_TAG = "aqua_model_id"
     AQUA_MODEL_NAME_TAG = "aqua_model_name"
     AQUA_EVALUATION = "aqua_evaluation"
     AQUA_FINE_TUNING = "aqua_finetuning"
@@ -34,6 +37,7 @@ class Tags(ExtendedEnum):
     AQUA_EVALUATION_MODEL_ID = "evaluation_model_id"
     MODEL_FORMAT = "model_format"
     MODEL_ARTIFACT_FILE = "model_file"
+    MULTIMODEL_TYPE_TAG = "aqua_multimodel"
 
 
 class InferenceContainerType(ExtendedEnum):
@@ -44,6 +48,7 @@ class InferenceContainerType(ExtendedEnum):
 
 class InferenceContainerTypeFamily(ExtendedEnum):
     AQUA_VLLM_CONTAINER_FAMILY = "odsc-vllm-serving"
+    AQUA_VLLM_V1_CONTAINER_FAMILY = "odsc-vllm-serving-v1"
     AQUA_TGI_CONTAINER_FAMILY = "odsc-tgi-serving"
     AQUA_LLAMA_CPP_CONTAINER_FAMILY = "odsc-llama-cpp-serving"
 
@@ -103,3 +108,15 @@ class ModelFormat(ExtendedEnum):
 class Platform(ExtendedEnum):
     ARM_CPU = "ARM_CPU"
     NVIDIA_GPU = "NVIDIA_GPU"
+
+
+# This dictionary defines compatibility groups for container families.
+# The structure is:
+#   - Key: The preferred container family to use when multiple compatible families are selected.
+#   - Value: A list of all compatible families (including the preferred one).
+CONTAINER_FAMILY_COMPATIBILITY: Dict[str, List[str]] = {
+    InferenceContainerTypeFamily.AQUA_VLLM_V1_CONTAINER_FAMILY: [
+        InferenceContainerTypeFamily.AQUA_VLLM_V1_CONTAINER_FAMILY,
+        InferenceContainerTypeFamily.AQUA_VLLM_CONTAINER_FAMILY,
+    ],
+}