oracle-ads 2.12.11__py3-none-any.whl → 2.13.1rc0__py3-none-any.whl

ads/common/auth.py

@@ -1,23 +1,25 @@
 #!/usr/bin/env python
-# -*- coding: utf-8; -*-
 
-# Copyright (c) 2021, 2023 Oracle and/or its affiliates.
+# Copyright (c) 2021, 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 copy
-from datetime import datetime
 import os
-from dataclasses import dataclass
 import time
+from dataclasses import dataclass
+from datetime import datetime
 from typing import Any, Callable, Dict, Optional, Union
 
-import ads.telemetry
 import oci
+from oci.config import (
+    DEFAULT_LOCATION,  # "~/.oci/config"
+    DEFAULT_PROFILE,  # "DEFAULT"
+)
+
+import ads.telemetry
 from ads.common import logger
 from ads.common.decorator.deprecate import deprecated
-from ads.common.extended_enum import ExtendedEnumMeta
-from oci.config import DEFAULT_LOCATION  # "~/.oci/config"
-from oci.config import DEFAULT_PROFILE  # "DEFAULT"
+from ads.common.extended_enum import ExtendedEnum
 
 SECURITY_TOKEN_LEFT_TIME = 600
 
@@ -26,7 +28,7 @@ class SecurityTokenError(Exception):  # pragma: no cover
     pass
 
 
-class AuthType(str, metaclass=ExtendedEnumMeta):
+class AuthType(ExtendedEnum):
     API_KEY = "api_key"
     RESOURCE_PRINCIPAL = "resource_principal"
     INSTANCE_PRINCIPAL = "instance_principal"
@@ -73,7 +75,11 @@ class AuthState(metaclass=SingletonMeta):
         self.oci_key_profile = self.oci_key_profile or os.environ.get(
             "OCI_CONFIG_PROFILE", DEFAULT_PROFILE
         )
-        self.oci_config = self.oci_config or {"region": os.environ["OCI_RESOURCE_REGION"]} if os.environ.get("OCI_RESOURCE_REGION") else {}
+        self.oci_config = (
+            self.oci_config or {"region": os.environ["OCI_RESOURCE_REGION"]}
+            if os.environ.get("OCI_RESOURCE_REGION")
+            else {}
+        )
         self.oci_signer_kwargs = self.oci_signer_kwargs or {}
         self.oci_client_kwargs = self.oci_client_kwargs or {}
 
@@ -82,7 +88,9 @@ def set_auth(
     auth: Optional[str] = AuthType.API_KEY,
     oci_config_location: Optional[str] = DEFAULT_LOCATION,
     profile: Optional[str] = DEFAULT_PROFILE,
-    config: Optional[Dict] = {"region": os.environ["OCI_RESOURCE_REGION"]} if os.environ.get("OCI_RESOURCE_REGION") else {},
+    config: Optional[Dict] = {"region": os.environ["OCI_RESOURCE_REGION"]}
+    if os.environ.get("OCI_RESOURCE_REGION")
+    else {},
     signer: Optional[Any] = None,
     signer_callable: Optional[Callable] = None,
     signer_kwargs: Optional[Dict] = {},
@@ -202,8 +210,8 @@ def set_auth(
         oci_config_location != DEFAULT_LOCATION or profile != DEFAULT_PROFILE
     ):
         raise ValueError(
-            f"'config' and 'oci_config_location', 'profile' pair are mutually exclusive."
-            f"Please specify 'config' OR 'oci_config_location', 'profile' pair."
+            "'config' and 'oci_config_location', 'profile' pair are mutually exclusive."
+            "Please specify 'config' OR 'oci_config_location', 'profile' pair."
         )
 
     auth_state.oci_config = config
@@ -621,7 +629,7 @@ class APIKey(AuthSignerGenerator):
             )
 
         oci.config.validate_config(configuration)
-        logger.debug(f"Using 'api_key' authentication.")
+        logger.debug("Using 'api_key' authentication.")
         return {
             "config": configuration,
             "signer": oci.signer.Signer(
@@ -684,14 +692,19 @@ class ResourcePrincipal(AuthSignerGenerator):
             "signer": oci.auth.signers.get_resource_principals_signer(),
             "client_kwargs": self.client_kwargs,
         }
-        logger.debug(f"Using 'resource_principal' authentication.")
+        logger.debug("Using 'resource_principal' authentication.")
         return signer_dict
 
     @staticmethod
     def supported():
         return any(
             os.environ.get(var)
-            for var in ['JOB_RUN_OCID', 'NB_SESSION_OCID', 'DATAFLOW_RUN_ID', 'PIPELINE_RUN_OCID']
+            for var in [
+                "JOB_RUN_OCID",
+                "NB_SESSION_OCID",
+                "DATAFLOW_RUN_ID",
+                "PIPELINE_RUN_OCID",
+            ]
         )
 
 
@@ -747,7 +760,7 @@ class InstancePrincipal(AuthSignerGenerator):
             ),
             "client_kwargs": self.client_kwargs,
         }
