oracle-ads 2.13.9rc0__py3-none-any.whl → 2.13.10rc0__py3-none-any.whl

ads/common/data.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2020, 2022 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+import numpy as np
+from ads.common.utils import _is_dask_dataframe, _is_dask_series
+
+
+class ADSData(object):
+    def __init__(self, X=None, y=None, name="", dataset_type=None):
+        r"""
+        This class wraps the input dataframe to various models, evaluation, and explanation frameworks.
+        It's primary purpose is to hold any metadata relevant to these tasks. This can include it's:
+
+        - X - the independent variables as some dataframe-like structure,
+        - y - the dependent variable or target column as some array-like structure,
+        - name - a string to name the data for user convenience,
+        - dataset_type - the type of the X value.
+
+        As part of this initiative, ADSData knows how to turn itself into an onnxruntime compatible data
+        structure with the method .to_onnxrt(), which takes and onnx session as input.
+
+        Parameters
+        ----------
+        X : Union[pandas.DataFrame, dask.DataFrame, numpy.ndarray, scipy.sparse.csr.csr_matrix]
+            If str, URI for the dataset. The dataset could be read from local or network file system, hdfs, s3 and gcs
+            Should be none if X_train, y_train, X_test, Y_test are provided
+        y: Union[str, pandas.DataFrame, dask.DataFrame, pandas.Series, dask.Series, numpy.ndarray]
+            If str, name of the target in X, otherwise series of labels corresponding to X
+        name: str, optional
+            Name to identify this data
+        dataset_type: ADSDataset optional
+            When this value is available, would be used to evaluate the ads task type
+        kwargs:
+            Additional keyword arguments that would be passed to the underlying Pandas read API.
+        """
+        self.X = X
+        self.y = y
+        self.name = name
+        self.dataset_type = dataset_type
+
+    @staticmethod
+    def build(X=None, y=None, name="", dataset_type=None, **kwargs):
+        r"""
+        Returns an ADSData object built from the (source, target) or (X,y)
+
+        Parameters
+        ----------
+        X : Union[pandas.DataFrame, dask.DataFrame, numpy.ndarray, scipy.sparse.csr.csr_matrix]
+            If str, URI for the dataset. The dataset could be read from local or network file system, hdfs, s3 and gcs
+            Should be none if X_train, y_train, X_test, Y_test are provided
+        y: Union[str, pandas.DataFrame, dask.DataFrame, pandas.Series, dask.Series, numpy.ndarray]
+            If str, name of the target in X, otherwise series of labels corresponding to X
+        name: str, optional
+            Name to identify this data
+        dataset_type: ADSDataset, optional
+            When this value is available, would be used to evaluate the ads task
+            type
+        kwargs:
+            Additional keyword arguments that would be passed to the underlying Pandas read API.
+
+        Returns
+        -------
+        ads_data: ads.common.data.ADSData
+            A built ADSData object
+
+        Examples
+        --------
+        >>> data = open_csv("my.csv")
+
+        >>> data_ads = ADSData(data, 'target').build(data, 'target')
+        """
+        if X is None or y is None:
+            raise ValueError("Both X and y are required.")
+        if _is_dask_dataframe(X):
+            X = X.compute()
+        if _is_dask_series(y):
+            y = y.compute()
+        if dataset_type is None:
+            dataset_type = type(X)
+        if isinstance(y, str):
+            try:
+                return ADSData(
+                    X.drop(y, axis=1), X[y], name=name, dataset_type=dataset_type
+                )
+            except AttributeError:
+                raise ValueError(
+                    "If y is a string, then X must be a pandas or dask dataframe"
+                )
+        else:
+            return ADSData(X, y, name=name, dataset_type=dataset_type)
+
+    def __repr__(self):
+        return "%sShape of X:%s\nShape of y:%s" % (
+            self.name + "\n",
+            str(self.X.shape),
+            str(self.y.shape),
+        )
+
+    def to_onnxrt(
+        self, sess, idx_range=None, model=None, impute_values={}, **kwargs
+    ):  # pragma: no cover
+        r"""
+        Returns itself formatted as an input for the onnxruntime session inputs passed in.
+
+        Parameters
+        ----------
+        sess: Session
+            The session object
+        idx_range: Range
+            The range of inputs to convert to onnx
+        model: SupportedModel
+            A model that supports being serialized for the onnx runtime.
+        kwargs: additional keyword arguments
+
+            - sess_inputs - Pass in the output from onnxruntime.InferenceSession("model.onnx").get_inputs()
+            - input_dtypes (list) - If sess_inputs cannot be passed in, pass in the numpy dtypes of each input
+            - input_shapes (list) - If sess_inputs cannot be passed in, pass in the shape of each input
+            - input_names (list) -If sess_inputs cannot be passed in, pass in the name of each input
+
+        Returns
+        -------
+        ort: Array
+            array of inputs formatted for the given session.
+        """
+        if model._underlying_model in ["torch"]:
+            sess_inputs = sess.get_inputs()
+            in_shape, in_name, in_type = [], [], []
+            for i, ftr in enumerate(sess_inputs):
+                in_type.append(ftr.type)
+                in_shape.append(ftr.shape)
+                in_name.append(ftr.name)
+            ret = {}
+            for i, name in enumerate(in_name):
+                idx_range = (0, len(self.X)) if idx_range is None else idx_range
+                batch_size = idx_range[1] - idx_range[0]
+                ret[name] = (
+                    self.X[:batch_size]
+                    .reshape([batch_size] + list(self.X[:1].shape))
+                    .detach()
+                    .cpu()
+                    .numpy()
+                    .astype(np.float32)
+                )
+            return ret
+        elif model._underlying_model in ["automl"]:
+            X_trans = model._onnx_data_transformer(
+                X=self.X, impute_values=impute_values
+            )
+            inputs = {}
+            for idx, c in enumerate(X_trans.columns):
+                inputs[sess.get_inputs()[idx].name] = (
+                    X_trans[c]
+                    .values.reshape((X_trans.shape[0], 1))
+                    .astype(X_trans.dtypes[idx])
+                )
+            return inputs
+        elif model._underlying_model in ["lightgbm", "xgboost", "sklearn"]:
+            idx_range = (0, len(self.X)) if idx_range is None else idx_range
+            inputs = []
+            for name, row in self.X[idx_range[0] : idx_range[1]].iterrows():
+                inputs.append(list(row))
+            return {"input": inputs}

