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_OPENAI_CONTAINER_FAMILY = 'odsc-vllm-serving-openai'¶
- 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'¶
- FORECAST = 'v1/forecast'¶
- RESPONSES = '/v1/responses'¶
- 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_TUNE_MODEL_VERSION = 'fine_tune_model_version'¶
- 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_DEPLOY_PREDICT_ENDPOINT = 'model_deploy_predict_endpoint'¶
- 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'¶
- STACKED_MODEL_TYPE_TAG = 'aqua_stacked_model'¶
- TASK = 'task'¶
- class ads.aqua.common.enums.TextEmbeddingInferenceContainerParams[source]¶
Bases:
ExtendedEnumContains 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.AquaComputeTarget(*, id: str | None = None, name: str | None = None, compartment_id: str | None = None, description: str | None = None, lifecycle_state: str | None = None, lifecycle_details: str | None = None, compute_configuration_details: ~ads.aqua.common.entities.ComputeConfigurationDetails | None = <factory>)[source]¶
Bases:
SerializableRepresents the specification of Aqua compute target.
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.
- compute_configuration_details: ComputeConfigurationDetails | None¶
- classmethod from_oci(oci_compute_target) Self[source]¶
Converts oci.data_science.models.ComputeTarget to AquaComputeTarget.
- model_config: ClassVar[ConfigDict] = {}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class ads.aqua.common.entities.AquaComputeTargetSummary(*, id: str | None = None, name: str | None = None, compartment_id: str | None = None, lifecycle_state: str | None = None, freeform_tags: Dict | None = None, defined_tags: Dict | None = None)[source]¶
Bases:
SerializableRepresents the specification of compute target.
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.
- classmethod from_oci_summary(oci_compute_target) Self[source]¶
Converts oci.data_science.models.ComputeTargetSummary to AquaComputeTargetSummary.
- model_config: ClassVar[ConfigDict] = {}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- 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>, params: dict | None = None, artifact_location: str | None = None, fine_tune_weights: ~typing.List[~ads.aqua.common.entities.LoraModuleSpec] | None = None, **extra_data: ~typing.Any)[source]¶
Bases:
SerializableLightweight model descriptor used for multi-model deployment.
This class holds essential details required to fetch model metadata and deploy individual models as part of a multi-model deployment group.
- gpu_count¶
Number of GPUs required to allocate for this model during deployment.
- Type:
Optional[int]
- model_task¶
The machine learning task this model performs (e.g., text-generation, summarization). Supported values are listed in MultiModelSupportedTaskType.
- Type:
Optional[str]
- env_var¶
Optional dictionary of environment variables to inject into the runtime environment of the model container.
- Type:
Optional[Dict[str, Any]]
- params¶
Optional dictionary of container-specific inference parameters to override. These are typically framework-level flags required by the runtime backend. For example, in vLLM containers, valid params may include: –tensor-parallel-size, –enforce-eager, –max-model-len, etc.
- Type:
Optional[Dict[str, Any]]
- artifact_location¶
Relative path or URI of the model artifact inside the multi-model group folder.
- Type:
Optional[str]
- fine_tune_weights¶
List of fine-tuned weight artifacts (e.g., LoRA modules) associated with this model.
- 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.
- all_model_ids() List[str][source]¶
Returns all model OCIDs associated with this reference, including fine-tuned weights.
- Returns:
A list containing the base model OCID and any fine-tuned module OCIDs.
- Return type:
List[str]
- classmethod extract_params_from_env_var(values: Dict[str, Any]) Dict[str, Any][source]¶
A model-level validator that extracts PARAMS from the env_var dictionary and injects them into the params field as a dictionary.
This is useful for backward compatibility where users pass CLI-style parameters via environment variables, e.g.: env_var = { “PARAMS”: “–max-model-len 65536 –enable-streaming” }
If params is already set, values from PARAMS in env_var are added only if they do not override existing keys.
- fine_tune_weights: List[LoraModuleSpec] | None¶
- model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'protected_namespaces': ()}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class ads.aqua.common.entities.ComputeConfigurationDetails(*, compute_type: str | None = None, instance_configuration: ~ads.aqua.common.entities.InstanceConfiguration | None = <factory>)[source]¶
Bases:
SerializableRepresents the specification of compute configuration of compute target.
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.
- instance_configuration: InstanceConfiguration | None¶
- model_config: ClassVar[ConfigDict] = {}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class ads.aqua.common.entities.ComputeRank(*, cost: int | None = None, performance: int | None = None)[source]¶
Bases:
SerializableRepresents the cost and performance rankings for a specific compute shape. These rankings help compare different shapes based on their relative pricing and computational capabilities.
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].
- class ads.aqua.common.entities.ComputeShapeSummary(*, available: bool | None = False, 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:
SerializableRepresents a compute shape’s specification including CPU, memory, and (if applicable) GPU configuration.
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].
- classmethod populate_gpu_specs(model: ComputeShapeSummary) ComputeShapeSummary[source]¶
Attempts to populate GPU specs if the shape is GPU-based and no GPU specs are explicitly set.
Logic: - If shape_series includes ‘GPU’ and gpu_specs is None:
Tries to parse the shape name to extract GPU count (e.g., from ‘VM.GPU.A10.2’).
Fallback is based on suffix numeric group (e.g., ‘.2’ → gpu_count=2).
If extraction fails, logs debug-level error but does not raise.
- Returns:
The updated model instance.
- Return type:
- class ads.aqua.common.entities.ComputeTargetDetails(*, compute_target_id: str | None, gpu_count: int | None, ocpus: float | None, memory_in_gbs: float | None)[source]¶
Bases:
SerializableRepresents the specification of compute target details for creating Aqua deployment.
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].
- class ads.aqua.common.entities.ContainerPath(*, full_path: str, path: str | None = None, name: str | None = None, version: str | None = None)[source]¶
Bases:
SerializableRepresents 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'
- 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.
- model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'protected_namespaces': ()}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class ads.aqua.common.entities.ContainerSpec[source]¶
Bases:
objectClass 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:
SerializableRepresents 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].
- class ads.aqua.common.entities.GPUSpecs(*, gpu_count: int | None = None, gpu_memory_in_gbs: int | None = None, gpu_type: str | None = None, quantization: ~typing.List[str] | None = <factory>, cpu_count: int | None = None, cpu_memory_in_gbs: int | None = None, ranking: ~ads.aqua.common.entities.ComputeRank | None = None)[source]¶
Bases:
SerializableRepresents the specifications and capabilities of a GPU-enabled compute shape. Includes details about GPU and CPU resources, supported quantization formats, and relative rankings for cost and performance.
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].
- ranking: ComputeRank | None¶
- class ads.aqua.common.entities.InstanceConfiguration(*, instance_shape: str | None = None, capacity_reservation_id: str | None = None)[source]¶
Bases:
SerializableRepresents the specification of instance shape of compute target.
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].
- class ads.aqua.common.entities.LoraModuleSpec(*, model_id: str, model_name: str | None = None, model_path: str | None = None, **extra_data: Any)[source]¶
Bases:
BaseModelDescriptor 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_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].
- class ads.aqua.common.entities.ModelConfigResult(*, config: Dict[str, Any] | None = None, model_details: Model | None = None)[source]¶
Bases:
BaseModelRepresents the result of getting the AQUA model configuration. .. attribute:: model_details
A dictionary containing model details extracted from OCI.
- 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 = ()¶
- 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].
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:
AquaErrorException raised when AQUA CLI encounter error.
Initializes an AquaError.
- Parameters:
- exit_code = 1¶
- exception ads.aqua.common.errors.AquaConfigError(reason, status=404, service_payload=None)[source]¶
Bases:
AquaErrorException raised when config for AQUA is invalid.
Initializes an AquaError.
- Parameters:
- exit_code = 10¶
- exception ads.aqua.common.errors.AquaError(reason: str, status: int, service_payload: dict | None = None)[source]¶
Bases:
ExceptionThe base exception from which all exceptions raised by Aqua will inherit.
Initializes an AquaError.
- Parameters:
- exit_code = 1¶
- exception ads.aqua.common.errors.AquaFileExistsError(reason, status=400, service_payload=None)[source]¶
Bases:
AquaError,FileExistsErrorException raised when file already exists in resource.
Initializes an AquaError.
- exception ads.aqua.common.errors.AquaFileNotFoundError(reason, status=404, service_payload=None)[source]¶
Bases:
AquaError,FileNotFoundErrorException raised for missing target file.
Initializes an AquaError.
- exception ads.aqua.common.errors.AquaMissingKeyError(reason, status=400, service_payload=None)[source]¶
Bases:
AquaErrorException raised when missing metadata in resource.
Initializes an AquaError.
- exception ads.aqua.common.errors.AquaRecommendationError(reason, status=400, service_payload=None)[source]¶
Bases:
AquaErrorException raised for models incompatible with shape recommendation tool.
Initializes an AquaError.
- exception ads.aqua.common.errors.AquaResourceAccessError(reason, status=404, service_payload=None)[source]¶
Bases:
AquaErrorException raised when file already exists in resource.
Initializes an AquaError.
- exception ads.aqua.common.errors.AquaRuntimeError(reason, status=400, service_payload=None)[source]¶
Bases:
AquaError,RuntimeErrorException raised for generic errors at runtime.
Initializes an AquaError.
- exception ads.aqua.common.errors.AquaValueError(reason, status=403, service_payload=None)[source]¶
Bases:
AquaError,ValueErrorException raised for unexpected values.
Initializes an AquaError.