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

ads/feature_store/service/oci_dataset_job.py

@@ -0,0 +1,199 @@
+#!/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 datetime
+import logging
+import time
+
+from feature_store_client.feature_store.models import (
+    CreateDatasetJobDetails,
+    CompleteDatasetJobDetails,
+    DatasetJob,
+)
+
+from ads.feature_store.mixin.oci_feature_store import OCIFeatureStoreMixin
+
+logger = logging.getLogger(__name__)
+
+SLEEP_INTERVAL = 3
+
+
+class OCIDatasetJob(OCIFeatureStoreMixin, DatasetJob):
+    """Represents an OCI Data Science DatasetJob.
+    This class contains all attributes of the `oci.data_science.models.DatasetJob`.
+    The main purpose of this class is to link the `oci.data_science.models.DatasetJob`
+    and the related client methods.
+    Linking the `DatasetJob` (payload) to Create methods.
+
+    The `OCIDatasetJob` can be initialized by unpacking the properties stored in a dictionary:
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "display_name": "<dataset_job_display_name>",
+            "description": "<dataset_job_description>",
+            "feature_store_id":"<feature_store_id>",
+        }
+        dataset_job = OCIDatasetJob(**properties)
+
+    The properties can also be OCI REST API payload, in which the keys are in camel format.
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "display_name": "<dataset_job_display_name>",
+            "description": "<dataset_job_description>",
+            "feature_store_id":"<feature_store_id>",
+        }
+        dataset_job = OCIDatasetJob(**properties)
+
+    Methods
+    -------
+    create(self) -> "OCIDatasetJob"
+        Creates dataset job.
+    from_id(cls, ocid: str) -> "OCIDatasetJob":
+        Gets existing dataset by Id.
+    Examples
+    --------
+    >>> oci_dataset_job = OCIDatasetJob.from_id("<dataset_job_id>")
+    >>> oci_dataset_job.create()
+    """
+
+    TERMINAL_STATES = [
+        DatasetJob.LIFECYCLE_STATE_SUCCEEDED,
+        DatasetJob.LIFECYCLE_STATE_FAILED,
+    ]
+
+    def __init__(self, **kwargs) -> None:
+        """Initialize a OCIDatasetJob object.
+
+        Parameters
+        ----------
+        kwargs:
+            Same as kwargs in feature_store.models.OCIDatasetJob.
+            Keyword arguments are passed into OCI feature group job model to initialize the properties.
+
+        """
+
+        super().__init__(**kwargs)
+
+    def create(self) -> "OCIDatasetJob":
+        """Creates dataset resource.
+
+        Returns
+        -------
+        OCIDatasetJob
+            The `OCIDatasetJob` instance (self), which allows chaining additional method.
+        """
+        if not self.compartment_id:
+            raise ValueError("The `compartment_id` must be specified.")
+        dataset_job_details = self.to_oci_model(CreateDatasetJobDetails)
+        return self.update_from_oci_model(
+            self.client.create_dataset_job(dataset_job_details).data
+        )
+
+    @property
+    def status(self) -> str:
+        """Lifecycle status
+
+        Returns
+        -------
+        str
+            Status in a string.
+        """
+        return self.lifecycle_state
+
+    def watch(self, interval: float = SLEEP_INTERVAL) -> "OCIDatasetJob":
+        """Watches the dataset job run until it finishes.
+        Before the job start running, this method will output the dataset job run status.
+        Once the job start running, the logs will be streamed until the job is success, failed or cancelled.
+
+        Parameters
+        ----------
+        interval : int
+            Time interval in seconds between each request to update the logs.
+            Defaults to 3 (seconds).
+
+        """
+
+        def stop_condition():
+            """Stops the log once the job is in a terminal state."""
+            self.sync()
+            if self.lifecycle_state not in self.TERMINAL_STATES:
+                return False
+            # Stop if time_finished is not available.
+            if not self.time_finished:
+                return True
+            # Stop only if time_finished is over 1 minute ago.
+            # This is for the time delay between dataset job run stopped and the logs appear in oci logging.
+            if (
+                datetime.datetime.now(self.time_finished.tzinfo)
+                - datetime.timedelta(minutes=1)
+                > self.time_finished
+            ):
+                return True
+            return False
+
+        logger.info(f"Dataset job OCID: {self.job.id}")
+        logger.info(f"Dataset job run OCID: {self.id}")
+
+        status = ""
+        while not stop_condition():
+            status = self._check_and_print_status(status)
+            # Break and stream logs if job has log ID and started.
+            # Otherwise, keep watching the status until job terminates.
+            if self.time_started and self.log_id:
+                break
+            time.sleep(interval)
+        self._check_and_print_status(status)
+        return self
+
+    def _job_run_status_text(self) -> str:
+        details = f", {self.lifecycle_details}" if self.lifecycle_details else ""
+        return f"Job Run {self.lifecycle_state}" + details
+
+    def _check_and_print_status(self, prev_status) -> str:
+        status = self._job_run_status_text()
+        if status != prev_status:
+            if self.lifecycle_state in self.TERMINAL_STATES and self.time_finished:
+                timestamp = self.time_finished
+            else:
+                timestamp = datetime.datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S")
+        return status
+
+    @classmethod
+    def from_id(cls, id: str) -> "OCIDatasetJob":
+        """Gets dataset resource  by id.
+
+        Parameters
+        ----------
+        id: str
+            The id of the dataset resource.
+
+        Returns
+        -------
+        OCIDatasetJob
+            An instance of `OCIDatasetJob`.
+        """
+        if not id:
+            raise ValueError("DatasetJob id not provided.")
+        return super().from_ocid(id)
+
+    def complete_dataset_job(self) -> "OCIDatasetJob":
+        """Completes a dataset job.
+
+        Returns
+        -------
+        OCIDatasetJob
+            The `OCIDatasetJob` instance (self).
+        """
+        return self.update_from_oci_model(
+            self.client.complete_dataset_job(
+                self.id, self.to_oci_model(CompleteDatasetJobDetails)
+            ).data
+        )

