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

ads/opctl/operator/lowcode/recommender/model/factory.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+
+# Copyright (c) 2023, 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 ..constant import SupportedModels
+from ..operator_config import RecommenderOperatorConfig
+from .base_model import RecommenderOperatorBaseModel
+from .recommender_dataset import RecommenderDatasets
+from .svd import SVDOperatorModel
+
+
+class UnSupportedModelError(Exception):
+    def __init__(self, model_type: str):
+        super().__init__(
+            f"Model: `{model_type}` "
+            f"is not supported. Supported models: {SupportedModels.values()}"
+        )
+
+
+class RecommenderOperatorModelFactory:
+    """
+    The factory class helps to instantiate proper model operator based on the model type.
+    """
+
+    _MAP = {SupportedModels.SVD: SVDOperatorModel}
+
+    @classmethod
+    def get_model(
+        cls, operator_config: RecommenderOperatorConfig, datasets: RecommenderDatasets
+    ) -> RecommenderOperatorBaseModel:
+        """
+        Gets the operator model based on the model type.
+
+        Parameters
+        ----------
+        operator_config: RecommenderOperatorConfig
+            The recommender detection operator config.
+
+        datasets: RecommenderDatasets
+            Datasets for finding recommender
+
+        Returns
+        -------
+        RecommenderOperatorBaseModel
+            The recommender detection operator model.
+
+        Raises
+        ------
+        UnSupportedModelError
+            In case of not supported model.
+        """
+        model_type = SupportedModels.SVD
+        if model_type not in cls._MAP:
+            raise UnSupportedModelError(model_type)
+        return cls._MAP[model_type](config=operator_config, datasets=datasets)

ads/opctl/operator/lowcode/recommender/model/recommender_dataset.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 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 pandas as pd
+
+from ads.opctl.operator.lowcode.common.utils import load_data
+from ..operator_config import RecommenderOperatorConfig
+
+
+class RecommenderDatasets:
+    def __init__(self, config: RecommenderOperatorConfig):
+        """Instantiates the DataIO instance.
+
+        Properties
+        ----------
+        spec: RecommenderOperatorSpec
+            The recommender operator spec.
+        """
+        spec = config.spec
+        self.interactions: pd.DataFrame = load_data(getattr(spec, "interactions_data"))
+        self.users: pd.DataFrame = load_data(getattr(spec, "user_data"))
+        self.items: pd.DataFrame = load_data(getattr(spec, "item_data"))

ads/opctl/operator/lowcode/recommender/model/svd.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+# Copyright (c) 2023, 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 logging
+from typing import Dict, Tuple
+
+import pandas as pd
+import report_creator as rc
+from pandas import DataFrame
+from surprise import SVD, Dataset, Reader
+from surprise.accuracy import mae, rmse
+from surprise.model_selection import train_test_split
+
+from ..constant import SupportedMetrics
+from ..operator_config import RecommenderOperatorConfig
+from .factory import RecommenderOperatorBaseModel
+from .recommender_dataset import RecommenderDatasets
+
+logging.getLogger("report_creator").setLevel(logging.WARNING)
+
+
+class SVDOperatorModel(RecommenderOperatorBaseModel):
+    """Class representing scikit surprise SVD operator model."""
+
+    def __init__(
+        self, config: RecommenderOperatorConfig, datasets: RecommenderDatasets
+    ):
+        super().__init__(config, datasets)
+        self.interactions = datasets.interactions
+        self.users = datasets.users
+        self.items = datasets.items
+        self.user_id = config.spec.user_column
+        self.item_id = config.spec.item_column
+        self.interaction_column = config.spec.interaction_column
+        self.test_size = 0.2
+        self.algo = SVD()
+
+    def _get_recommendations(self, user_id, n):
+        all_item_ids = self.items[self.item_id].unique()
+        rated_items = self.interactions[self.interactions[self.user_id] == user_id][
+            self.item_id
+        ]
+        unrated_items = [
+            item_id for item_id in all_item_ids if item_id not in rated_items.values
+        ]
+        predictions = [self.algo.predict(user_id, item_id) for item_id in unrated_items]
+        predictions.sort(key=lambda x: x.est, reverse=True)
+        top_n_recommendations = predictions[:n]
+        return [(pred.iid, pred.est) for pred in top_n_recommendations]
+
+    def _build_model(self) -> Tuple[DataFrame, Dict]:
+        min_rating = self.interactions[self.interaction_column].min()
+        max_rating = self.interactions[self.interaction_column].max()
+        reader = Reader(rating_scale=(min_rating, max_rating))
+        data = Dataset.load_from_df(
+            self.interactions[[self.user_id, self.item_id, self.interaction_column]],
+            reader,
+        )
+        trainset, testset = train_test_split(data, test_size=self.test_size)
+        self.algo.fit(trainset)
+        predictions = self.algo.test(testset)
+
+        metric = {}
+        metric[SupportedMetrics.RMSE] = rmse(predictions, verbose=True)
+        metric[SupportedMetrics.MAE] = mae(predictions, verbose=True)
+        all_recommendations = []
+        for user_id in self.users[self.user_id]:
+            recommendations = self._get_recommendations(user_id, n=self.spec.top_k)
+            for item_id, est_rating in recommendations:
+                all_recommendations.append(
+                    {
+                        self.user_id: user_id,
+                        self.item_id: item_id,
+                        self.interaction_column: est_rating,
+                    }
+                )
+        recommendations_df = pd.DataFrame(all_recommendations)
+        return recommendations_df, metric
+
+    def _generate_report(self):
+        model_description = rc.Text(
+            "Singular Value Decomposition (SVD) is a matrix factorization technique used in recommendation systems to \
+            decompose a user-item interaction matrix into three constituent matrices. These matrices capture the \
+            latent factors that explain the observed interactions."
+        )
+        new_user_recommendations = self._get_recommendations(
+            "__new_user__", self.spec.top_k
+        )
+        new_recommendations = []
+        for item_id, est_rating in new_user_recommendations:
+            new_recommendations.append(
+                {
+                    self.user_id: "__new_user__",
+                    self.item_id: item_id,
+                    self.interaction_column: est_rating,
+                }
+            )
+        title = rc.Heading("Recommendations for new users", level=2)
+        other_sections = [title, rc.DataTable(new_recommendations)]
+        return (model_description, other_sections)
+
+    def _evaluation_metrics(self):
+        pass
+
+    def _test_data_evaluate_metrics(self):
+        pass