-        logger.debug(f"Using 'instance_principal' authentication.")
+        logger.debug("Using 'instance_principal' authentication.")
         return signer_dict
 
 
@@ -814,7 +827,7 @@ class SecurityToken(AuthSignerGenerator):
                 oci.config.from_file(self.oci_config_location, self.oci_key_profile)
             )
 
-        logger.debug(f"Using 'security_token' authentication.")
+        logger.debug("Using 'security_token' authentication.")
 
         for parameter in self.SECURITY_TOKEN_REQUIRED:
             if parameter not in configuration:
@@ -903,7 +916,7 @@ class SecurityToken(AuthSignerGenerator):
             raise ValueError("Invalid `security_token_file`. Specify a valid path.")
         try:
             token = None
-            with open(expanded_path, "r") as f:
+            with open(expanded_path) as f:
                 token = f.read()
             return token
         except:
@@ -1023,7 +1036,7 @@ class OCIAuthContext:
             logger.debug(f"OCI profile set to {self.profile}")
         else:
             ads.set_auth(auth=AuthType.RESOURCE_PRINCIPAL)
-            logger.debug(f"OCI auth set to resource principal")
+            logger.debug("OCI auth set to resource principal")
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):

ads/common/extended_enum.py

@@ -1,73 +1,81 @@
 #!/usr/bin/env python
-# -*- coding: utf-8; -*-
 
-# Copyright (c) 2022, 2024 Oracle and/or its affiliates.
+# Copyright (c) 2022, 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 abc import ABCMeta
-from enum import Enum
 
 
 class ExtendedEnumMeta(ABCMeta):
-    """The helper metaclass to extend functionality of a generic Enum.
+    """
+    A helper metaclass to extend functionality of a generic "Enum-like" class.
 
     Methods
     -------
-    values(cls) -> list:
-        Gets the list of class attributes.
-
-    Examples
-    --------
-    >>> class TestEnum(str, metaclass=ExtendedEnumMeta):
-    ...    KEY1 = "value1"
-    ...    KEY2 = "value2"
-    >>> print(TestEnum.KEY1) # "value1"
+    __contains__(cls, item) -> bool:
+        Checks if `item` is among the attribute values of the class.
+        Case-insensitive if `item` is a string.
+    values(cls) -> tuple:
+        Returns the tuple of class attribute values.
+    keys(cls) -> tuple:
+        Returns the tuple of class attribute names.
     """
 
-    def __contains__(cls, value):
-        return value and value.lower() in tuple(value.lower() for value in cls.values())
-
-    def values(cls) -> list:
-        """Gets the list of class attributes values.
+    def __contains__(cls, item: object) -> bool:
+        """
+        Checks if `item` is a member of the class's values.
 
-        Returns
-        -------
-        list
-            The list of class values.
+        - If `item` is a string, does a case-insensitive match against any string
+          values stored in the class.
+        - Otherwise, does a direct membership test.
+        """
+        # Gather the attribute values
+        attr_values = cls.values()
+
+        # If item is a string, compare case-insensitively to any str-type values
+        if isinstance(item, str):
+            return any(
+                isinstance(val, str) and val.lower() == item.lower()
+                for val in attr_values
+            )
+        else:
+            # For non-string items (e.g., int), do a direct membership check
+            return item in attr_values
+
+    def __iter__(cls):
+        # Make the class iterable by returning an iterator over its values
+        return iter(cls.values())
+
+    def values(cls) -> tuple:
+        """
+        Gets the tuple of class attribute values, excluding private or special
+        attributes and any callables (methods, etc.).
         """
         return tuple(
-            value for key, value in cls.__dict__.items() if not key.startswith("_")
+            value
+            for key, value in cls.__dict__.items()
+            if not key.startswith("_") and not callable(value)
         )
 
-    def keys(cls) -> list:
-        """Gets the list of class attributes names.
-
-        Returns
-        -------
-        list
-            The list of class attributes names.
+    def keys(cls) -> tuple:
+        """
+        Gets the tuple of class attribute names, excluding private or special
+        attributes and any callables (methods, etc.).
         """
         return tuple(
-            key for key, value in cls.__dict__.items() if not key.startswith("_")
+            key
+            for key, value in cls.__dict__.items()
+            if not key.startswith("_") and not callable(value)
         )
 
 
-class ExtendedEnum(Enum):
+class ExtendedEnum(metaclass=ExtendedEnumMeta):
     """The base class to extend functionality of a generic Enum.
 
     Examples
     --------