ads/feature_store/service/oci_entity.py

@@ -0,0 +1,125 @@
+#!/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 feature_store_client.feature_store as fs
+from feature_store_client.feature_store.models import (
+    CreateEntityDetails,
+    UpdateEntityDetails,
+    Entity,
+)
+
+from ads.feature_store.mixin.oci_feature_store import OCIFeatureStoreMixin
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class OCIEntity(OCIFeatureStoreMixin, Entity):
+    """Represents an OCI Data Science Entity.
+    This class contains all attributes of the `oci.data_science.models.Entity`.
+    The main purpose of this class is to link the `oci.data_science.models.Entity`
+    and the related client methods.
+    Linking the `Transformation` (payload) to Create/Update/Get/List/Delete methods.
+
+    The `OCIEntity` can be initialized by unpacking the properties stored in a dictionary:
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "name": "<entity_name>",
+            "description": "<entity_description>",
+            "feature_store_id":"<feature_store_id>",
+        }
+        transformation_model = OCIEntity(**properties)
+
+    The properties can also be OCI REST API payload, in which the keys are in camel format.
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "name": "<entity_name>",
+            "description": "<entity_description>",
+            "feature_store_id":"<feature_store_id>",
+        }
+        transformation_model = OCIEntity(**properties)
+
+    Methods
+    -------
+    create(self) -> "OCIEntity"
+        Creates entity.
+    delete(self):
+        Deletes entity.
+    from_id(cls, ocid: str) -> "OCIEntity":
+        Gets existing entity by Id.
+    Examples
+    --------
+    >>> oci_entity = OCIEntity.from_id("<entity_id>")
+    >>> oci_entity.delete()
+    """
+
+    # Overriding default behavior
+    @classmethod
+    def init_client(cls, **kwargs) -> fs.feature_store_client.FeatureStoreClient:
+        client = super().init_client(**kwargs)
+
+        # Define the list entities callable to list the resources
+        cls.OCI_LIST_METHOD = client.list_entities
+
+        return client
+
+    def create(self) -> "OCIEntity":
+        """Creates entity resource.
+
+        Returns
+        -------
+        OCIEntity
+            The `OCIEntity` instance (self), which allows chaining additional method.
+        """
+        if not self.compartment_id:
+            raise ValueError("The `compartment_id` must be specified.")
+        entity_details = self.to_oci_model(CreateEntityDetails)
+        return self.update_from_oci_model(
+            self.client.create_entity(entity_details).data
+        )
+
+    def update(self) -> "OCIEntity":
+        """Updates entity.
+
+        Returns
+        -------
+        OCIEntity
+            The `OCIEntity` instance (self).
+        """
+        return self.update_from_oci_model(
+            self.client.update_entity(
+                self.id, self.to_oci_model(UpdateEntityDetails)
+            ).data
+        )
+
+    @classmethod
+    def from_id(cls, id: str) -> "OCIEntity":
+        """Gets entity resource  by id.
+
+        Parameters
+        ----------
+        id: str
+            The id of the entity resource.
+
+        Returns
+        -------
+        OCIEntity
+            An instance of `OCIEntity`.
+        """
+        if not id:
+            raise ValueError("Entity id not provided.")
+        return super().from_ocid(id)
+
+    def delete(self):
+        """Removes entity"""
+
+        self.client.delete_entity(self.id)

