Merge remote-tracking branch 'origin/master' into feature/proxy-user

Author: cstenac

.gitignore

@@ -1,3 +1,3 @@
 *.pyc
 .idea
-.iml
+*.iml

dataikuapi/apinode_client.py

@@ -16,7 +16,8 @@ def __init__(self, uri, service_id, api_key=None):
         """
         DSSBaseClient.__init__(self, "%s/%s" % (uri, "public/api/v1/%s" % service_id), api_key)
 
-    def predict_record(self, endpoint_id, features, forced_generation=None, dispatch_key=None, context=None):
+    def predict_record(self, endpoint_id, features, forced_generation=None, dispatch_key=None, context=None,
+                       with_explanations=None, explanation_method=None, n_explanations=None, n_explanations_mc_steps=None):
         """
         Predicts a single record on a DSS API node endpoint (standard or custom prediction)
 
@@ -25,12 +26,24 @@ def predict_record(self, endpoint_id, features, forced_generation=None, dispatch
         :param forced_generation: See documentation about multi-version prediction
         :param dispatch_key: See documentation about multi-version prediction
         :param context: Optional, Python dictionary of additional context information. The context information is logged, but not directly used.
+        :param with_explanations: Optional, whether individual explanations should be computed for each record. The prediction endpoint must be compatible. If None, will use the value configured in the endpoint.
+        :param explanation_method: Optional, method to compute explanations. Valid values are 'SHAPLEY' or 'ICE'. If None, will use the value configured in the endpoint.
+        :param n_explanations: Optional, number of explanations to output per prediction. If None, will use the value configured in the endpoint.
+        :param n_explanations_mc_steps: Optional, precision parameter for SHAPLEY method, higher means more precise but slower (between 25 and 1000).
+         If None, will use the value configured in the endpoint.
 
         :return: a Python dict of the API answer. The answer contains a "result" key (itself a dict)
         """
-        obj =  {
-            "features" :features
+        obj = {
+            "features": features,
+            "explanations": {
+                "enabled": with_explanations,
+                "method": explanation_method,
+                "nExplanations": n_explanations,
+                "nMonteCarloSteps": n_explanations_mc_steps
+            }
         }
+
         if context is not None:
             obj["context"] = context
         if forced_generation is not None:
@@ -40,14 +53,20 @@ def predict_record(self, endpoint_id, features, forced_generation=None, dispatch
 
         return self._perform_json("POST", "%s/predict" % endpoint_id, body = obj)
 
-    def predict_records(self, endpoint_id, records, forced_generation=None, dispatch_key=None):
+    def predict_records(self, endpoint_id, records, forced_generation=None, dispatch_key=None, with_explanations=None,
+                        explanation_method=None, n_explanations=None, n_explanations_mc_steps=None):
         """
         Predicts a batch of records on a DSS API node endpoint (standard or custom prediction)
 
         :param str endpoint_id: Identifier of the endpoint to query
         :param records: Python list of records. Each record must be a Python dict. Each record must contain a "features" dict (see predict_record) and optionally a "context" dict.
         :param forced_generation: See documentation about multi-version prediction
         :param dispatch_key: See documentation about multi-version prediction
+        :param with_explanations: Optional, whether individual explanations should be computed for each record. The prediction endpoint must be compatible. If None, will use the value configured in the endpoint.
+        :param explanation_method: Optional, method to compute explanations. Valid values are 'SHAPLEY' or 'ICE'. If None, will use the value configured in the endpoint.
+        :param n_explanations: Optional, number of explanations to output per prediction. If None, will use the value configured in the endpoint.
+        :param n_explanations_mc_steps: Optional, precision parameter for SHAPLEY method, higher means more precise but slower (between 25 and 1000).
+         If None, will use the value configured in the endpoint.
 
         :return: a Python dict of the API answer. The answer contains a "results" key (which is an array of result objects)
         """
@@ -57,7 +76,13 @@ def predict_records(self, endpoint_id, records, forced_generation=None, dispatch
                 raise ValueError("Each record must contain a 'features' dict")
 
         obj = {
-            "items" : records
+            "items": records,
+            "explanations": {
+                "enabled": with_explanations,
+                "method": explanation_method,
+                "nExplanations": n_explanations,
+                "nMonteCarloSteps": n_explanations_mc_steps
+            }
         }
 
         if forced_generation is not None:

dataikuapi/dss/app.py

@@ -0,0 +1,144 @@
+import sys
+import re
+import os.path as osp
+from .future import DSSFuture
+from dataikuapi.utils import DataikuException
+import random, string
+
+def random_string(length):
+    return ''.join(random.choice(string.ascii_letters) for _ in range(length))
+
+class DSSApp(object):
+    """
+    A handle to interact with a app on the DSS instance.
+    Do not create this class directly, instead use :meth:`dataikuapi.DSSClient.get_app``
+    """
+    def __init__(self, client, app_id):
+       self.client = client
+       self.app_id = app_id
+
+    ########################################################
+    # Instances
+    ########################################################
+
+    def create_instance(self, instance_key, instance_name, wait=True):
+        """
+        Creates a new instance of this app. Each instance. must have a globally unique
+        instance key, separate from any project key across the whole DSS instance
+
+        :return: 
+        """
+        future_resp = self.client._perform_json(
+            "POST", "/apps/%s/instances" % self.app_id, body={
+            "targetProjectKey" : instance_key,
+            "targetProjectName" : instance_name
+        })
+        future = DSSFuture(self.client, future_resp.get("jobId", None), future_resp)
+        if wait:
+            result = future.wait_for_result()
+            return DSSAppInstance(self.client, instance_key)
+        else:
+            return future
+
+    def make_random_project_key(self):
+        slugified_app_id = re.sub(r'[^A-Za-z_0-9]+', '_', self.app_id)
+        return "%s_tmp_%s" % (slugified_app_id, random_string(10))
+
+    def create_temporary_instance(self):
+        """
+        Creates a new temporary instance of this app.
+        The return value should be used as a Python context manager. Upon exit, the temporary app
+        instance is deleted
+        :return a :class:`TemporaryDSSAppInstance`
+        """
+        key = self.make_random_project_key()
+        instance = self.create_instance(key, key, True)
+        return TemporaryDSSAppInstance(self.client, key)
+
+    def list_instance_keys(self):
+        """
+        List the existing instances of this app
+
+        :return a list of instance keys, each as a string
+        """
+        return [x["projectKey"] for x in self.list_instances()]
+
+    def list_instances(self):
+        """
+        List the existing instances of this app
+        
+        :rtype: list of dicts
+        :return a list of instances, each as a dict containing at least a "projectKey" field
+        """
+        return self.client._perform_json(
+            "GET", "/apps/%s/instances/" % self.app_id)
+
+    def get_instance(self, instance_key):
+        return DSSAppInstance(self.client, instance_key)
+
+
+    def get_manifest(self):
+        raw_data = self.client._perform_json("GET", "/apps/%s/" % self.app_id)
+        project_key = self.app_id[8:] if self.app_id.startswith('PROJECT_') else None
+        return DSSAppManifest(self.client, raw_data, project_key)
+
+
+class DSSAppManifest(object):
+
+    def __init__(self, client, raw_data, project_key=None):
+        """The manifest for an app. Do not create this class directly"""
+        self.client = client
+        self.raw_data = raw_data
+        self.project_key = project_key
+
+    def get_raw(self):
+        return self.raw_data
+
+    def get_all_actions(self):
+        return [x for section in self.raw_data["homepageSections"] for x in section["tiles"]]
+
+    def get_runnable_scenarios(self):
+        """Return the scenario identifiers that are declared as actions for this app"""
+        return [x["scenarioId"] for x in self.get_all_actions() if x["type"] == "SCENARIO_RUN"]
+
+    def save(self):
+        """Saves the changes to this manifest object back to the template project"""
+        if self.project_key is None:
+            raise Exception("This manifest object wasn't created from a project, cannot be saved back")
+        self.client._perform_empty("PUT", "/projects/%s/app-manifest" % self.project_key, body=self.raw_data)
+
+
+class DSSAppInstance(object):
+
+    def __init__(self, client, project_key):
+       self.client = client
+       self.project_key = project_key
+
+    def get_as_project(self):
+        """
+        Get the :class:`dataikuapi.dss.project DSSProject` corresponding to this app instance
+        """
+        return self.client.get_project(self.project_key)
+
+    def get_manifest(self):
+        """
+        Get the app manifest for this instance, as a :class:`DSSAppManifest`
+        """
+        raw_data = self.client._perform_json("GET", "/projects/%s/app-manifest" % self.project_key)
+        return DSSAppManifest(self.client, raw_data)
+
+class TemporaryDSSAppInstance(DSSAppInstance):
+    """internal class"""
+
+    def __init__(self, client, project_key):
+        DSSAppInstance.__init__(self, client,project_key)
+
+
+    def close(self):
+        self.get_as_project().delete(drop_data=True)
+
+    def __enter__(self,):
+        return self
+
+    def __exit__(self, type, value, traceback):
+        self.close()