-    >>> class TestEnum(ExtendedEnumMeta):
-    ...    KEY1 = "value1"
-    ...    KEY2 = "value2"
-    >>> print(TestEnum.KEY1.value) # "value1"
+    >>> class TestEnum(ExtendedEnum):
+    ...    KEY1 = "v1"
+    ...    KEY2 = "v2"
     """
-
-    @classmethod
-    def values(cls):
-        return sorted(map(lambda c: c.value, cls))
-
-    @classmethod
-    def keys(cls):
-        return sorted(map(lambda c: c.name, cls))

ads/llm/__init__.py

@@ -1,21 +1,24 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*--
 
-# Copyright (c) 2023 Oracle and/or its affiliates.
+# 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/
 
 try:
     import langchain
-    from ads.llm.langchain.plugins.llms.oci_data_science_model_deployment_endpoint import (
-        OCIModelDeploymentVLLM,
-        OCIModelDeploymentTGI,
-    )
+
+    from ads.llm.chat_template import ChatTemplates
     from ads.llm.langchain.plugins.chat_models.oci_data_science import (
         ChatOCIModelDeployment,
-        ChatOCIModelDeploymentVLLM,
         ChatOCIModelDeploymentTGI,
+        ChatOCIModelDeploymentVLLM,
+    )
+    from ads.llm.langchain.plugins.embeddings.oci_data_science_model_deployment_endpoint import (
+        OCIDataScienceEmbedding,
+    )
+    from ads.llm.langchain.plugins.llms.oci_data_science_model_deployment_endpoint import (
+        OCIModelDeploymentTGI,
+        OCIModelDeploymentVLLM,
     )
-    from ads.llm.chat_template import ChatTemplates
 except ImportError as ex:
     if ex.name == "langchain":
         raise ImportError(

ads/llm/langchain/plugins/embeddings/__init__.py

@@ -0,0 +1,4 @@
+#!/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/

ads/llm/langchain/plugins/embeddings/oci_data_science_model_deployment_endpoint.py

@@ -0,0 +1,184 @@
+#!/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/
+
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+import requests
+from langchain_core.embeddings import Embeddings
+from langchain_core.language_models.llms import create_base_retry_decorator
+from pydantic import BaseModel, Field
+
+DEFAULT_HEADER = {
+    "Content-Type": "application/json",
+}
+
+
+class TokenExpiredError(Exception):
+    pass
+
+
+def _create_retry_decorator(llm) -> Callable[[Any], Any]:
+    """Creates a retry decorator."""
+    errors = [requests.exceptions.ConnectTimeout, TokenExpiredError]
+    decorator = create_base_retry_decorator(
+        error_types=errors, max_retries=llm.max_retries
+    )
+    return decorator
+
+
+class OCIDataScienceEmbedding(BaseModel, Embeddings):
+    """Embedding model deployed on OCI Data Science Model Deployment.
+
+    Example:
+
+        .. code-block:: python
+
+            from ads.llm import OCIDataScienceEmbedding
+
+            embeddings = OCIDataScienceEmbedding(
+                endpoint="https://modeldeployment.us-ashburn-1.oci.customer-oci.com/<md_ocid>/predict",
+            )
+    """  # noqa: E501
+
+    auth: dict = Field(default_factory=dict, exclude=True)
+    """ADS auth dictionary for OCI authentication:
+    https://accelerated-data-science.readthedocs.io/en/latest/user_guide/cli/authentication.html.
+    This can be generated by calling `ads.common.auth.api_keys()`
+    or `ads.common.auth.resource_principal()`. If this is not
+    provided then the `ads.common.default_signer()` will be used."""
+
+    endpoint: str = ""
+    """The uri of the endpoint from the deployed Model Deployment model."""
+
+    model_kwargs: Optional[Dict] = None
+    """Keyword arguments to pass to the model."""
+
+    endpoint_kwargs: Optional[Dict] = None
+    """Optional attributes (except for headers) passed to the request.post
+    function.
+    """
+
+    max_retries: int = 1
+    """The maximum number of retries to make when generating."""
+
+    @property
+    def _identifying_params(self) -> Mapping[str, Any]:
+        """Get the identifying parameters."""
+        _model_kwargs = self.model_kwargs or {}
+        return {
+            **{"endpoint": self.endpoint},
+            **{"model_kwargs": _model_kwargs},
+        }
+
+    def _embed_with_retry(self, **kwargs) -> Any:
+        """Use tenacity to retry the call."""
+        retry_decorator = _create_retry_decorator(self)
+
+        @retry_decorator
+        def _completion_with_retry(**kwargs: Any) -> Any:
+            try:
+                response = requests.post(self.endpoint, **kwargs)
+                response.raise_for_status()
+                return response
+            except requests.exceptions.HTTPError as http_err:
+                if response.status_code == 401 and self._refresh_signer():
+                    raise TokenExpiredError() from http_err
+                else:
+                    raise ValueError(
+                        f"Server error: {str(http_err)}. Message: {response.text}"
+                    ) from http_err
+            except Exception as e:
+                raise ValueError(f"Error occurs by inference endpoint: {str(e)}") from e
+
+        return _completion_with_retry(**kwargs)
+
+    def _embedding(self, texts: List[str]) -> List[List[float]]:
+        """Call out to OCI Data Science Model Deployment Endpoint.
+
+        Args:
+            texts: A list of texts to embed.
+
+        Returns:
+            A list of list of floats representing the embeddings, or None if an
+            error occurs.
+        """
+        _model_kwargs = self.model_kwargs or {}
+        body = self._construct_request_body(texts, _model_kwargs)
+        request_kwargs = self._construct_request_kwargs(body)
+        response = self._embed_with_retry(**request_kwargs)
+        return self._proceses_response(response)
+
+    def _construct_request_kwargs(self, body: Any) -> dict:
+        """Constructs the request kwargs as a dictionary."""
+        from ads.model.common.utils import _is_json_serializable
+
+        _endpoint_kwargs = self.endpoint_kwargs or {}
+        headers = _endpoint_kwargs.pop("headers", DEFAULT_HEADER)
+        return (
+            dict(
+                headers=headers,
+                json=body,
+                auth=self.auth.get("signer"),
+                **_endpoint_kwargs,
+            )
+            if _is_json_serializable(body)
+            else dict(
+                headers=headers,
+                data=body,
+                auth=self.auth.get("signer"),
+                **_endpoint_kwargs,
+            )
+        )
+
+    def _construct_request_body(self, texts: List[str], params: dict) -> Any:
+        """Constructs the request body."""
+        return {"input": texts}
+
+    def _proceses_response(self, response: requests.Response) -> List[List[float]]:
+        """Extracts results from requests.Response."""
+        try:
+            res_json = response.json()
+            embeddings = res_json["data"][0]["embedding"]
+        except Exception as e:
+            raise ValueError(
+                f"Error raised by inference API: {e}.\nResponse: {response.text}"
+            ) from e
+        return embeddings
+
+    def embed_documents(
+        self,
+        texts: List[str],
+        chunk_size: Optional[int] = None,
+    ) -> List[List[float]]:
+        """Compute doc embeddings using OCI Data Science Model Deployment Endpoint.
+
+        Args:
+            texts: The list of texts to embed.
+            chunk_size: The chunk size defines how many input texts will
+                be grouped together as request. If None, will use the
+                chunk size specified by the class.
+
+        Returns:
+            List of embeddings, one for each text.
+        """
+        results = []
+        _chunk_size = (
+            len(texts) if (not chunk_size or chunk_size > len(texts)) else chunk_size
+        )
+        for i in range(0, len(texts), _chunk_size):
+            response = self._embedding(texts[i : i + _chunk_size])
+            results.extend(response)
+        return results
+
+    def embed_query(self, text: str) -> List[float]:
+        """Compute query embeddings using OCI Data Science Model Deployment Endpoint.
+
+        Args:
+            text: The text to embed.
+
+        Returns:
+            Embeddings for the text.
+        """
+        return self._embedding([text])[0]

ads/model/artifact_downloader.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# -*- coding: utf-8; -*-
 
 # Copyright (c) 2022, 2024 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
@@ -12,9 +11,9 @@ from typing import Dict, Optional
 from zipfile import ZipFile
 
 from ads.common import utils
+from ads.common.object_storage_details import ObjectStorageDetails
 from ads.common.utils import extract_region
 from ads.model.service.oci_datascience_model import OCIDataScienceModel
-from ads.common.object_storage_details import ObjectStorageDetails
 
 
 class ArtifactDownloader(ABC):
@@ -169,9 +168,9 @@ class LargeArtifactDownloader(ArtifactDownloader):
 
     def _download(self):
         """Downloads model artifacts."""
-        self.progress.update(f"Importing model artifacts from catalog")
+        self.progress.update("Importing model artifacts from catalog")
 
-        if self.dsc_model.is_model_by_reference() and self.model_file_description:
+        if self.dsc_model._is_model_by_reference() and self.model_file_description:
             self.download_from_model_file_description()
             self.progress.update()
             return