ads/common/decorator/__init__.py

@@ -0,0 +1,9 @@
+#!/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 ads.common.decorator.require_nonempty_arg import require_nonempty_arg
+from ads.common.decorator.argument_to_case import argument_to_case
+from ads.common.decorator.deprecate import deprecated
+from ads.common.decorator.runtime_dependency import runtime_dependency

ads/common/decorator/argument_to_case.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2022 Oracle and its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""
+The module that provides the decorator helping to convert function arguments
+to specific case (lower/upper).
+
+Examples
+--------
+>>> @argument_to_case("lower", ["name"])
+... def test_function(name: str, last_name: str)
+...     print(name)
+...
+>>> test_function("myname", "mylastname")
+... MYNAME
+"""
+
+import inspect
+from copy import copy
+from enum import Enum
+from functools import wraps
+from typing import Callable, List
+
+from .utils import _get_original_func
+
+
+class ArgumentCase(Enum):
+    LOWER = "lower"
+    UPPER = "upper"
+
+
+def argument_to_case(case: ArgumentCase, arguments: List[str]):
+    """The decorator helping to convert function arguments to specific case.
+
+    Parameters
+    ----------
+    case: ArgumentCase
+        The case to convert specific arguments.
+    arguments: List[str]
+        The list of arguments to convert to specific case.
+
+    Examples
+    --------
+    >>> @argument_to_case("lower", ["name"])
+    ... def test_function(name: str, last_name: str)
+    ...     print(name)
+    ...
+    >>> test_function("myname", "mylastname")
+    ... MYNAME
+    """
+
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Retrieving the original function from the decorated one.
+            # This is necessary when the chain of decorators is used.
+            # The only original function arguments should be processed.
+            original_func = _get_original_func(func)
+            # Getting the original function arguments
+            func_args = inspect.getfullargspec(original_func).args
+            # Saving original args and kwargs.
+            new_args = list(copy(args))
+            new_kwargs = copy(kwargs)
+            # Converting args and kwargs to the specific case.
+            for func_arg in func_args:
+                if func_arg in arguments:
+                    if func_arg in new_kwargs:
+                        new_kwargs[func_arg] = (
+                            new_kwargs[func_arg].lower()
+                            if case == ArgumentCase.LOWER
+                            else new_kwargs[func_arg].upper()
+                        )
+                    else:
+                        arg_index = func_args.index(func_arg)
+                        if arg_index >= 0:
+                            new_args[arg_index] = (
+                                new_args[arg_index].lower()
+                                if case == ArgumentCase.LOWER
+                                else new_args[arg_index].upper()
+                            )
+            return func(*new_args, **new_kwargs)
+
+        return wrapper
+
+    return decorator

ads/common/decorator/deprecate.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2021, 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+import warnings
+from enum import Enum
+from functools import wraps
+
+
+class NotSupportedError(Exception):   # pragma: no cover
+    pass
+
+
+class TARGET_TYPE(Enum):
+    CLASS = "Class"
+    METHOD = "Method"
+    ATTRIBUTE = "Attribute"
+
+
+def deprecated(
+    deprecated_in: str = None,
+    removed_in: str = None,
+    details: str = None,
+    target_type: str = None,
+    raise_error: bool = False,
+):
+    """This is a decorator which can be used to mark functions
+    as deprecated. It will result in a warning being emitted
+    when the function is used.
+
+    Parameters
+    ----------
+    deprecated_in: `str`
+        Version of ADS where this function deprecated.
+    removed_in: `str`
+        Future version where this function will be removed.
+    details: `str`
+        More information to be shown.
+    """
+
+    def decorator(target):
+        @wraps(target)
+        def wrapper(*args, **kwargs):
+            if target.__name__ == "__init__":
+                _target_type = target_type or TARGET_TYPE.CLASS.value
+                target_name = target.__qualname__.split(".")[0]
+            else:
+                _target_type = target_type or TARGET_TYPE.METHOD.value
+                target_name = target.__name__
+            if deprecated_in:
+                msg = (
+                    f"{_target_type} {target_name} is "
+                    f"deprecated in {deprecated_in} and will be "
+                    f"removed in {removed_in if removed_in else 'a future release'}."
+                    f"{'' if not details else ' ' + details}"
+                )
+            else:
+                msg = details
+            if raise_error:
+                raise NotSupportedError(msg)
+            else:
+                warnings.warn(msg, DeprecationWarning, stacklevel=2)
+            return target(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

ads/common/decorator/require_nonempty_arg.py

@@ -0,0 +1,65 @@
+#!/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/
+
+import inspect
+from functools import wraps
+from typing import Any, Callable, List, Union
+
+from ads.common.decorator.utils import _get_original_func
+
+
+def require_nonempty_arg(
+    arg_name: Union[str, List[str]], error_msg: str = "A required argument is empty"
+) -> Callable:
+    """
+    A decorator to ensure that a specific argument of a function is not empty.
+
+    Parameters
+    ----------
+    arg_name (Union[str, List[str]]): The name of the argument or the list of the arguments to check.
+    error_msg (str, optional)
+        The error message to raise if the check fails.
+
+    Returns
+    -------
+    Callable
+        A wrapped function that includes the check.
+
+    Raises
+    ------
+    ValueError
+        If the specified argument is empty.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Retrieving the original function from the decorated one.
+            # This is necessary when the chain of decorators is used.
+            # The only original function arguments should be processed.
+            original_func = _get_original_func(func)
+
+            # Get the signature of the function
+            sig = inspect.signature(original_func)
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            # Check if the argument is present and not empty
+            if isinstance(arg_name, str):
+                arguments_to_check = [arg_name]
+            else:
+                arguments_to_check = arg_name
+
+            if not any(
+                check_name in bound_args.arguments and bound_args.arguments[check_name]
+                for check_name in arguments_to_check
+            ):
+                raise ValueError(error_msg)
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

