Merge pull request #38 from sassoftware/dev-1.3.0

Dev 1.3.0

Author: Jon Walker

.gitignore

@@ -32,6 +32,7 @@ dist
 *.egg-info
 .eggs
 .pypirc
+*.pyc
 
 ## tox testing tool
 .tox

CHANGELOG.md

@@ -1,7 +1,20 @@
 
 Unreleased
 ----------
- - 
+ -
+
+v1.3 (2019-10-10)
+----------------- 
+**Improvements**
+ - Added `update_performance` task for easily uploading performance information for a model. 
+ - New (experimental) pyml2sas sub-package provides utilities for generating SAS code from Python gradient boosting models. 
+ - New (experimental) methods for managing workflows added to `model_management` service.
+ 
+**Changes**
+ - `register_model` task automatically captures installed Python packages.
+ - All `list_xxx` methods return all matching items unless a `limit` parameter is specified.
+ - Improved API documentation.
+ - Updated `full_lifecycle` example with performance monitoring.
 
 v1.2.5 (2019-10-10)
 -------------------

doc/api/sasctl.core.rst

@@ -0,0 +1,8 @@
+sasctl.core
+=======================
+
+.. automodule:: sasctl.core
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

doc/api/sasctl.current_session.rst

@@ -0,0 +1,3 @@
+current_session
+===============
+

doc/api/sasctl.rst

@@ -4,32 +4,18 @@ sasctl package
 Module contents
 ---------------
 
-.. automodule:: sasctl
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. toctree::
+
+    sasctl.session
+    sasctl.current_session
 
 Submodules
 ----------
 
-sasctl.core module
-~~~~~~~~~~~~~~~~~~
-
-.. automodule:: sasctl.core
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-sasctl.tasks module
-~~~~~~~~~~~~~~~~~~~
-
-.. automodule:: sasctl.tasks
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
+.. toctree::
 
+    sasctl.core
+    sasctl.tasks
 
 Subpackages
 -----------

doc/api/sasctl.session.rst

@@ -0,0 +1,5 @@
+Session
+=======
+
+.. autoclass:: sasctl.core.Session
+    :members:

doc/api/sasctl.tasks.rst

@@ -0,0 +1,7 @@
+sasctl.tasks
+=======================
+
+.. automodule:: sasctl.tasks
+    :members:
+    :undoc-members:
+    :show-inheritance:

examples/full_lifecycle.py

@@ -11,7 +11,7 @@
 from sklearn.model_selection import train_test_split
 
 from sasctl import Session
-from sasctl.tasks import register_model, publish_model
+from sasctl.tasks import register_model, publish_model, update_model_performance
 from sasctl.services import model_repository as mr
 from sasctl.services import model_management as mm
 
@@ -39,12 +39,10 @@
                project=project,     # Register in "Iris" project
                force=True)          # Create project if it doesn't exist
 
-# Update project properties
+# Update project properties.  Target variable must be set before performance
+# definitions can be created.
 project = mr.get_project(project)
-project['function'] = 'prediction'
-project['targetLevel'] = 'interval'
 project['targetVariable'] = 'Price'
-project['predictionVariable'] = 'var1'
 project = mr.update_project(project)
 
 # Instruct the project to look for tables in the "Public" CAS library with
@@ -55,8 +53,8 @@
 # Publish the model to the real-time scoring engine
 module_lm = publish_model(model_name, 'maslocal')
 
-# Select the first row of training data
-x = X.iloc[0, :]
+# Select the first row of testing data
+x = X_test.iloc[0, :]
 
 # Call the published module and score the record
 result = module_lm.score(**x)
@@ -76,5 +74,16 @@
 result = module_dt.score(**x)
 print(result)
 
+# Model Manager can track model performance over time if provided with
+# historical model observations & predictions.  SIMULATE historical data by
+# repeatedly sampling from the test set.
+perf_df = X_test.copy()
+perf_df['var1'] = lm.predict(X_test)
+perf_df['Price'] = y
+
+# For each (simulated) historical period, upload model results
+for period in ('q12019', 'q22019', 'q32019', 'q42019'):
+    sample = perf_df.sample(frac=0.2)
+    update_model_performance(sample, model_name, period)
 
 

src/sasctl/__init__.py

@@ -4,7 +4,7 @@
 # Copyright © 2019, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-__version__ = '1.2.5'
+__version__ = '1.3'
 __author__ = 'SAS'
 __credits__ = ['Yi Jian Ching, Lucas De Paula, James Kochuba, Peter Tobac, '
                'Chris Toth, Jon Walker']

src/sasctl/_services/model_management.py