ads/opctl/operator/lowcode/recommender/operator_config.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 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 os
+from dataclasses import dataclass, field
+
+from ads.common.serializer import DataClassSerializable
+from ads.opctl.operator.common.operator_config import OperatorConfig, InputData
+from ads.opctl.operator.common.utils import _load_yaml_from_uri
+from ads.opctl.operator.lowcode.common.utils import find_output_dirname
+from .constant import SupportedModels
+
+
+@dataclass(repr=True)
+class OutputDirectory(DataClassSerializable):
+    """Class representing operator specification output directory details."""
+
+    url: str = None
+    name: str = None
+
+
+@dataclass(repr=True)
+class RecommenderOperatorSpec(DataClassSerializable):
+    """Class representing Recommender operator specification."""
+
+    user_data: InputData = field(default_factory=InputData)
+    item_data: InputData = field(default_factory=InputData)
+    interactions_data: InputData = field(default_factory=InputData)
+    output_directory: OutputDirectory = field(default_factory=OutputDirectory)
+    top_k: int = None
+    model_name: str = None
+    user_column: str = None
+    item_column: str = None
+    interaction_column: str = None
+    recommendations_filename: str = None
+    generate_report: bool = None
+    report_filename: str = None
+
+
+    def __post_init__(self):
+        """Adjusts the specification details."""
+        self.output_directory = self.output_directory or OutputDirectory(url=find_output_dirname(self.output_directory))
+        self.model_name = self.model_name or SupportedModels.SVD
+        self.recommendations_filename = self.recommendations_filename or "recommendations.csv"
+        # For Report Generation. When user doesn't specify defaults to True
+        self.generate_report = (
+            self.generate_report if self.generate_report is not None else True
+        )
+        self.report_filename = self.report_filename or "report.html"
+
+
+@dataclass(repr=True)
+class RecommenderOperatorConfig(OperatorConfig):
+    """Class representing Recommender operator config.
+
+    Attributes
+    ----------
+    kind: str
+        The kind of the resource. For operators it is always - `operator`.
+    type: str
+        The type of the operator. For Recommender operator it is always - `Recommender`
+    version: str
+        The version of the operator.
+    spec: RecommenderOperatorSpec
+        The Recommender operator specification.
+    """
+
+    kind: str = "operator"
+    type: str = "Recommender"
+    version: str = "v1"
+    spec: RecommenderOperatorSpec = field(default_factory=RecommenderOperatorSpec)
+
+    @classmethod
+    def _load_schema(cls) -> str:
+        """Loads operator schema."""
+        return _load_yaml_from_uri(
+            os.path.join(os.path.dirname(os.path.abspath(__file__)), "schema.yaml")
+        )

ads/opctl/operator/lowcode/recommender/schema.yaml

