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

ads/aqua/common/entities.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+import re
+from typing import Any, Dict, Optional
+
+from oci.data_science.models import Model
+from pydantic import BaseModel, Field, model_validator
+
+from ads.aqua import logger
+from ads.aqua.config.utils.serializer import Serializable
+
+
+class ContainerSpec:
+    """
+    Class to hold to hold keys within the container spec.
+    """
+
+    CONTAINER_SPEC = "containerSpec"
+    CLI_PARM = "cliParam"
+    SERVER_PORT = "serverPort"
+    HEALTH_CHECK_PORT = "healthCheckPort"
+    ENV_VARS = "envVars"
+    RESTRICTED_PARAMS = "restrictedParams"
+    EVALUATION_CONFIGURATION = "evaluationConfiguration"
+
+
+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.
+    """
+
+    config: Optional[Dict[str, Any]] = Field(
+        None, description="Loaded configuration dictionary."
+    )
+    model_details: Optional[Model] = Field(
+        None, description="Details of the model from OCI."
+    )
+
+    class Config:
+        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.
+    model_task : Optional[str]
+        The task that model operates on. Supported tasks are in MultiModelSupportedTaskType
+    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.
+    fine_tune_weights_location : Optional[str]
+        For fine tuned models, the artifact path of the modified model weights
+    """
+
+    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."
+    )
+    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"
+    )
+
+    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

@@ -0,0 +1,134 @@
+#!/usr/bin/env python
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+from typing import Dict, List
+
+from ads.common.extended_enum import ExtendedEnum
+
+
+class DataScienceResource(ExtendedEnum):
+    MODEL_DEPLOYMENT = "datasciencemodeldeployment"
+    MODEL = "datasciencemodel"
+
+
+class Resource(ExtendedEnum):
+    JOB = "jobs"
+    JOBRUN = "jobruns"
+    MODEL = "models"
+    MODEL_DEPLOYMENT = "modeldeployments"
+    MODEL_VERSION_SET = "model-version-sets"
+
+
+class PredictEndpoints(ExtendedEnum):
+    CHAT_COMPLETIONS_ENDPOINT = "/v1/chat/completions"
+    TEXT_COMPLETIONS_ENDPOINT = "/v1/completions"
+    EMBEDDING_ENDPOINT = "/v1/embedding"
+
+
+class Tags(ExtendedEnum):
+    TASK = "task"
+    LICENSE = "license"
+    ORGANIZATION = "organization"
+    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"
+    READY_TO_FINE_TUNE = "ready_to_fine_tune"
+    READY_TO_IMPORT = "ready_to_import"
+    BASE_MODEL_CUSTOM = "aqua_custom_base_model"
+    AQUA_EVALUATION_MODEL_ID = "evaluation_model_id"
+    MODEL_FORMAT = "model_format"
+    MODEL_ARTIFACT_FILE = "model_file"
+    MULTIMODEL_TYPE_TAG = "aqua_multimodel"
+
+
+class InferenceContainerType(ExtendedEnum):
+    CONTAINER_TYPE_VLLM = "vllm"
+    CONTAINER_TYPE_TGI = "tgi"
+    CONTAINER_TYPE_LLAMA_CPP = "llama-cpp"
+
+
+class InferenceContainerTypeFamily(ExtendedEnum):
+    AQUA_VLLM_CONTAINER_FAMILY = "odsc-vllm-serving"
+    AQUA_VLLM_V1_CONTAINER_FAMILY = "odsc-vllm-serving-v1"
+    AQUA_VLLM_LLAMA4_CONTAINER_FAMILY = "odsc-vllm-serving-llama4"
+    AQUA_TGI_CONTAINER_FAMILY = "odsc-tgi-serving"
+    AQUA_LLAMA_CPP_CONTAINER_FAMILY = "odsc-llama-cpp-serving"
+
+
+class CustomInferenceContainerTypeFamily(ExtendedEnum):
+    AQUA_TEI_CONTAINER_FAMILY = "odsc-tei-serving"
+
+
+class InferenceContainerParamType(ExtendedEnum):
+    PARAM_TYPE_VLLM = "VLLM_PARAMS"
+    PARAM_TYPE_TGI = "TGI_PARAMS"
+    PARAM_TYPE_LLAMA_CPP = "LLAMA_CPP_PARAMS"
+
+
+class EvaluationContainerTypeFamily(ExtendedEnum):
+    AQUA_EVALUATION_CONTAINER_FAMILY = "odsc-llm-evaluate"
+
+
+class FineTuningContainerTypeFamily(ExtendedEnum):
+    AQUA_FINETUNING_CONTAINER_FAMILY = "odsc-llm-fine-tuning"
+
+
+class HuggingFaceTags(ExtendedEnum):
+    TEXT_GENERATION_INFERENCE = "text-generation-inference"
+
+
+class RqsAdditionalDetails(ExtendedEnum):
+    METADATA = "metadata"
+    CREATED_BY = "createdBy"
+    DESCRIPTION = "description"
+    MODEL_VERSION_SET_ID = "modelVersionSetId"
+    MODEL_VERSION_SET_NAME = "modelVersionSetName"
+    PROJECT_ID = "projectId"
+    VERSION_LABEL = "versionLabel"
+
+
+class TextEmbeddingInferenceContainerParams(ExtendedEnum):
+    """Contains a subset of params that are required for enabling model deployment in OCI Data Science. More options
+    are available at https://huggingface.co/docs/text-embeddings-inference/en/cli_arguments
+    """
+
+    MODEL_ID = "model-id"
+    PORT = "port"
+
+
+class ConfigFolder(ExtendedEnum):
+    CONFIG = "config"
+    ARTIFACT = "artifact"
+
+
+class ModelFormat(ExtendedEnum):
+    GGUF = "GGUF"
+    SAFETENSORS = "SAFETENSORS"
+    UNKNOWN = "UNKNOWN"
+
+
+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,
+    ],
+    InferenceContainerTypeFamily.AQUA_VLLM_LLAMA4_CONTAINER_FAMILY: [
+        InferenceContainerTypeFamily.AQUA_VLLM_LLAMA4_CONTAINER_FAMILY,
+        InferenceContainerTypeFamily.AQUA_VLLM_V1_CONTAINER_FAMILY,
+        InferenceContainerTypeFamily.AQUA_VLLM_CONTAINER_FAMILY,
+    ],
+}

