oracle-ads 2.11.16__py3-none-any.whl → 2.11.17__py3-none-any.whl

ads/aqua/app.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
 # Copyright (c) 2024 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
@@ -175,7 +174,7 @@ class AquaApp:
                         f"Invalid model version set name. Please provide a model version set with `{tag}` in tags."
                     )
 
-            except:
+            except Exception:
                 logger.debug(
                     f"Model version set {model_version_set_name} doesn't exist. "
                     "Creating new model version set."
@@ -254,7 +253,7 @@ class AquaApp:
 
         try:
             response = self.ds_client.head_model_artifact(model_id=model_id, **kwargs)
-            return True if response.status == 200 else False
+            return response.status == 200
         except oci.exceptions.ServiceError as ex:
             if ex.status == 404:
                 logger.info(f"Artifact not found in model {model_id}.")
@@ -302,7 +301,7 @@ class AquaApp:
                 config_path,
                 config_file_name=config_file_name,
             )
-        except:
+        except Exception:
             # todo: temp fix for issue related to config load for byom models, update logic to choose the right path
             try:
                 config_path = f"{artifact_path.rstrip('/')}/config/"
@@ -310,7 +309,7 @@ class AquaApp:
                     config_path,
                     config_file_name=config_file_name,
                 )
-            except:
+            except Exception:
                 pass
 
         if not config:
@@ -343,7 +342,7 @@ class CLIBuilderMixin:
         params = [
             f"--{field.name} {getattr(self,field.name)}"
             for field in fields(self.__class__)
-            if getattr(self, field.name)
+            if getattr(self, field.name) is not None
         ]
         cmd = f"{cmd} {' '.join(params)}"
         return cmd

ads/aqua/common/enums.py

@@ -39,6 +39,7 @@ class Tags(str, metaclass=ExtendedEnumMeta):
     BASE_MODEL_CUSTOM = "aqua_custom_base_model"
     AQUA_EVALUATION_MODEL_ID = "evaluation_model_id"
     MODEL_FORMAT = "model_format"
+    MODEL_ARTIFACT_FILE = "model_file"
 
 
 class InferenceContainerType(str, metaclass=ExtendedEnumMeta):
@@ -59,6 +60,14 @@ class InferenceContainerParamType(str, metaclass=ExtendedEnumMeta):
     PARAM_TYPE_LLAMA_CPP = "LLAMA_CPP_PARAMS"
 
 
+class EvaluationContainerTypeFamily(str, metaclass=ExtendedEnumMeta):
+    AQUA_EVALUATION_CONTAINER_FAMILY = "odsc-llm-evaluate"
+
+
+class FineTuningContainerTypeFamily(str, metaclass=ExtendedEnumMeta):
+    AQUA_FINETUNING_CONTAINER_FAMILY = "odsc-llm-fine-tuning"
+
+
 class HuggingFaceTags(str, metaclass=ExtendedEnumMeta):
     TEXT_GENERATION_INFERENCE = "text-generation-inference"
 

ads/aqua/common/utils.py

@@ -10,6 +10,8 @@ import logging
 import os
 import random
 import re
+import shlex
+import subprocess
 from datetime import datetime, timedelta
 from functools import wraps
 from pathlib import Path
@@ -19,6 +21,13 @@ from typing import List, Union
 import fsspec
 import oci
 from cachetools import TTLCache, cached
+from huggingface_hub.hf_api import HfApi, ModelInfo
+from huggingface_hub.utils import (
+    GatedRepoError,
+    HfHubHTTPError,
+    RepositoryNotFoundError,
+    RevisionNotFoundError,
+)
 from oci.data_science.models import JobRun, Model
 from oci.object_storage.models import ObjectSummary
 