@@ -5,7 +5,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from .service import Service
-
+from ..utils.decorators import experimental
 
 class ModelManagement(Service):
     """The Model Management API provides basic resources for monitoring
@@ -20,7 +20,8 @@ class ModelManagement(Service):
                             'performance tasks')
 
     # TODO:  set ds2MultiType
-    def publish_model(self,
+    @classmethod
+    def publish_model(cls,
                       model,
                       destination,
                       name=None,
@@ -80,15 +81,16 @@ def publish_model(self,
         # Publishes a model that has already been registered in the model
         # repository.
         # Unlike model_publish service, does not require Code to be specified.
-        r = self.post('/publish',
-                      json=request,
-                      params=dict(force=force,
+        r = cls.post('/publish',
+                     json=request,
+                     params=dict(force=force,
                                   reloadModelTable=reload_model_table),
-                      headers={'Content-Type':
+                     headers={'Content-Type':
                                    'application/vnd.sas.models.publishing.request.asynchronous+json'})
         return r
 
-    def create_performance_definition(self,
+    @classmethod
+    def create_performance_definition(cls,
                                       model,
                                       library_name,
                                       table_prefix,
@@ -156,7 +158,7 @@ def create_performance_definition(self,
         """
         from .model_repository import ModelRepository
 
-        if '_' in table_prefix:
+        if not scoring_required and '_' in table_prefix:
             raise ValueError(
                 "Parameter 'table_prefix' cannot contain underscores."
                 " Received a value of '%s'.") % table_prefix
@@ -210,11 +212,12 @@ def create_performance_definition(self,
                                           project.get('variables', []) if
                                           v.get('role') == 'output']
 
-        return self.post('/performanceTasks', json=request,
-                     headers={
+        return cls.post('/performanceTasks', json=request,
+                        headers={
             'Content-Type': 'application/vnd.sas.models.performance.task+json'})
 
-    def execute_performance_definition(self, definition):
+    @classmethod
+    def execute_performance_definition(cls, definition):
         """Launches a job to run a performance definition.
 
         Parameters
@@ -228,7 +231,118 @@ def execute_performance_definition(self, definition):
             The executing job
 
         """
-        definition = self.get_performance_definition(definition)
+        definition = cls.get_performance_definition(definition)
+
+        return cls.post('/performanceTasks/%s' % definition.id)
+
+    @classmethod
+    @experimental
+    def list_model_workflow_definition(cls):
+        """List all enabled Workflow Processes to execute on Model Project.
+
+        Returns
+        -------
+        RestObj
+            The list of workflows
+
+        """
+        from .workflow import Workflow
+        wf = Workflow()
+
+        return wf.list_enabled_definitions()
+
+    @classmethod
+    @experimental
+    def list_model_workflow_prompt(cls, workflowName):
+        """List prompt Workflow Processes Definitions.
+
+        Parameters
+        ----------
+        workflowName : str
+            Name or ID of an enabled workflow to retrieve inputs
+
+        Returns
+        -------
+        list
+            The list of prompts for specific workflow
+    
+        """
+        from .workflow import Workflow
+        wf = Workflow()
+        
+        return wf.list_workflow_prompt(workflowName)
+
+    @classmethod
+    @experimental
+    def list_model_workflow_executed(cls, projectName):
+        """List prompt Workflow Processes Definitions.
+
+        Parameters
+        ----------
+        projectName : str
+            Name of the Project list executed workflow
+
+        Returns
+        -------
+        RestObj
+            List of workflows associated to project
+
+        """
+        from .model_repository import ModelRepository
+        mr = ModelRepository()
+
+        project = mr.get_project(projectName)
+
+        return cls.get('/workflowProcesses?filter=eq(associations.solutionObjectId,%22' + project['id'] + '%22)')
+
+    @classmethod
+    @experimental
+    def execute_model_workflow_definition(cls, project_name, workflow_name, input=None):
+        """Runs specific Workflow Processes Definitions.
+
+        Parameters
+        ----------
+        project_name : str
+            Name of the Project that will execute workflow
+        workflow_name : str
+            Name or ID of an enabled workflow to execute
+        input : dict, optional
+            Input values for the workflow for initial workflow prompt
+
+        Returns
+        -------
+        RestObj
+            The executing workflow
+            
+        """
+        from .model_repository import ModelRepository
+        from .workflow import Workflow
+
+        mr = ModelRepository()
+        wf = Workflow()
+        
+        project = mr.get_project(project_name)
+
+        workflow = wf.run_workflow_definition(workflow_name, input=input)
+        
+        # Associations running workflow to model project, note workflow has to be running
+        # THINK ABOUT: do we do a check on status of the workflow to determine if it is still running before associating?
+
+        input = {"processName": workflow['name'],
+                 "processId": workflow['id'],
+                 "objectType": "MM_Project",
+                 "solutionObjectName": project_name,
+                 "solutionObjectId": project['id'],
+                 "solutionObjectUri": "/modelRepository/projects/" + project['id'],
+                 "solutionObjectMediaType": "application/vnd.sas.models.project+json"}
+        
+        #Note, you can get a HTTP Error 404: {"errorCode":74052,"message":"The workflow process for id <> cannot be found.
+        #                                    Associations can only be made to running processes.","details":["correlator:
+        #                                    e62c5562-2b11-45db-bcb7-933200cb0f0a","traceId: 3118c0fb1eb9702d","path:
+        #                                    /modelManagement/workflowAssociations"],"links":[],"version":2,"httpStatusCode":404} 
+        # Which is fine and expected like the Visual Experience.
+        return cls.post('/workflowAssociations',
+                        json=input,
+                        headers={'Content-Type': 'application/vnd.sas.workflow.object.association+json'})
 
-        return self.post('/performanceTasks/%s' % definition.id)