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

ads/common/utils.py

@@ -1,10 +1,8 @@
 #!/usr/bin/env python
-# -*- coding: utf-8; -*-
 
 # Copyright (c) 2020, 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 __future__ import absolute_import, print_function
 
 import collections
 import contextlib
@@ -23,9 +21,8 @@ import tempfile
 from datetime import datetime
 from enum import Enum
 from io import DEFAULT_BUFFER_SIZE
-from pathlib import Path
 from textwrap import fill
-from typing import Dict, Optional, Union
+from typing import Any, Dict, Optional, Tuple, Union
 from urllib import request
 from urllib.parse import urlparse
 
@@ -66,6 +63,8 @@ MIN_RATIO_FOR_DOWN_SAMPLING = 1 / 20
 # Maximum distinct values by cardinality will be used for plotting
 MAX_DISPLAY_VALUES = 10
 
+UNKNOWN = ""
+
 # par link of the index json file.
 PAR_LINK = "https://objectstorage.us-ashburn-1.oraclecloud.com/p/WyjtfVIG0uda-P3-2FmAfwaLlXYQZbvPZmfX1qg0-sbkwEQO6jpwabGr2hMDBmBp/n/ociodscdev/b/service-conda-packs/o/service_pack/index.json"
 
@@ -85,6 +84,7 @@ mpl.rcParams["axes.prop_cycle"] = cycler(
     color=["teal", "blueviolet", "forestgreen", "peru", "y", "dodgerblue", "r"]
 )
 
+
 # sqlalchemy engines
 _engines = {}
 
@@ -152,6 +152,22 @@ def oci_key_location():
     )
 
 