@@ -37,6 +46,7 @@ from ads.aqua.constants import (
     COMPARTMENT_MAPPING_KEY,
     CONSOLE_LINK_RESOURCE_TYPE_MAPPING,
     CONTAINER_INDEX,
+    HF_LOGIN_DEFAULT_TIMEOUT,
     MAXIMUM_ALLOWED_DATASET_IN_BYTE,
     MODEL_BY_REFERENCE_OSS_PATH_KEY,
     SERVICE_MANAGED_CONTAINER_URI_SCHEME,
@@ -47,7 +57,7 @@ from ads.aqua.constants import (
     VLLM_INFERENCE_RESTRICTED_PARAMS,
 )
 from ads.aqua.data import AquaResourceIdentifier
-from ads.common.auth import default_signer
+from ads.common.auth import AuthState, default_signer
 from ads.common.extended_enum import ExtendedEnumMeta
 from ads.common.object_storage_details import ObjectStorageDetails
 from ads.common.oci_resource import SEARCH_TYPE, OCIResource
@@ -771,6 +781,33 @@ def get_ocid_substring(ocid: str, key_len: int) -> str:
     return ocid[-key_len:] if ocid and len(ocid) > key_len else ""
 
 
+def upload_folder(os_path: str, local_dir: str, model_name: str) -> str:
+    """Upload the local folder to the object storage
+
+    Args:
+        os_path (str): object storage URI with prefix. This is the path to upload
+        local_dir (str): Local directory where the object is downloaded
+        model_name (str): Name of the huggingface model
+    Retuns:
+        str: Object name inside the bucket
+    """
+    os_details: ObjectStorageDetails = ObjectStorageDetails.from_path(os_path)
+    if not os_details.is_bucket_versioned():
+        raise ValueError(f"Version is not enabled at object storage location {os_path}")
+    auth_state = AuthState()
+    object_path = os_details.filepath.rstrip("/") + "/" + model_name + "/"
+    command = f"oci os object bulk-upload --src-dir {local_dir} --prefix {object_path} -bn {os_details.bucket} -ns {os_details.namespace} --auth {auth_state.oci_iam_type} --profile {auth_state.oci_key_profile} --no-overwrite"
+    try:
+        logger.info(f"Running: {command}")
+        subprocess.check_call(shlex.split(command))
+    except subprocess.CalledProcessError as e:
+        logger.error(
+            f"Error uploading the object. Exit code: {e.returncode} with error {e.stdout}"
+        )
+
+    return f"oci://{os_details.bucket}@{os_details.namespace}" + "/" + object_path
+
+
 def is_service_managed_container(container):
     return container and container.startswith(SERVICE_MANAGED_CONTAINER_URI_SCHEME)
 
@@ -935,3 +972,93 @@ def get_restricted_params_by_container(container_type_name: str) -> set:
         return TGI_INFERENCE_RESTRICTED_PARAMS
     else:
         return set()
+
+
+def get_huggingface_login_timeout() -> int:
+    """This helper function returns the huggingface login timeout, returns default if not set via
+    env var.
+    Returns
+    -------
+    timeout: int
+        huggingface login timeout.
+
+    """
+    timeout = HF_LOGIN_DEFAULT_TIMEOUT
+    try:
+        timeout = int(
+            os.environ.get("HF_LOGIN_DEFAULT_TIMEOUT", HF_LOGIN_DEFAULT_TIMEOUT)
+        )
+    except ValueError:
+        pass
+    return timeout
+
+
+def format_hf_custom_error_message(error: HfHubHTTPError):
+    """
+    Formats a custom error message based on the Hugging Face error response.
+
+    Parameters
+    ----------
+    error (HfHubHTTPError): The caught exception.
+
+    Raises
+    ------
+    AquaRuntimeError: A user-friendly error message.
+    """
+    # Extract the repository URL from the error message if present
+    match = re.search(r"(https://huggingface.co/[^\s]+)", str(error))
+    url = match.group(1) if match else "the requested Hugging Face URL."
+
+    if isinstance(error, RepositoryNotFoundError):
+        raise AquaRuntimeError(
+            reason=f"Failed to access `{url}`. Please check if the provided repository name is correct. "
+            "If the repo is private, make sure you are authenticated and have a valid HF token registered. "
+            "To register your token, run this command in your terminal: `huggingface-cli login`",
+            service_payload={"error": "RepositoryNotFoundError"},
+        )
+
+    if isinstance(error, GatedRepoError):
+        raise AquaRuntimeError(
+            reason=f"Access denied to `{url}` "
+            "This repository is gated. Access is restricted to authorized users. "
+            "Please request access or check with the repository administrator. "
+            "If you are trying to access a gated repository, ensure you have a valid HF token registered. "
+            "To register your token, run this command in your terminal: `huggingface-cli login`",
+            service_payload={"error": "GatedRepoError"},
+        )
+
+    if isinstance(error, RevisionNotFoundError):
+        raise AquaRuntimeError(
+            reason=f"The specified revision could not be found at `{url}` "
+            "Please check the revision identifier and try again.",
+            service_payload={"error": "RevisionNotFoundError"},
+        )
+
+    raise AquaRuntimeError(
+        reason=f"An error occurred while accessing `{url}` "
+        "Please check your network connection and try again. "
+        "If you are trying to access a gated repository, ensure you have a valid HF token registered. "
+        "To register your token, run this command in your terminal: `huggingface-cli login`",
+        service_payload={"error": "Error"},
+    )
+
+
+@cached(cache=TTLCache(maxsize=1, ttl=timedelta(hours=5), timer=datetime.now))
+def get_hf_model_info(repo_id: str) -> ModelInfo:
+    """Gets the model information object for the given model repository name. For models that requires a token,
+    this method assumes that the token validation is already done.
+
+    Parameters
+    ----------
+    repo_id: str
+        hugging face model repository name
+
+    Returns
+    -------
+        instance of ModelInfo object
+
+    """
+    try:
+        return HfApi().model_info(repo_id=repo_id)
+    except HfHubHTTPError as err:
+        raise format_hf_custom_error_message(err) from err

ads/aqua/constants.py

@@ -34,6 +34,7 @@ AQUA_MODEL_ARTIFACT_CONFIG = "config.json"
 AQUA_MODEL_ARTIFACT_CONFIG_MODEL_NAME = "_name_or_path"
 AQUA_MODEL_ARTIFACT_CONFIG_MODEL_TYPE = "model_type"
 AQUA_MODEL_ARTIFACT_FILE = "model_file"
+HF_LOGIN_DEFAULT_TIMEOUT = 2
 
 TRAINING_METRICS_FINAL = "training_metrics_final"
 VALIDATION_METRICS_FINAL = "validation_metrics_final"

ads/aqua/evaluation/evaluation.py

@@ -191,7 +191,7 @@ class AquaEvaluationApp(AquaApp):
                         enable_spec=True
                     ).inference
                     for container in inference_config.values():