ads/aqua/common/errors.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""
+aqua.exception
+~~~~~~~~~~~~~~
+
+This module contains the set of Aqua exceptions.
+"""
+
+from ads.common.extended_enum import ExtendedEnum
+
+
+class ExitCode(ExtendedEnum):
+    SUCCESS = 0
+    COMMON_ERROR = 1
+    INVALID_CONFIG = 10
+
+
+class AquaError(Exception):
+    """AquaError
+
+    The base exception from which all exceptions raised by Aqua
+    will inherit.
+    """
+
+    exit_code = 1
+
+    def __init__(
+        self,
+        reason: str,
+        status: int,
+        service_payload: dict = None,
+    ):
+        """Initializes an AquaError.
+
+        Parameters
+        ----------
+        reason: str
+            User friendly error message.
+        status: int
+            Http status code that are going to raise.
+        service_payload: dict
+            Payload to contain more details related to the error.
+        """
+        self.service_payload = service_payload or {}
+        self.status = status
+        self.reason = reason
+
+
+class AquaValueError(AquaError, ValueError):
+    """Exception raised for unexpected values."""
+
+    def __init__(self, reason, status=403, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaFileNotFoundError(AquaError, FileNotFoundError):
+    """Exception raised for missing target file."""
+
+    def __init__(self, reason, status=404, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaRuntimeError(AquaError, RuntimeError):
+    """Exception raised for generic errors at runtime."""
+
+    def __init__(self, reason, status=400, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaMissingKeyError(AquaError):
+    """Exception raised when missing metadata in resource."""
+
+    def __init__(self, reason, status=400, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaFileExistsError(AquaError, FileExistsError):
+    """Exception raised when file already exists in resource."""
+
+    def __init__(self, reason, status=400, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaResourceAccessError(AquaError):
+    """Exception raised when file already exists in resource."""
+
+    def __init__(self, reason, status=404, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaConfigError(AquaError):
+    """Exception raised when config for AQUA is invalid."""
+
+    exit_code = ExitCode.INVALID_CONFIG
+
+    def __init__(self, reason, status=404, service_payload=None):
+        super().__init__(reason, status, service_payload)
+
+
+class AquaCLIError(AquaError):
+    """Exception raised when AQUA CLI encounter error."""
+
+    exit_code = ExitCode.COMMON_ERROR
+
+    def __init__(self, reason, status=None, service_payload=None):
+        super().__init__(reason, status, service_payload)