ENH BYO trained model

If you train a scikit-learn compatible estimator outside of Civis Platform, you can use this to upload it to Civis Platform and prepare it for scoring with CivisML. There's a new Custom Script which will introspect metadata necessary for CivisML and make itself appear sufficiently like a CivisML training job that it can be used as input to a scoring job.

Author: Stephen Hoover

civis/ml/_model.py

@@ -42,8 +42,11 @@
                    9112: 9113,    # v1.1
                    8387: 9113,    # v1.0
                    7020: 7021,    # v0.5
+                   11028: 10583,  # v2.2 registration CHANGE ME
                    }
 _CIVISML_TEMPLATE = None  # CivisML training template to use
+REGISTRATION_TEMPLATES = [11028,  # v2.2
+                          ]
 
 
 class ModelError(RuntimeError):
@@ -713,6 +716,8 @@ def _get_template_ids(self, client):
         global _CIVISML_TEMPLATE
         if _CIVISML_TEMPLATE is None:
             for t_id in sorted(_PRED_TEMPLATES)[::-1]:
+                if t_id in REGISTRATION_TEMPLATES:
+                    continue
                 try:
                     # Check that we can access the template
                     client.templates.get_scripts(id=t_id)
@@ -783,6 +788,98 @@ def __setstate__(self, state):
         template_ids = self._get_template_ids(self._client)
         self.train_template_id, self.predict_template_id = template_ids
 
+    @classmethod
+    def register_pretrained_model(cls, model, dependent_variable=None,
+                                  features=None, model_name=None,
+                                  dependencies=None, git_token_name=None,
+                                  skip_model_check=False, verbose=False,
+                                  client=None):
+        """Make a scikit-learn Estimator usable with CivisML scoring
+
+        Parameters
+        ----------
+        model : sklearn.base.BaseEstimator or int
+            The model object. This must be a fitted scikit-learn compatible
+            Estimator object, or else the integer Civis File ID of a
+            pickle which stores such an object.
+        dependent_variable
+        features
+        model_name
+        dependencies
+        git_token_name
+        skip_model_check
+        verbose
+        client
+
+        Returns
+        -------
+        :class:`~civis.ml.ModelPipeline`
+        """
+        client = client or APIClient(resources='all')
+
+        if isinstance(dependent_variable, six.string_types):
+            dependent_variable = [dependent_variable]
+        if isinstance(features, six.string_types):
+            features = [features]
+        if isinstance(dependencies, six.string_types):
+            dependencies = [dependencies]
+        if not model_name:
+            model_name = ("Pretrained {} model for "
+                          "CivisML".format(model.__class__.__name__))
+            model_name = model_name[:255]  # Max size is 255 characters
+
+        if isinstance(model, (int, float, six.string_types)):
+            model_file_id = int(model)
+        else:
+            try:
+                tempdir = tempfile.mkdtemp()
+                fout = os.path.join(tempdir, 'model_for_civisml.pkl')
+                joblib.dump(model, fout, compress=3)
+                with open(fout, 'rb') as _fout:
+                    # NB: Using the name "estimator.pkl" means that
+                    # CivisML doesn't need to copy this input to a file
+                    # with a different name.
+                    model_file_id = cio.file_to_civis(_fout, 'estimator.pkl',
+                                                      client=client)
+            finally:
+                shutil.rmtree(tempdir)
+
+        args = {'MODEL_FILE_ID': str(model_file_id),
+                'SKIP_MODEL_CHECK': skip_model_check,
+                'DEBUG': verbose}
+        if dependent_variable is not None:
+            args['TARGET_COLUMN'] = ' '.join(dependent_variable)
+        if features is not None:
+            args['FEATURE_COLUMNS'] = ' '.join(features)
+        if dependencies is not None:
+            args['DEPENDENCIES'] = ' '.join(dependencies)
+        if git_token_name:
+            creds = find(client.credentials.list(),
+                         name=git_token_name,
+                         type='Custom')
+            if len(creds) > 1:
+                raise ValueError("Unique credential with name '{}' for "
+                                 "remote git hosting service not found!"
+                                 .format(git_token_name))
+            args['GIT_CRED'] = creds[0].id
+
+        template_id = max(REGISTRATION_TEMPLATES)
+        container = client.scripts.post_custom(
+            from_template_id=template_id,
+            name=model_name,
+            arguments=args)
+        log.info('Created custom script %s.', container.id)
+
+        run = client.scripts.post_custom_runs(container.id)
+        log.debug('Started job %s, run %s.', container.id, run.id)
+
+        fut = ModelFuture(container.id, run.id, client=client,
+                          poll_on_creation=False)
+        fut.result()
+        log.info('Model registration complete.')
+
+        return ModelPipeline.from_existing(fut.job_id, fut.run_id, client)
+
     @classmethod
     def from_existing(cls, train_job_id, train_run_id='latest', client=None):
         """Create a :class:`ModelPipeline` object from existing model IDs

civis/ml/tests/test_model.py

@@ -39,6 +39,10 @@
 from civis.ml import _model
 
 
+LATEST_TRAIN_TEMPLATE = 10582
+LATEST_PRED_TEMPLATE = 10583
+
+
 def setup_client_mock(script_id=-10, run_id=100, state='succeeded',
                       run_outputs=None):
     """Return a Mock set up for use in testing container scripts
@@ -682,7 +686,7 @@ def test_modelpipeline_init_newest():
     mp = _model.ModelPipeline(LogisticRegression(), 'test', etl=etl,
                               client=mock_client)
     assert mp.etl == etl
-    assert mp.train_template_id == max(_model._PRED_TEMPLATES)
+    assert mp.train_template_id == LATEST_TRAIN_TEMPLATE
     # clean up
     _model._CIVISML_TEMPLATE = None
 
@@ -787,7 +791,7 @@ def test_modelpipeline_classmethod_constructor_defaults(
 def test_modelpipeline_classmethod_constructor_future_train_version():
     # Test handling attempts to restore a model created with a newer
     # version of CivisML.
-    current_max_template = max(_model._PRED_TEMPLATES)
+    current_max_template = LATEST_TRAIN_TEMPLATE
     cont = container_response_stub(current_max_template + 1000)
     mock_client = mock.Mock()
     mock_client.scripts.get_containers.return_value = cont
@@ -892,7 +896,7 @@ def test_modelpipeline_train_df(mock_ccr, mock_stash, mp_setup):
     train_data = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
     assert 'res' == mp.train(train_data)
     mock_stash.assert_called_once_with(
-        train_data, max(_model._PRED_TEMPLATES.keys()), client=mock.ANY)
+        train_data, LATEST_TRAIN_TEMPLATE, client=mock.ANY)
     assert mp.train_result_ == 'res'