-                        if container.name == runtime.image.split(":")[0]:
+                        if container.name == runtime.image[:runtime.image.rfind(":")]:
                             eval_inference_configuration = (
                                 container.spec.evaluation_configuration
                             )

ads/aqua/extension/common_handler.py

@@ -1,18 +1,24 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
 # Copyright (c) 2024 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 
 
 from importlib import metadata
 
+import huggingface_hub
 import requests
+from huggingface_hub import HfApi
+from huggingface_hub.utils import LocalTokenNotFoundError
 from tornado.web import HTTPError
 
 from ads.aqua import ODSC_MODEL_COMPARTMENT_OCID
 from ads.aqua.common.decorator import handle_exceptions
 from ads.aqua.common.errors import AquaResourceAccessError, AquaRuntimeError
-from ads.aqua.common.utils import fetch_service_compartment, known_realm
+from ads.aqua.common.utils import (
+    fetch_service_compartment,
+    get_huggingface_login_timeout,
+    known_realm,
+)
 from ads.aqua.extension.base_handler import AquaAPIhandler
 from ads.aqua.extension.errors import Errors
 
@@ -46,16 +52,80 @@ class CompatibilityCheckHandler(AquaAPIhandler):
 
         """
         if ODSC_MODEL_COMPARTMENT_OCID or fetch_service_compartment():
-            return self.finish(dict(status="ok"))
+            return self.finish({"status": "ok"})
         elif known_realm():
-            return self.finish(dict(status="compatible"))
+            return self.finish({"status": "compatible"})
         else:
             raise AquaResourceAccessError(
-                f"The AI Quick actions extension is not compatible in the given region."
+                "The AI Quick actions extension is not compatible in the given region."
             )
 
 
+class NetworkStatusHandler(AquaAPIhandler):
+    """Handler to check internet connection."""
+
+    @handle_exceptions
+    def get(self):
+        requests.get("https://huggingface.com", timeout=get_huggingface_login_timeout())
+        return self.finish({"status": 200, "message": "success"})
+
+
+class HFLoginHandler(AquaAPIhandler):
+    """Handler to login to HF."""
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):
+        """Handles post request for the HF login.
+
+        Raises
+        ------
+        HTTPError
+            Raises HTTPError if inputs are missing or are invalid.
+        """
+        try:
+            input_data = self.get_json_body()
+        except Exception as ex:
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT) from ex
+
+        if not input_data:
+            raise HTTPError(400, Errors.NO_INPUT_DATA)
+
+        token = input_data.get("token")
+
+        if not token:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("token"))
+
+        # Login to HF
+        try:
+            huggingface_hub.login(token=token, new_session=False)
+        except Exception as ex:
+            raise AquaRuntimeError(
+                reason=str(ex), service_payload={"error": type(ex).__name__}
+            ) from ex
+
+        return self.finish({"status": 200, "message": "login successful"})
+
+
+class HFUserStatusHandler(AquaAPIhandler):
+    """Handler to check if user logged in to the HF."""
+
+    @handle_exceptions
+    def get(self):
+        try:
+            HfApi().whoami()
+        except LocalTokenNotFoundError as err:
+            raise AquaRuntimeError(
+                "You are not logged in. Please log in to Hugging Face using the `huggingface-cli login` command."
+                "See https://huggingface.co/settings/tokens.",
+            ) from err
+
+        return self.finish({"status": 200, "message": "logged in"})
+
+
 __handlers__ = [
     ("ads_version", ADSVersionHandler),
     ("hello", CompatibilityCheckHandler),
+    ("network_status", NetworkStatusHandler),
+    ("hf_login", HFLoginHandler),
+    ("hf_logged_in", HFUserStatusHandler),
 ]

ads/aqua/extension/deployment_handler.py

@@ -101,6 +101,7 @@ class AquaDeploymentHandler(AquaAPIhandler):
         container_family = input_data.get("container_family")
         ocpus = input_data.get("ocpus")
         memory_in_gbs = input_data.get("memory_in_gbs")
+        model_file = input_data.get("model_file")
 
         self.finish(
             AquaDeploymentApp().create(
@@ -122,6 +123,7 @@ class AquaDeploymentHandler(AquaAPIhandler):
                 container_family=container_family,
                 ocpus=ocpus,
                 memory_in_gbs=memory_in_gbs,
+                model_file=model_file,
             )
         )
 

ads/aqua/extension/model_handler.py

@@ -2,15 +2,19 @@
 # Copyright (c) 2024 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 Optional
 from urllib.parse import urlparse
 
 from tornado.web import HTTPError
 
 from ads.aqua.common.decorator import handle_exceptions
-from ads.aqua.common.errors import AquaValueError
+from ads.aqua.common.errors import AquaRuntimeError, AquaValueError
+from ads.aqua.common.utils import get_hf_model_info
 from ads.aqua.extension.base_handler import AquaAPIhandler
 from ads.aqua.extension.errors import Errors
 from ads.aqua.model import AquaModelApp
+from ads.aqua.model.constants import ModelTask
+from ads.aqua.model.entities import AquaModelSummary, HFModelSummary
 from ads.aqua.ui import ModelFormat
 
 
@@ -26,11 +30,9 @@ class AquaModelHandler(AquaAPIhandler):
         url_parse = urlparse(self.request.path)
         paths = url_parse.path.strip("/")
         if paths.startswith("aqua/model/files"):
-            os_path = self.get_argument("os_path")
-            if not os_path:
-                raise HTTPError(
-                    400, Errors.MISSING_REQUIRED_PARAMETER.format("os_path")
-                )
+            os_path = self.get_argument("os_path", None)
+            model_name = self.get_argument("model_name", None)
+
             model_format = self.get_argument("model_format")
             if not model_format:
                 raise HTTPError(
@@ -38,10 +40,24 @@ class AquaModelHandler(AquaAPIhandler):
                 )
             try:
                 model_format = ModelFormat(model_format.upper())
-            except ValueError:
-                raise AquaValueError(f"Invalid model format: {model_format}")
+            except ValueError as err:
+                raise AquaValueError(f"Invalid model format: {model_format}") from err
             else:
-                return self.finish(AquaModelApp.get_model_files(os_path, model_format))
+                if os_path:
+                    return self.finish(
+                        AquaModelApp.get_model_files(os_path, model_format)
+                    )
+                elif model_name:
+                    return self.finish(
+                        AquaModelApp.get_hf_model_files(model_name, model_format)
+                    )
+                else:
+                    raise HTTPError(
+                        400,
+                        Errors.MISSING_ONEOF_REQUIRED_PARAMETER.format(
+                            "os_path", "model_name"
+                        ),
+                    )
         elif not model_id:
             return self.list()
 
@@ -52,7 +68,7 @@ class AquaModelHandler(AquaAPIhandler):
         return self.finish(AquaModelApp().get(model_id))
 
     @handle_exceptions
-    def delete(self, id=""):
+    def delete(self):
         """Handles DELETE request for clearing cache"""
         url_parse = urlparse(self.request.path)
         paths = url_parse.path.strip("/")
@@ -86,8 +102,8 @@ class AquaModelHandler(AquaAPIhandler):
         """
         try:
             input_data = self.get_json_body()