ads/feature_store/service/oci_feature_group.py

@@ -0,0 +1,164 @@
+#!/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 datetime
+import pandas as pd
+from ads.common import utils
+
+from feature_store_client.feature_store.models import (
+    CreateFeatureGroupDetails,
+    UpdateFeatureGroupDetails,
+    FeatureGroup,
+)
+
+from ads.feature_store.mixin.oci_feature_store import OCIFeatureStoreMixin
+
+
+class OCIFeatureGroup(OCIFeatureStoreMixin, FeatureGroup):
+    """Represents an OCI Data Science feature group.
+    This class contains all attributes of the `oci.data_science.models.FeatureDefinition`.
+    The main purpose of this class is to link the `oci.data_science.models.FeatureDefinition`
+    and the related client methods.
+    Linking the `FeatureGroup` (payload) to Create/Update/Get/List/Delete methods.
+
+    The `OCIFeatureGroup` can be initialized by unpacking the properties stored in a dictionary:
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "display_name": "<feature_group_name>",
+            "description": "<feature_group_description>",
+            "feature_store_id": <feature_store_id>
+            "entity_id": "<entity id>",
+            "input_feature_details": "",
+            "primary_keys": []
+        }
+        feature_group = OCIFeatureGroup(**properties)
+
+    The properties can also be OCI REST API payload, in which the keys are in camel format.
+
+    .. code-block:: python
+
+        payload = {
+            "compartmentId": "<compartment_ocid>",
+            "displayName": "<feature_group_name>",
+            "description": "<feature_group_description>",
+            "featureStoreId": <feature_store_id>
+            "entityId": "<entity id>",
+            "inputFeatureDetails": "",
+            "primaryKeys": []
+        }
+        feature_group = OCIFeatureGroup(**payload)
+
+    Methods
+    -------
+    create(self) -> "OCIFeatureGroup"
+        Creates feature group
+    delete(self) -> "OCIFeatureGroup":
+        Deletes feature group
+    update(self) -> "OCIFeatureGroup":
+        Updates feature group
+    from_id(cls, ocid: str) -> "OCIFeatureGroup":
+        Gets feature group by OCID.
+    Examples
+    --------
+    >>> self = OCIFeatureGroup.from_id("<feature_group_id>")
+    >>> self.description = "A brand new description"
+    >>> self.delete()
+    """
+
+    def create(self) -> "OCIFeatureGroup":
+        """Creates feature group on OCI Data Science platform
+
+        Returns
+        -------
+        OCIFeatureGroup
+            The OCIFeatureGroup instance (self), which allows chaining additional method.
+        """
+        if not self.compartment_id:
+            raise ValueError(
+                "`compartment_id` must be specified for the feature group."
+            )
+
+        if not self.feature_store_id:
+            raise ValueError(
+                "`feature_store_id` must be specified for the feature group."
+            )
+
+        if not self.entity_id:
+            raise ValueError("`entity_id` must be specified for the feature group.")
+
+        if not self.name:
+            timestamp = datetime.datetime.now().strftime("%Y%m%d-%H%M")
+            self.name = f"feature-group-{timestamp}"
+
+        feature_group_details = self.to_oci_model(CreateFeatureGroupDetails)
+        return self.update_from_oci_model(
+            self.client.create_feature_group(feature_group_details).data
+        )
+
+    def update(self) -> "OCIFeatureGroup":
+        """Updates feature group.
+
+        Returns
+        -------
+        OCIFeatureGroup
+            The `OCIFeatureGroup` instance (self).
+        """
+        return self.update_from_oci_model(
+            self.client.update_feature_group(
+                self.to_oci_model(UpdateFeatureGroupDetails), self.id
+            ).data
+        )
+
+    def delete(self):
+        """Removes feature group
+
+        Returns
+        -------
+        None
+        """
+        self.client.delete_feature_group(self.id)
+
+    def to_df(self):
+        return pd.DataFrame.from_records([self.to_df_record()])
+
+    def to_df_record(self):
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "time_created": self.time_created.strftime(utils.date_format),
+            "time_updated": self.time_updated.strftime(utils.date_format),
+            "lifecycle_state": self.lifecycle_state,
+            "created_by": f"...{self.created_by[-6:]}",
+            "compartment_id": f"...{self.compartment_id[-6:]}",
+            "primary_keys": self.primary_keys,
+            "feature_store_id": self.feature_store_id,
+            "entity_id": self.entity_id,
+            "input_feature_details": self.input_feature_details,
+            "expectation_details": self.expectation_details,
+            "statistics_config": self.statistics_config,
+        }
+
+    @classmethod
+    def from_id(cls, id: str) -> "OCIFeatureGroup":
+        """Gets feature group resource  by id.
+
+        Parameters
+        ----------
+        id: str
+            The id of the feature group resource.
+
+        Returns
+        -------
+        OCIFeatureStore
+            An instance of `OCIFeatureStore`.
+        """
+        if not id:
+            raise ValueError("feature group id not provided.")
+        return super().from_ocid(id)