@@ -0,0 +1,265 @@
+kind:
+  allowed:
+    - operator
+  required: true
+  type: string
+  default: operator
+  meta:
+    description: "Which service are you trying to use? Common kinds: `operator`, `job`"
+
+version:
+  allowed:
+    - "v1"
+  required: true
+  type: string
+  default: v1
+  meta:
+    description: "Operators may change yaml file schemas from version to version, as well as implementation details. Double check the version to ensure compatibility."
+
+type:
+  required: true
+  type: string
+  default: recommender
+  meta:
+    description: "Type should always be `recommender` when using a recommender operator"
+
+
+spec:
+  required: true
+  type: dict
+  schema:
+    user_data:
+      required: true
+      type: dict
+      default: {"url": "user_data.csv"}
+      meta:
+        description: "This should contain user related attribute."
+      schema:
+        connect_args:
+          nullable: true
+          required: false
+          type: dict
+        format:
+          allowed:
+            - csv
+            - json
+            - clipboard
+            - excel
+            - feather
+            - sql_table
+            - sql_query
+            - hdf
+            - tsv
+          required: false
+          type: string
+        columns:
+          required: false
+          type: list
+          schema:
+            type: string
+        filters:
+          required: false
+          type: list
+          schema:
+            type: string
+        options:
+          nullable: true
+          required: false
+          type: dict
+        sql:
+          required: false
+          type: string
+        table_name:
+          required: false
+          type: string
+        url:
+          required: false
+          type: string
+          meta:
+            description: "The url can be local, or remote. For example: `oci://<bucket>@<namespace>/data.csv`"
+        limit:
+          required: false
+          type: integer
+
+    item_data:
+      required: true
+      type: dict
+      default: {"url": "item_data.csv"}
+      meta:
+        description: "This should contain item related attribute"
+      schema:
+        connect_args:
+          nullable: true
+          required: false
+          type: dict
+        format:
+          allowed:
+            - csv
+            - json
+            - clipboard
+            - excel
+            - feather
+            - sql_table
+            - sql_query
+            - hdf
+            - tsv
+          required: false
+          type: string
+        columns:
+          required: false
+          type: list
+          schema:
+            type: string
+        filters:
+          required: false
+          type: list
+          schema:
+            type: string
+        options:
+          nullable: true
+          required: false
+          type: dict
+        sql:
+          required: false
+          type: string
+        table_name:
+          required: false
+          type: string
+        url:
+          required: false
+          type: string
+          meta:
+            description: "The url can be local, or remote. For example: `oci://<bucket>@<namespace>/data.csv`"
+        limit:
+          required: false
+          type: integer
+
+    interactions_data:
+      required: true
+      default: {"url": "interactions_data.csv"}
+      meta:
+        description: "This should include interactions between items and users"
+      schema:
+        connect_args:
+          nullable: true
+          required: false
+          type: dict
+        format:
+          allowed:
+            - csv
+            - json
+            - clipboard
+            - excel
+            - feather
+            - sql_table
+            - sql_query
+            - hdf
+            - tsv
+          required: false
+          type: string
+        columns:
+          required: false
+          type: list
+          schema:
+            type: string
+        filters:
+          required: false
+          type: list
+          schema:
+            type: string
+        options:
+          nullable: true
+          required: false
+          type: dict
+        sql:
+          required: false
+          type: string
+        table_name:
+          required: false
+          type: string
+        url:
+          required: false
+          type: string
+          meta:
+            description: "The url can be local, or remote. For example: `oci://<bucket>@<namespace>/data.csv`"
+        limit:
+          required: false
+          type: integer
+      type: dict
+
+    top_k:
+      required: true
+      type: integer
+      default: 1
+
+    output_directory:
+      required: false
+      schema:
+        connect_args:
+          nullable: true
+          required: false
+          type: dict
+        format:
+          allowed:
+            - csv
+            - json
+            - clipboard
+            - excel
+            - feather
+            - sql_table
+            - sql_query
+            - hdf
+            - tsv
+          required: false
+          type: string
+        columns:
+          required: false
+          type: list
+          schema:
+            type: string
+        filters:
+          required: false
+          type: list
+          schema:
+            type: string
+        options:
+          nullable: true
+          required: false
+          type: dict
+        sql:
+          required: false
+          type: string
+        table_name:
+          required: false
+          type: string
+        url:
+          required: false
+          type: string
+          meta:
+            description: "The url can be local, or remote. For example: `oci://<bucket>@<namespace>/data.csv`"
+        limit:
+          required: false
+          type: integer
+      type: dict
+
+    report_filename:
+      required: false
+      type: string
+      default: report.html
+      meta:
+        description: "Placed into output_directory location. Defaults to report.html"
+
+    user_column:
+      type: string
+      required: true
+      default: "user_id"
+
+    item_column:
+      type: string
+      required: true
+      default: "item_id"
+
+    interaction_column:
+      type: string
+      required: true
+      default: "rating"