-        except Exception:
-            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT)
+        except Exception as ex:
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT) from ex
 
         if not input_data:
             raise HTTPError(400, Errors.NO_INPUT_DATA)
@@ -105,11 +121,15 @@ class AquaModelHandler(AquaAPIhandler):
         compartment_id = input_data.get("compartment_id")
         project_id = input_data.get("project_id")
         model_file = input_data.get("model_file")
+        download_from_hf = (
+            str(input_data.get("download_from_hf", "false")).lower() == "true"
+        )
 
         return self.finish(
             AquaModelApp().register(
                 model=model,
                 os_path=os_path,
+                download_from_hf=download_from_hf,
                 inference_container=inference_container,
                 finetuning_container=finetuning_container,
                 compartment_id=compartment_id,
@@ -130,7 +150,88 @@ class AquaModelLicenseHandler(AquaAPIhandler):
         return self.finish(AquaModelApp().load_license(model_id))
 
 
+class AquaHuggingFaceHandler(AquaAPIhandler):
+    """Handler for Aqua Hugging Face REST APIs."""
+
+    @staticmethod
+    def _find_matching_aqua_model(model_id: str) -> Optional[AquaModelSummary]:
+        """
+        Finds a matching model in AQUA based on the model ID from Hugging Face.
+
+        Parameters
+        ----------
+        model_id (str): The Hugging Face model ID to match.
+
+        Returns
+        -------
+        Optional[AquaModelSummary]
+            Returns the matching AquaModelSummary object if found, else None.
+        """
+        # Convert the Hugging Face model ID to lowercase once
+        model_id_lower = model_id.lower()
+
+        aqua_model_app = AquaModelApp()
+        model_ocid = aqua_model_app._find_matching_aqua_model(model_id=model_id_lower)
+        if model_ocid:
+            return aqua_model_app.get(model_ocid, load_model_card=False)
+
+        return None
+
+    @handle_exceptions
+    def post(self, *args, **kwargs):
+        """Handles post request for the HF Models APIs
+
+        Raises
+        ------
+        HTTPError
+            Raises HTTPError if inputs are missing or are invalid.
+        """
+        try:
+            input_data = self.get_json_body()
+        except Exception as ex:
+            raise HTTPError(400, Errors.INVALID_INPUT_DATA_FORMAT) from ex
+
+        if not input_data:
+            raise HTTPError(400, Errors.NO_INPUT_DATA)
+
+        model_id = input_data.get("model_id")
+
+        if not model_id:
+            raise HTTPError(400, Errors.MISSING_REQUIRED_PARAMETER.format("model_id"))
+
+        # Get model info from the HF
+        hf_model_info = get_hf_model_info(repo_id=model_id)
+
+        # Check if model is not disabled
+        if hf_model_info.disabled:
+            raise AquaRuntimeError(
+                f"The chosen model '{hf_model_info.id}' is currently disabled and cannot be imported into AQUA. "
+                "Please verify the model's status on the Hugging Face Model Hub or select a different model."
+            )
+
+        # Check pipeline_tag, it should be `text-generation`
+        if (
+            not hf_model_info.pipeline_tag
+            or hf_model_info.pipeline_tag.lower() != ModelTask.TEXT_GENERATION
+        ):
+            raise AquaRuntimeError(
+                f"Unsupported pipeline tag for the chosen model: '{hf_model_info.pipeline_tag}'. "
+                f"AQUA currently supports the following tasks only: {', '.join(ModelTask.values())}. "
+                "Please select a model with a compatible pipeline tag."
+            )
+
+        # Check if it is a service/verified model
+        aqua_model_info: AquaModelSummary = self._find_matching_aqua_model(
+            model_id=hf_model_info.id
+        )
+
+        return self.finish(
+            HFModelSummary(model_info=hf_model_info, aqua_model_info=aqua_model_info)
+        )
+
+
 __handlers__ = [
     ("model/?([^/]*)", AquaModelHandler),
     ("model/?([^/]*)/license", AquaModelLicenseHandler),
+    ("model/hf/search/?([^/]*)", AquaHuggingFaceHandler),
 ]

ads/aqua/model/entities.py

@@ -14,6 +14,8 @@ from dataclasses import InitVar, dataclass, field
 from typing import List, Optional
 
 import oci
+from huggingface_hub import hf_api
+
 from ads.aqua import logger
 from ads.aqua.app import CLIBuilderMixin
 from ads.aqua.common import utils
@@ -41,10 +43,12 @@ class AquaFineTuneValidation(DataClassSerializable):
     value: str = ""
 
 
+@dataclass(repr=False)
 class ModelValidationResult:
     model_file: Optional[str] = None
-    model_format: ModelFormat = None
+    model_formats: List[ModelFormat] = field(default_factory=list)
     telemetry_model_name: str = None
+    tags: Optional[dict] = None
 
 
 @dataclass(repr=False)
@@ -84,7 +88,8 @@ class AquaModelSummary(DataClassSerializable):
     ready_to_import: bool = False
     nvidia_gpu_supported: bool = False
     arm_cpu_supported: bool = False
-    model_format: ModelFormat = ModelFormat.UNKNOWN
+    model_file: Optional[str] = None
+    model_formats: List[ModelFormat] = field(default_factory=list)
 
 
 @dataclass(repr=False)
@@ -95,6 +100,7 @@ class AquaModel(AquaModelSummary, DataClassSerializable):
     inference_container: str = None
     finetuning_container: str = None
     evaluation_container: str = None
+    artifact_location: str = None
 
 
 @dataclass(repr=False)
@@ -105,6 +111,16 @@ class HFModelContainerInfo:
     finetuning_container: str = None
 
 
+@dataclass(repr=False)
+class HFModelSummary:
+    """Represents a summary of Hugging Face model."""
+
+    model_info: hf_api.ModelInfo = field(default_factory=hf_api.ModelInfo)
+    aqua_model_info: Optional[AquaModelSummary] = field(
+        default_factory=AquaModelSummary
+    )
+
+
 @dataclass(repr=False)
 class AquaEvalFTCommon(DataClassSerializable):
     """Represents common fields for evaluation and fine-tuning."""
@@ -264,6 +280,8 @@ class AquaFineTuneModel(AquaModel, AquaEvalFTCommon, DataClassSerializable):
 class ImportModelDetails(CLIBuilderMixin):
     model: str
     os_path: str
+    download_from_hf: Optional[bool] = True
+    local_dir: Optional[str] = None
     inference_container: Optional[str] = None
     finetuning_container: Optional[str] = None
     compartment_id: Optional[str] = None