ads/feature_store/service/oci_feature_group_job.py

@@ -0,0 +1,214 @@
+#!/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 datetime
+import logging
+import time
+
+import feature_store_client.feature_store as fs
+from feature_store_client.feature_store.models import (
+    CreateFeatureGroupJobDetails,
+    CompleteFeatureGroupJobDetails,
+    FeatureGroupJob,
+    DatasetJob,
+)
+
+from ads.feature_store.mixin.oci_feature_store import OCIFeatureStoreMixin
+
+logger = logging.getLogger(__name__)
+
+SLEEP_INTERVAL = 3
+
+
+class OCIFeatureGroupJob(OCIFeatureStoreMixin, FeatureGroupJob):
+    """Represents an OCI Data Science FeatureGroupJob.
+    This class contains all attributes of the `oci.data_science.models.FeatureGroupJob`.
+    The main purpose of this class is to link the `oci.data_science.models.FeatureGroupJob`
+    and the related client methods.
+    Linking the `FeatureGroupJob` (payload) to Create methods.
+
+    The `OCIFeatureGroupJob` can be initialized by unpacking the properties stored in a dictionary:
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "display_name": "<feature_definition_job_display_name>",
+            "description": "<feature_definition_job_description>",
+            "feature_store_id":"<feature_store_id>",
+        }
+        feature_definition_job = OCIFeatureGroupJob(**properties)
+
+    The properties can also be OCI REST API payload, in which the keys are in camel format.
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "display_name": "<feature_definition_job_display_name>",
+            "description": "<feature_definition_job_description>",
+            "feature_store_id":"<feature_store_id>",
+        }
+        feature_definition_job = OCIFeatureGroupJob(**properties)
+
+    Methods
+    -------
+    create(self) -> "OCIFeatureGroupJob"
+        Creates feature definition job.
+    from_id(cls, ocid: str) -> "OCIFeatureGroupJob":
+        Gets existing feature definition run by Id.
+    Examples
+    --------
+    >>> oci_feature_definition_job = OCIFeatureGroupJob.from_id("<feature_definition_job_id>")
+    >>> oci_feature_definition_job.create()
+    """
+
+    TERMINAL_STATES = [
+        DatasetJob.LIFECYCLE_STATE_SUCCEEDED,
+        DatasetJob.LIFECYCLE_STATE_FAILED,
+    ]
+
+    def __init__(self, **kwargs) -> None:
+        """Initialize a OCIFeatureGroupJob object.
+
+        Parameters
+        ----------
+        kwargs:
+            Same as kwargs in feature_store.models.OCIFeatureGroupJob.
+            Keyword arguments are passed into OCI feature group job model to initialize the properties.
+
+        """
+
+        super().__init__(**kwargs)
+
+    # Overriding default behavior
+    @classmethod
+    def init_client(cls, **kwargs) -> fs.feature_store_client.FeatureStoreClient:
+        client = super().init_client(**kwargs)
+
+        # Define the list entities callable to list the resources
+        cls.OCI_LIST_METHOD = client.list_feature_group_jobs
+
+        return client
+
+    def create(self) -> "OCIFeatureGroupJob":
+        """Creates feature definition resource.
+
+        Returns
+        -------
+        OCIFeatureGroupJob
+            The `OCIFeatureGroupJob` instance (self), which allows chaining additional method.
+        """
+        if not self.compartment_id:
+            raise ValueError("The `compartment_id` must be specified.")
+        feature_definition_job_details = self.to_oci_model(CreateFeatureGroupJobDetails)
+        return self.update_from_oci_model(
+            self.client.create_feature_group_job(feature_definition_job_details).data
+        )
+
+    @property
+    def status(self) -> str:
+        """Lifecycle status
+
+        Returns
+        -------
+        str
+            Status in a string.
+        """
+        return self.lifecycle_state
+
+    def _job_run_status_text(self) -> str:
+        details = f", {self.lifecycle_details}" if self.lifecycle_details else ""
+        return f"Job Run {self.lifecycle_state}" + details
+
+    def watch(self, interval: float = SLEEP_INTERVAL) -> "OCIFeatureGroupJob":
+        """Watches the feature definition job run until it finishes.
+        Before the job start running, this method will output the feature definition job run status.
+        Once the job start running, the logs will be streamed until the job is success, failed or cancelled.
+
+        Parameters
+        ----------
+        interval : int
+            Time interval in seconds between each request to update the logs.
+            Defaults to 3 (seconds).
+        """
+
+        def stop_condition():
+            """Stops the log once the job is in a terminal state."""
+            self.sync()
+            if self.lifecycle_state not in self.TERMINAL_STATES:
+                return False
+            # Stop if time_finished is not available.
+            if not self.time_finished:
+                return True
+            # Stop only if time_finished is over 1 minute ago.
+            # This is for the time delay between feature definition job run stopped and the logs appear in oci logging.
+            if (
+                datetime.datetime.now(self.time_finished.tzinfo)
+                - datetime.timedelta(minutes=1)
+                > self.time_finished
+            ):
+                return True
+            return False
+
+        logger.info(f"Feature definition job OCID: {self.job.id}")
+        logger.info(f"Feature definition job run OCID: {self.id}")
+
+        status = ""
+        while not stop_condition():
+            status = self._check_and_print_status(status)
+            # Break and stream logs if job has log ID and started.
+            # Otherwise, keep watching the status until job terminates.
+            if self.time_started and self.log_id:
+                break
+            time.sleep(interval)
+        self._check_and_print_status(status)
+        return self
+
+    def _check_and_print_status(self, prev_status) -> str:
+        status = self._job_run_status_text()
+        if status != prev_status:
+            if self.lifecycle_state in self.TERMINAL_STATES and self.time_finished:
+                timestamp = self.time_finished
+            else:
+                timestamp = datetime.datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S")
+        return status
+
+    def complete_feature_group_job(self) -> "OCIFeatureGroupJob":
+        """Completes a feature group job.
+
+        Returns
+        -------
+        OCIFeatureGroupJob
+            The `OCIFeatureGroupJob` instance (self).
+        """
+        return self.update_from_oci_model(
+            self.client.complete_feature_group_job(
+                self.id, self.to_oci_model(CompleteFeatureGroupJobDetails)
+            ).data
+        )
+
+    @classmethod
+    def from_id(cls, id: str) -> "OCIFeatureGroupJob":
+        """Gets feature definition resource  by id.
+
+        Parameters
+        ----------
+        id: str
+            The id of the feature definition resource.
+
+        Returns
+        -------
+        OCIFeatureGroupJob
+            An instance of `OCIFeatureGroupJob`.
+        """
+        if not id:
+            raise ValueError("FeatureGroupJob id not provided.")
+        return super().from_ocid(id)
+
+    def __repr__(self) -> str:
+        """Displays the object as YAML."""
+        return self.to_yaml()