ads/opctl/operator/lowcode/recommender/utils.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2023, 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 os
+
+
+def default_signer(**kwargs):
+    os.environ["EXTRA_USER_AGENT_INFO"] = "Recommender-Operator"
+    from ads.common.auth import default_signer
+    return default_signer(**kwargs)

ads/opctl/operator/runtime/__init__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/

ads/opctl/operator/runtime/const.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2023, 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 .runtime import ContainerRuntime, PythonRuntime
+from .marketplace_runtime import MarketplacePythonRuntime
+
+RUNTIME_TYPE_MAP = {
+    ContainerRuntime.type: ContainerRuntime,
+    PythonRuntime.type: PythonRuntime,
+}
+MARKETPLACE_RUNTIME_MAP = {
+    MarketplacePythonRuntime.type: MarketplacePythonRuntime,
+}

ads/opctl/operator/runtime/container_runtime_schema.yaml

@@ -0,0 +1,50 @@
+kind:
+  allowed:
+    - operator.local
+  required: true
+  type: string
+  meta:
+    description: "The operator local runtime. Kind should always be `operator.local` when using an operator with local container runtime."
+version:
+  allowed:
+    - "v1"
+  required: true
+  type: string
+  meta:
+    description: "Operator local runtime may change yaml file schemas from version to version, as well as implementation details. Double check the version to ensure compatibility."
+type:
+  allowed:
+    - container
+  required: true
+  type: string
+  meta:
+    description: "Type should always be `container` when using an operator with local container runtime."
+spec:
+  required: true
+  type: dict
+  schema:
+    image:
+      nullable: true
+      required: false
+      type: string
+      default: image:tag
+      meta:
+        description: "The image to run the operator. By default will be used the operator name with latest tag."
+    env:
+      nullable: true
+      required: false
+      type: list
+      schema:
+        type: dict
+        schema:
+          name:
+            type: string
+          value:
+            type:
+              - number
+              - string
+    volume:
+      required: false
+      type:
+        - string
+        - list

ads/opctl/operator/runtime/marketplace_runtime.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+
+# 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/
+
+from dataclasses import dataclass
+from typing import ClassVar, Dict
+
+from ads.common.extended_enum import ExtendedEnum
+from ads.opctl.operator.common.operator_yaml_generator import YamlGenerator
+from ads.opctl.operator.common.utils import _load_yaml_from_uri
+from ads.opctl.operator.runtime.runtime import Runtime
+
+
+class OPERATOR_MARKETPLACE_LOCAL_RUNTIME_TYPE(ExtendedEnum):
+    PYTHON = "python"
+
+
+MARKETPLACE_OPERATOR_LOCAL_KIND = "marketplace.local"
+
+
+@dataclass(repr=True)
+class MarketplacePythonRuntime(Runtime):
+    """Represents a python operator runtime."""
+
+    _schema: ClassVar[str] = "python_marketplace_runtime_schema.yaml"
+    type: str = OPERATOR_MARKETPLACE_LOCAL_RUNTIME_TYPE.PYTHON
+    version: str = "v1"
+
+    def __init__(self, **kwargs):
+        kwargs.update(kind=MARKETPLACE_OPERATOR_LOCAL_KIND)
+        self.spec = YamlGenerator(
+            schema=_load_yaml_from_uri(
+                __file__.replace("marketplace_runtime.py", self._schema)
+            )
+        ).generate_example_dict()
+
+        super().__init__(**kwargs)
+
+    @classmethod
+    def init(cls, **kwargs: Dict) -> "MarketplacePythonRuntime":
+        """Initializes a starter specification for the runtime.
+
+        Returns
+        -------
+        PythonRuntime
+            The runtime instance.
+        """
+        instance = cls()
+        return instance

ads/opctl/operator/runtime/python_marketplace_runtime_schema.yaml

@@ -0,0 +1,21 @@
+kind:
+  allowed:
+    - marketplace.local
+  required: true
+  type: string
+  meta:
+    description: "The operator marketplace local runtime. Kind should always be `operator.local` when using an operator with local python runtime."
+version:
+  allowed:
+    - "v1"
+  required: true
+  type: string
+  meta:
+    description: "Operator local runtime may change yaml file schemas from version to version, as well as implementation details. Double check the version to ensure compatibility."
+type:
+  allowed:
+    - python
+  required: true
+  type: string
+  meta:
+    description: "Type should always be `python` when using an operator with local python runtime."