+def text_sanitizer(content):
+    if isinstance(content, str):
+        return (
+            content.replace("“", '"')
+            .replace("”", '"')
+            .replace("’", "'")
+            .replace("‘", "'")
+            .replace("—", "-")
+            .encode("utf-8", "ignore")
+            .decode("utf-8", "ignore")
+        )
+    if isinstance(content, dict):
+        return json.dumps(content)
+    return str(content)
+
+
 @deprecated(
     "2.5.10",
     details="Deprecated, use: from ads.common.auth import AuthState; AuthState().oci_config_path",
@@ -215,6 +231,37 @@ def random_valid_ocid(prefix="ocid1.dataflowapplication.oc1.iad"):
     return f"{left}.{fake}"
 
 
+def parse_bool(value: Any) -> bool:
+    """
+    Converts a value to boolean. For strings, it interprets 'true', '1', or 'yes'
+    (case insensitive) as True; everything else as False.
+
+    Parameters
+    ----------
+    value : Any
+        The value to convert to boolean.
+
+    Returns
+    -------
+    bool
+        The boolean interpretation of the value.
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "1", "yes")
+    return bool(value)
+
+
+def read_file(file_path: str, **kwargs) -> str:
+    try:
+        with fsspec.open(file_path, "r", **kwargs.get("auth", {})) as f:
+            return f.read()
+    except Exception as e:
+        logger.debug(f"Failed to read file {file_path}. {e}")
+        return UNKNOWN
+
+
 def get_dataframe_styles(max_width=75):
     """Styles used for dataframe, example usage:
 
@@ -501,13 +548,13 @@ def print_user_message(
     if is_documentation_mode() and is_notebook():
         if display_type.lower() == "tip":
             if "\n" in msg:
-                t = "<b>{}:</b>".format(title.upper().strip()) if title else ""
+                t = f"<b>{title.upper().strip()}:</b>" if title else ""
 
                 user_message = "{}{}".format(
                     t,
                     "".join(
                         [
-                            "<br>&nbsp;&nbsp;+&nbsp;{}".format(x.strip())
+                            f"<br>&nbsp;&nbsp;+&nbsp;{x.strip()}"
                             for x in msg.strip().split("\n")
                         ]
                     ),
@@ -646,7 +693,7 @@ def ellipsis_strings(raw, n=24):
         else:
             n2 = int(n) // 2 - 3
             n1 = n - n2 - 3
-            result.append("{0}...{1}".format(s[:n1], s[-n2:]))
+            result.append(f"{s[:n1]}...{s[-n2:]}")
 
     return result
 
@@ -942,9 +989,9 @@ def generate_requirement_file(
     with open(os.path.join(file_path, file_name), "w") as req_file:
         for lib in requirements:
             if requirements[lib]:
-                req_file.write("{}=={}\n".format(lib, requirements[lib]))
+                req_file.write(f"{lib}=={requirements[lib]}\n")
             else:
-                req_file.write("{}\n".format(lib))
+                req_file.write(f"{lib}\n")
 
 
 def _get_feature_type_and_dtype(column):
@@ -966,7 +1013,7 @@ def to_dataframe(
         pd.Series,
         np.ndarray,
         pd.DataFrame,
-    ]
+    ],
 ):
     """
     Convert to pandas DataFrame.
@@ -1391,7 +1438,7 @@ def remove_file(file_path: str, auth: Optional[Dict] = None) -> None:
     fs = fsspec.filesystem(scheme, **auth)
     try:
         fs.rm(file_path)
-    except FileNotFoundError as e:
+    except FileNotFoundError:
         raise FileNotFoundError(f"`{file_path}` not found.")
     except Exception as e:
         raise e
@@ -1786,3 +1833,36 @@ def get_log_links(
         console_link_url = f"https://cloud.oracle.com/logging/log-groups/{log_group_id}?region={region}"
 
     return console_link_url
+
+
+def parse_content_disposition(header: str) -> Tuple[str, Dict[str, str]]:
+    """
+    Parses a Content-Disposition header into its main disposition and a dictionary of parameters.
+
+    For example:
+        'attachment; filename="example.txt"'
+    will be parsed into:
+        ('attachment', {'filename': 'example.txt'})
+
+    Parameters
+    ----------
+    header (str): The Content-Disposition header string.
+
+    Returns
+    -------
+    Tuple[str, Dict[str, str]]: A tuple containing the disposition and a dictionary of parameters.
+    """
+    if not header:
+        return "", {}
+
+    parts = header.split(";")
+    # The first part is the main disposition (e.g., "attachment").
+    disposition = parts[0].strip().lower()
+    params: Dict[str, str] = {}
+
+    # Process each subsequent part to extract key-value pairs.
+    for part in parts[1:]:
+        if "=" in part:
+            key, value = part.split("=", 1)
+            params[key.strip().lower()] = value.strip().strip('"')
+    return disposition, params

ads/config.py

@@ -80,6 +80,9 @@ AQUA_TELEMETRY_BUCKET_NS = os.environ.get("AQUA_TELEMETRY_BUCKET_NS", CONDA_BUCK
 DEBUG_TELEMETRY = os.environ.get("DEBUG_TELEMETRY", None)
 AQUA_SERVICE_NAME = "aqua"
 DATA_SCIENCE_SERVICE_NAME = "data-science"
+USER = "USER"
+SERVICE = "SERVICE"
+
 
 
 THREADED_DEFAULT_TIMEOUT = 5

ads/llm/__init__.py

@@ -1,21 +1,25 @@
 #!/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 (
+        OCIModelDeploymentLLM,
+        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/llm/langchain/plugins/llms/oci_data_science_model_deployment_endpoint.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-# Copyright (c) 2024 Oracle and/or its affiliates.
+# 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/
 
 
@@ -433,23 +433,6 @@ class OCIModelDeploymentLLM(BaseLLM, BaseOCIModelDeployment):
     model: str = DEFAULT_MODEL_NAME
     """The name of the model."""
 
-    max_tokens: int = 256
-    """Denotes the number of tokens to predict per generation."""
-
-    temperature: float = 0.2
-    """A non-negative float that tunes the degree of randomness in generation."""
-
-    k: int = -1
-    """Number of most likely tokens to consider at each step."""
-
-    p: float = 0.75
-    """Total probability mass of tokens to consider at each step."""
-
-    best_of: int = 1
-    """Generates best_of completions server-side and returns the "best"
-    (the one with the highest log probability per token).
-    """
-
     stop: Optional[List[str]] = None
     """Stop words to use when generating. Model output is cut off
     at the first occurrence of any of these substrings."""
@@ -466,14 +449,9 @@ class OCIModelDeploymentLLM(BaseLLM, BaseOCIModelDeployment):
     def _default_params(self) -> Dict[str, Any]:
         """Get the default parameters."""
         return {
-            "best_of": self.best_of,
-            "max_tokens": self.max_tokens,
             "model": self.model,
             "stop": self.stop,
             "stream": self.streaming,
-            "temperature": self.temperature,
-            "top_k": self.k,
-            "top_p": self.p,
         }
 
     @property
@@ -788,6 +766,23 @@ class OCIModelDeploymentTGI(OCIModelDeploymentLLM):
 
     """
 
+    max_tokens: int = 256
+    """Denotes the number of tokens to predict per generation."""
+
+    temperature: float = 0.2
+    """A non-negative float that tunes the degree of randomness in generation."""
+
+    k: int = -1
+    """Number of most likely tokens to consider at each step."""
+
+    p: float = 0.75
+    """Total probability mass of tokens to consider at each step."""
+
+    best_of: int = 1
+    """Generates best_of completions server-side and returns the "best"
+    (the one with the highest log probability per token).
+    """
+
     api: Literal["/generate", "/v1/completions"] = "/v1/completions"
     """Api spec."""
 
@@ -922,6 +917,20 @@ class OCIModelDeploymentVLLM(OCIModelDeploymentLLM):
 
     """
 
+    max_tokens: int = 256
+    """Denotes the number of tokens to predict per generation."""
+
+    temperature: float = 0.2
+    """A non-negative float that tunes the degree of randomness in generation."""
+
+    p: float = 0.75
+    """Total probability mass of tokens to consider at each step."""
+
+    best_of: int = 1
+    """Generates best_of completions server-side and returns the "best"
+    (the one with the highest log probability per token).
+    """
+
     n: int = 1
     """Number of output sequences to return for the given prompt."""
 

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,12 @@ 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_created_by_reference()
+            and self.model_file_description
+        ):
             self.download_from_model_file_description()
             self.progress.update()
             return

ads/model/common/utils.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*--
 
 # Copyright (c) 2022, 2023 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
@@ -7,16 +6,29 @@
 import json
 import os
 import tempfile
-import yaml
 from typing import Any, Dict, Optional
 from zipfile import ZipFile
-from ads.common import utils
 
+import yaml
+
+from ads.common import utils
+from ads.common.extended_enum import ExtendedEnum
 
 DEPRECATE_AS_ONNX_WARNING = "This attribute `as_onnx` will be deprecated in the future. You can choose specific format by setting `model_save_serializer`."
 DEPRECATE_USE_TORCH_SCRIPT_WARNING = "This attribute `use_torch_script` will be deprecated in the future. You can choose specific format by setting `model_save_serializer`."
 
 
+class MetadataArtifactPathType(ExtendedEnum):
+    """
+    Enum for defining metadata artifact path type.
+    Can be either local path or OSS path. It can also be the content itself.
+    """
+
+    LOCAL = "local"
+    OSS = "oss"
+    CONTENT = "content"
+
+
 def _extract_locals(
     locals: Dict[str, Any], filter_out_nulls: Optional[bool] = True
 ) -> Dict[str, Any]: