ads.aqua.common package

Submodules

ads.aqua.common.utils

ads.aqua.common.enums

class ads.aqua.common.enums.ConfigFolder[source]

Bases: ExtendedEnum

ARTIFACT = 'artifact'
CONFIG = 'config'
class ads.aqua.common.enums.CustomInferenceContainerTypeFamily[source]

Bases: ExtendedEnum

AQUA_TEI_CONTAINER_FAMILY = 'odsc-tei-serving'
class ads.aqua.common.enums.DataScienceResource[source]

Bases: ExtendedEnum

MODEL = 'datasciencemodel'
MODEL_DEPLOYMENT = 'datasciencemodeldeployment'
class ads.aqua.common.enums.EvaluationContainerTypeFamily[source]

Bases: ExtendedEnum

AQUA_EVALUATION_CONTAINER_FAMILY = 'odsc-llm-evaluate'
class ads.aqua.common.enums.FineTuningContainerTypeFamily[source]

Bases: ExtendedEnum

AQUA_FINETUNING_CONTAINER_FAMILY = 'odsc-llm-fine-tuning'
class ads.aqua.common.enums.HuggingFaceTags[source]

Bases: ExtendedEnum

TEXT_GENERATION_INFERENCE = 'text-generation-inference'
class ads.aqua.common.enums.InferenceContainerParamType[source]

Bases: ExtendedEnum

PARAM_TYPE_LLAMA_CPP = 'LLAMA_CPP_PARAMS'
PARAM_TYPE_TGI = 'TGI_PARAMS'
PARAM_TYPE_VLLM = 'VLLM_PARAMS'
class ads.aqua.common.enums.InferenceContainerType[source]

Bases: ExtendedEnum

CONTAINER_TYPE_LLAMA_CPP = 'llama-cpp'
CONTAINER_TYPE_TGI = 'tgi'
CONTAINER_TYPE_VLLM = 'vllm'
class ads.aqua.common.enums.InferenceContainerTypeFamily[source]

Bases: ExtendedEnum

AQUA_LLAMA_CPP_CONTAINER_FAMILY = 'odsc-llama-cpp-serving'
AQUA_TGI_CONTAINER_FAMILY = 'odsc-tgi-serving'
AQUA_VLLM_CONTAINER_FAMILY = 'odsc-vllm-serving'
AQUA_VLLM_LLAMA4_CONTAINER_FAMILY = 'odsc-vllm-serving-llama4'
AQUA_VLLM_V1_CONTAINER_FAMILY = 'odsc-vllm-serving-v1'
class ads.aqua.common.enums.ModelFormat[source]

Bases: ExtendedEnum

GGUF = 'GGUF'
SAFETENSORS = 'SAFETENSORS'
UNKNOWN = 'UNKNOWN'
class ads.aqua.common.enums.Platform[source]

Bases: ExtendedEnum

ARM_CPU = 'ARM_CPU'
NVIDIA_GPU = 'NVIDIA_GPU'
class ads.aqua.common.enums.PredictEndpoints[source]

Bases: ExtendedEnum

CHAT_COMPLETIONS_ENDPOINT = '/v1/chat/completions'
EMBEDDING_ENDPOINT = '/v1/embedding'
TEXT_COMPLETIONS_ENDPOINT = '/v1/completions'
class ads.aqua.common.enums.Resource[source]

Bases: ExtendedEnum

JOB = 'jobs'
JOBRUN = 'jobruns'
MODEL = 'models'
MODEL_DEPLOYMENT = 'modeldeployments'
MODEL_VERSION_SET = 'model-version-sets'
class ads.aqua.common.enums.RqsAdditionalDetails[source]

Bases: ExtendedEnum

CREATED_BY = 'createdBy'
DESCRIPTION = 'description'
METADATA = 'metadata'
MODEL_VERSION_SET_ID = 'modelVersionSetId'
MODEL_VERSION_SET_NAME = 'modelVersionSetName'
PROJECT_ID = 'projectId'
VERSION_LABEL = 'versionLabel'
class ads.aqua.common.enums.Tags[source]

Bases: ExtendedEnum

AQUA_EVALUATION = 'aqua_evaluation'
AQUA_EVALUATION_MODEL_ID = 'evaluation_model_id'
AQUA_FINE_TUNED_MODEL_TAG = 'aqua_fine_tuned_model'
AQUA_FINE_TUNING = 'aqua_finetuning'
AQUA_MODEL_ID_TAG = 'aqua_model_id'
AQUA_MODEL_NAME_TAG = 'aqua_model_name'
AQUA_SERVICE_MODEL_TAG = 'aqua_service_model'
AQUA_TAG = 'OCI_AQUA'
BASE_MODEL_CUSTOM = 'aqua_custom_base_model'
LICENSE = 'license'
MODEL_ARTIFACT_FILE = 'model_file'
MODEL_FORMAT = 'model_format'
MULTIMODEL_TYPE_TAG = 'aqua_multimodel'
ORGANIZATION = 'organization'
READY_TO_FINE_TUNE = 'ready_to_fine_tune'
READY_TO_IMPORT = 'ready_to_import'
TASK = 'task'
class ads.aqua.common.enums.TextEmbeddingInferenceContainerParams[source]

Bases: 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'

ads.aqua.common.entities

class ads.aqua.common.entities.AquaMultiModelRef(*, model_id: str, model_name: str | None = None, gpu_count: int | None = None, model_task: str | None = None, env_var: dict | None = <factory>, artifact_location: str | None = None, fine_tune_weights: ~typing.List[~ads.aqua.common.entities.LoraModuleSpec] | None = None)[source]

Bases: Serializable

Lightweight model descriptor used for multi-model deployment.

This class only contains essential details required to fetch complete model metadata and deploy models.

model_id

The unique identifier of the model.

Type:

str

model_name

The name of the model.

Type:

Optional[str]

gpu_count

Number of GPUs required for deployment.

Type:

Optional[int]

model_task

The task that model operates on. Supported tasks are in MultiModelSupportedTaskType

Type:

Optional[str]

env_var

Optional environment variables to override during deployment.

Type:

Optional[Dict[str, Any]]

artifact_location

Artifact path of model in the multimodel group.

Type:

Optional[str]

fine_tune_weights

For fine tuned models, the artifact path of the modified model weights

Type:

Optional[List[LoraModuleSpec]]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class Config[source]

Bases: object

extra = 'ignore'
protected_namespaces = ()
all_model_ids() → List[str][source]

Returns all associated model OCIDs, including the base model and any fine-tuned models.

Returns:

A list of all model OCIDs associated with this multi-model reference.

Return type:

List[str]

artifact_location: str | None
env_var: dict | None
fine_tune_weights: List[LoraModuleSpec] | None
gpu_count: int | None
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_id: str
model_name: str | None
model_task: str | None
class ads.aqua.common.entities.ComputeShapeSummary(*, core_count: int | None = None, memory_in_gbs: int | None = None, name: str | None = None, shape_series: str | None = None, gpu_specs: GPUSpecs | None = None)[source]

Bases: Serializable

Represents the specifications of a compute instance shape, including CPU, memory, and optional GPU characteristics.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

core_count: int | None
gpu_specs: GPUSpecs | None
memory_in_gbs: int | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None
classmethod set_gpu_specs(model: ComputeShapeSummary) → ComputeShapeSummary[source]

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:

The updated instance with gpu_specs populated if applicable.

Return type:

ComputeShapeSummary

shape_series: str | None
class ads.aqua.common.entities.ContainerPath(*, full_path: str, path: str | None = None, name: str | None = None, version: str | None = None)[source]

Bases: 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'
full_path

The complete container path string to be parsed.

Type:

str

path

The full path up to the version (e.g., ‘iad.ocir.io/ociodscdev/odsc-llm-evaluate’).

Type:

Optional[str]

name

The image name, which is the last segment of path (e.g., ‘odsc-llm-evaluate’).

Type:

Optional[str]

version

The version number following the final colon in the path (e.g., ‘0.1.2.9’).

Type:

Optional[str]

validate(values: Any) → Any[source]

Validates and parses the full_path, extracting path, name, and version.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class Config[source]

Bases: object

extra = 'ignore'
protected_namespaces = ()
full_path: str
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None
path: str | None
classmethod validate(values: Any) → Any[source]

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:

Updated values dictionary with extracted ‘path’, ‘name’, and ‘version’.

Return type:

dict

version: str | None
class ads.aqua.common.entities.ContainerSpec[source]

Bases: object

Class to hold to hold keys within the container spec.