ads/common/decorator/runtime_dependency.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2021, 2024 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""
+The module that provides the decorator helping to add runtime dependencies in functions.
+
+Examples
+--------
+>>> @runtime_dependency(module="pandas", short_name="pd")
+... def test_function()
+...     print(pd)
+
+>>> @runtime_dependency(module="pandas", object="DataFrame", short_name="df")
+... def test_function()
+...     print(df)
+
+>>> @runtime_dependency(module="pandas", short_name="pd")
+... @runtime_dependency(module="pandas", object="DataFrame", short_name="df")
+... def test_function()
+...     print(df)
+...     print(pd)
+
+>>> @runtime_dependency(module="pandas", object="DataFrame", short_name="df", install_from="ads[optional]")
+... def test_function()
+...     pass
+
+>>> @runtime_dependency(module="pandas", object="DataFrame", short_name="df", err_msg="Custom error message.")
+... def test_function()
+...     pass
+"""
+
+import importlib
+import logging
+from functools import wraps
+from typing import Any, Callable
+
+from .utils import _get_original_func
+
+logger = logging.getLogger(__name__)
+
+MODULE_NOT_FOUND_ERROR = (
+    "The `{module}` module was not found. Please run `pip install {package}`."
+)
+IMPORT_ERROR = "Cannot import name `{object}` from `{module}`."
+
+
+class OptionalDependency:
+    LABS = "oracle-ads[labs]"
+    BOOSTED = "oracle-ads[boosted]"
+    NOTEBOOK = "oracle-ads[notebook]"
+    TEXT = "oracle-ads[text]"
+    VIZ = "oracle-ads[viz]"
+    DATA = "oracle-ads[data]"
+    OPCTL = "oracle-ads[opctl]"
+    MYSQL = "oracle-ads[mysql]"
+    BDS = "oracle-ads[bds]"
+    PYTORCH = "oracle-ads[torch]"
+    TENSORFLOW = "oracle-ads[tensorflow]"
+    GEO = "oracle-ads[geo]"
+    ONNX = "oracle-ads[onnx]"
+    OPTUNA = "oracle-ads[optuna]"
+    SPARK = "oracle-ads[spark]"
+    HUGGINGFACE = "oracle-ads[huggingface]"
+    FORECAST = "oracle-ads[forecast]"
+    FEATURE_STORE_MARKETPLACE = "oracle-ads[feature-store-marketplace]"
+    PII = "oracle-ads[pii]"
+    FEATURE_STORE = "oracle-ads[feature-store]"
+    GRAPHVIZ = "oracle-ads[graphviz]"
+    MLM_INSIGHTS = "oracle-ads[mlm_insights]"
+
+
+def runtime_dependency(
+    module: str,
+    short_name: str = "",
+    object: str = None,
+    install_from: str = None,
+    err_msg: str = "",
+    is_for_notebook_only=False,
+):
+    """The decorator which is helping to add runtime dependencies to functions.
+
+    Parameters
+    ----------
+    module: str
+        The module name to be imported.
+    short_name: (str, optional). Defaults to empty string.
+        The short name for the imported module.
+    object: (str, optional). Defaults to None.
+        The name of the object to be imported. Can be a function or a class, or
+        any variable provided by module.
+    install_from: (str, optional). Defaults to None.
+        The parameter helping to answer from where the required dependency can be installed.
+    err_msg: (str, optional). Defaults to empty string.
+        The custom error message.
+    is_for_notebook_only: (bool, optional). Defaults to False.
+        If the value of this flag is set to True, the dependency will be added only
+        in case when the current environment is a jupyter notebook.
+
+    Raises
+    ------
+    ModuleNotFoundError
+        In case if requested module not found.
+    ImportError
+        In case if object cannot be imported from the module.
+
+    Examples
+    --------
+    >>> @runtime_dependency(module="pandas", short_name="pd")
+    ... def test_function()
+    ...     print(pd)
+
+    >>> @runtime_dependency(module="pandas", object="DataFrame", short_name="df")
+    ... def test_function()
+    ...     print(df)
+
+    >>> @runtime_dependency(module="pandas", short_name="pd")
+    ... @runtime_dependency(module="pandas", object="DataFrame", short_name="df")
+    ... def test_function()
+    ...     print(df)
+    ...     print(pd)
+
+    >>> @runtime_dependency(module="pandas", object="DataFrame", short_name="df", install_from="ads[optional]")
+    ... def test_function()
+    ...     pass
+
+    >>> @runtime_dependency(module="pandas", object="DataFrame", short_name="df", err_msg="Custom error message.")
+    ... def test_function()
+    ...     pass
+    """
+
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            from ads.common.utils import is_notebook
+
+            if not is_for_notebook_only or is_notebook():
+                assert module, "The parameter `module` must be provided."
+                assert isinstance(
+                    module, str
+                ), "The parameter `module` must be a string."
+                try:
+                    _package_name = module.split(".")[0]
+                    # importing module
+                    _module = importlib.import_module(module)
+                    # checking if object parameter is specified then inporting
+                    # the object from the module. The object can be a function
+                    # or a class or any module vatiable.
+                    _module = getattr(_module, object) if object else _module
+                    # retrieving the original function from the decorated one.
+                    # This is necessary when the chain of decorators is used.
+                    # The only original function should be injected with the
+                    # dependency.
+                    original_func = _get_original_func(func)
+                    _module_name = module.split(".")[-1]
+                    # Injecting the imported module into global variables of the
+                    # original function.
+                    original_func.__globals__[
+                        short_name or object or _module_name
+                    ] = _module
+                except ModuleNotFoundError:
+                    raise ModuleNotFoundError(
+                        err_msg
+                        or MODULE_NOT_FOUND_ERROR.format(
+                            module=module, package=install_from or _package_name
+                        )
+                    )
+                except AttributeError:
+                    raise ImportError(
+                        err_msg or IMPORT_ERROR.format(object=object, module=module)
+                    )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

ads/common/decorator/threaded.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2021, 2024 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+
+import concurrent.futures
+import functools
+import logging
+from typing import Optional
+
+from git import Optional
+
+from ads.config import THREADED_DEFAULT_TIMEOUT
+
+logger = logging.getLogger(__name__)
+
+# Create a global thread pool with a maximum of 10 threads
+thread_pool = concurrent.futures.ThreadPoolExecutor(max_workers=10)
+
+
+class TimeoutError(Exception):
+    """
+    Custom exception to be raised when a function times out.
+
+    Attributes
+    ----------
+    message : str
+        The error message describing what went wrong.
+
+    Parameters
+    ----------
+    message : str
+        The error message.
+    """
+
+    def __init__(
+        self,
+        func_name: str,
+        timeout: int,
+        message: Optional[str] = "The operation could not be completed in time.",
+    ):
+        super().__init__(
+            f"{message} The function '{func_name}' exceeded the timeout of {timeout} seconds."
+        )
+
+
+def threaded(timeout: Optional[int] = THREADED_DEFAULT_TIMEOUT):
+    """
+    Decorator to run a function in a separate thread using a global thread pool.
+
+    Parameters
+    ----------
+    timeout (int, optional)
+        The maximum time in seconds to wait for the function to complete.
+        If the function does not complete within this time, "timeout" is returned.
+
+    Returns
+    -------
+    function: The wrapped function that will run in a separate thread with the specified timeout.
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            """
+            Wrapper function to submit the decorated function to the thread pool and handle timeout.
+
+            Parameters
+            ----------
+                *args: Positional arguments to pass to the decorated function.
+                **kwargs: Keyword arguments to pass to the decorated function.
+
+            Returns
+            -------
+            Any: The result of the decorated function if it completes within the timeout.
+
+            Raise
+            -----
+            TimeoutError
+                In case of the function exceeded the timeout.
+            """
+            future = thread_pool.submit(func, *args, **kwargs)
+            try:
+                return future.result(timeout=timeout)
+            except concurrent.futures.TimeoutError as ex:
+                logger.debug(
+                    f"The function '{func.__name__}' "
+                    f"exceeded the timeout of {timeout} seconds. "
+                    f"{ex}"
+                )
+                raise TimeoutError(func.__name__, timeout)
+
+        return wrapper
+
+    return decorator