CLI_PARM = 'cliParam'
CONTAINER_SPEC = 'containerSpec'
ENV_VARS = 'envVars'
EVALUATION_CONFIGURATION = 'evaluationConfiguration'
HEALTH_CHECK_PORT = 'healthCheckPort'
RESTRICTED_PARAMS = 'restrictedParams'
SERVER_PORT = 'serverPort'
class ads.aqua.common.entities.GPUShapesIndex(*, shapes: ~typing.Dict[str, ~ads.aqua.common.entities.GPUSpecs] = <factory>)[source]

Bases: Serializable

Represents the index of GPU shapes.

shapes(Dict[str, GPUSpecs])
Type:

A mapping of compute shape names to their GPU specifications.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

shapes: Dict[str, GPUSpecs]
class ads.aqua.common.entities.GPUSpecs(*, gpu_memory_in_gbs: int | None = None, gpu_count: int | None = None, gpu_type: str | None = None)[source]

Bases: Serializable

Represents the GPU specifications for a compute instance.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

gpu_count: int | None
gpu_memory_in_gbs: int | None
gpu_type: str | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ads.aqua.common.entities.LoraModuleSpec(*, model_id: str, model_name: str | None = None, model_path: str | None = None, **extra_data: Any)[source]

Bases: 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.

model_id

The OCID of the fine-tuned model registered in the OCI Model Catalog.

Type:

str

model_name

The unique name used to route inference requests to this model variant.

Type:

Optional[str]

model_path

The relative path within the artifact pointing to the LoRA adapter weights.

Type:

Optional[str]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_id: str
model_name: str | None
model_path: str | None
classmethod validate_lora_module(data: dict) → dict[source]

Validates that required structure exists for a LoRA module.

class ads.aqua.common.entities.ModelConfigResult(*, config: Dict[str, Any] | None = None, model_details: Model | None = None)[source]

Bases: BaseModel

Represents the result of getting the AQUA model configuration. .. attribute:: model_details

A dictionary containing model details extracted from OCI.

type:

Dict[str, Any]

config

A dictionary of the loaded configuration.

Type:

Dict[str, Any]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class Config[source]

Bases: object

arbitrary_types_allowed = True
extra = 'ignore'
protected_namespaces = ()
config: Dict[str, Any] | None
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_details: Model | None

ads.aqua.common.errors

aqua.exception

This module contains the set of Aqua exceptions.

exception ads.aqua.common.errors.AquaCLIError(reason, status=None, service_payload=None)[source]

Bases: AquaError

Exception raised when AQUA CLI encounter error.

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.

exit_code = 1
exception ads.aqua.common.errors.AquaConfigError(reason, status=404, service_payload=None)[source]

Bases: AquaError

Exception raised when config for AQUA is invalid.

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.

exit_code = 10
exception ads.aqua.common.errors.AquaError(reason: str, status: int, service_payload: dict | None = None)[source]

Bases: Exception

The base exception from which all exceptions raised by Aqua will inherit.

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.

exit_code = 1
exception ads.aqua.common.errors.AquaFileExistsError(reason, status=400, service_payload=None)[source]

Bases: AquaError, FileExistsError

Exception raised when file already exists in resource.

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.

exception ads.aqua.common.errors.AquaFileNotFoundError(reason, status=404, service_payload=None)[source]

Bases: AquaError, FileNotFoundError

Exception raised for missing target file.

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.

exception ads.aqua.common.errors.AquaMissingKeyError(reason, status=400, service_payload=None)[source]

Bases: AquaError

Exception raised when missing metadata in resource.

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.

exception ads.aqua.common.errors.AquaResourceAccessError(reason, status=404, service_payload=None)[source]

Bases: AquaError

Exception raised when file already exists in resource.

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.

exception ads.aqua.common.errors.AquaRuntimeError(reason, status=400, service_payload=None)[source]

Bases: AquaError, RuntimeError

Exception raised for generic errors at runtime.

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.

exception ads.aqua.common.errors.AquaValueError(reason, status=403, service_payload=None)[source]

Bases: AquaError, ValueError

Exception raised for unexpected values.

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.

class ads.aqua.common.errors.ExitCode[source]

Bases: ExtendedEnum

COMMON_ERROR = 1
INVALID_CONFIG = 10
SUCCESS = 0