Merge pull request #57 from isabelizimm/dev-sd-handler

handlers to single dispatch

Author: isabelizimm

.github/workflows/docs.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e .[dev]
+          python -m pip install -e .[dev,torch]
       - name: build docs
         run: |
           cd docs

docs/source/advancedusage/custom_handler.md

@@ -0,0 +1,41 @@
+# Custom Handlers
+
+There are two different ways that vetiver supports flexible handling for models that do not work automatically with the vetiver framework. The first way is with [new model types,](#new-model-type) where there is no current implementation for the type of model you would like to deploy. The second way is when you would like to implement a current handler, but [in a different way](#different-model-implementation). In either case, you *must* make a custom handler from the base `VetiverHandler`. A minimal custom handler could look like the following:
+
+```python
+from vetiver.handlers.base import VetiverHandler
+
+class SampleCustomHandler(VetiverHandler):
+    def __init__(model, ptype_data):
+        super().__init__(model, ptype_data)
+    
+    def handler_predict(self, input_data, check_ptype):
+        """
+        handler_predict defines how to make predictions from your model
+        """
+        # your code here
+```
+
+## New model type
+If your model type is not supported by vetiver, you should create and then register the handler using [single dispatch](https://docs.python.org/3/library/functools.html#functools.singledispatch). Once the new type is registered, you are able to use `VetiverModel()` as normal. Here is a template for such a function: 
+
+```python    
+from vetiver.handlers._interface import create_handler
+
+@create_handler.register
+def _(model: {_model_type}, ptype_data):
+    return SampleCustomHandler(model, ptype_data)
+
+VetiverModel(your_model, "your_model")
+```
+
+If your model is a common type, please consider [submitting a pull request](https://github.com/rstudio/vetiver-python/pulls).
+
+## Different model implementation
+If your model's prediction function is different than vetiver's, you should create a custom handler with a `handler_predict` method to make predictions. Then, initialize your handler with your model, and pass the object into `VetiverModel`.
+
+```python    
+new_model = SampleCustomHandler(your_model, your_ptype_data)
+
+VetiverModel(new_model, "your_model")
+```

docs/source/conf.py

@@ -10,9 +10,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+from vetiver import __version__
 
 
 # -- Project information -----------------------------------------------------
@@ -22,7 +23,7 @@
 author = "Isabel Zimmerman"
 
 # The full version, including alpha/beta/rc tags
-release = "0.1.3"
+release = __version__
 
 
 # -- General configuration ---------------------------------------------------
@@ -64,6 +65,13 @@
 
 }
 
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}
+myst_heading_anchors = 2
+
 html_logo = "../figures/logo.png"
 html_favicon = "../figures/logo.png"
 

docs/source/index.rst

@@ -42,8 +42,6 @@ Version
 Deploy
 ==================
 
-.. currentmodule:: vetiver
-
 .. autosummary::
    :toctree: reference/
    :caption: Deploy
@@ -56,3 +54,10 @@ Deploy
    ~load_pkgs
    ~vetiver_write_app
    ~vetiver_write_docker
+
+Advanced Usage
+==================
+.. toctree::
+   advancedusage/custom_handler.md
+   :caption: Advanced Usage
+   

vetiver/__init__.py

@@ -14,6 +14,7 @@
 from .meta import *
 from .write_docker import *
 from .write_fastapi import * 
-from .handlers._interface import *
-from .handlers.sklearn_vt import *
-from .handlers.pytorch_vt import *
+from .handlers._interface import create_handler, InvalidModelError
+from .handlers.base import VetiverHandler
+from .handlers.sklearn import SKLearnHandler
+from .handlers.torch import TorchHandler

vetiver/handlers/_interface.py

@@ -1,31 +1,96 @@
-from vetiver.handlers import pytorch_vt, sklearn_vt
-import sklearn 
+from vetiver.handlers import torch, sklearn, base
+from functools import singledispatch
 
-torch_exists = True
-try:
-    import torch
-except ImportError:
-    torch_exists = False
+from vetiver.ptype import vetiver_create_ptype
 
-def create_translator(model, ptype_data):
+class InvalidModelError(Exception):
+    """
+    Throw an error if `model` is not
+    from scikit-learn or torch
+    """
+
+    def __init__(
+        self,
+        message="The `model` argument must be a scikit-learn or torch model.",
+    ):
+        self.message = message
+        super().__init__(self.message)
+
+CREATE_PTYPE_TPL =  """\
+Failed to create a handler from model of \
+type {_model_type}. If your model is not one of \
+(scikit-learn, torch), you should create and register \
+the handler. Here is a template for such a function: \
+    from vetiver.handlers._interface import create_handler
+    from vetiver.handlers.base import VetiverHandler
+
+    class CustomTemplateHandler(VetiverHandler):
+        def __init__(model, ptype_data):
+            super().__init__(model, ptype_data)
+        
+        def vetiver_create_meta(
+             user: list = None, 
+             version: str = None, 
+             url: str = None, 
+             required_pkgs: list = []):
+        \"""
+        Create metadata for model. This method should include the required 
+        packages necessary to create a prediction.
+        \"""
+        required_pkgs = required_pkgs + ["name_of_modeling_package"]
+        meta = vetiver_meta(user, version, url, required_pkgs)
+        
+        return meta
+
+        def handler_predict(self, input_data, check_ptype):
+            \"""
+            handler_predict should define how to make predictions from your model
+            \"""
+            ...
+
+    @vetiver_create_ptype.register
+    def _(model: {_model_type}, ptype_data):
+        return CustomTemplateHandler(model, ptype_data)
+
+If your datatype is a common type, please consider submitting \
+a pull request.
+"""
+
+@singledispatch
+def create_handler(model, ptype_data):
     """check for model type to handle prediction
 
     Parameters
     ----------
-    model
+    model: object
         Description of parameter `x`.
+    ptype_data : object
+        An object with information (data) whose layout is to be determined.
 
     Returns
     -------
-    pytorch_vt.TorchHandler or sklearn_vt.SKLearnHandler
+    handler
         Handler class for specified model type
+
+    Examples
+    --------
+    >>> import vetiver
+    >>> X, y = vetiver.mock.get_mock_data()
+    >>> model = vetiver.mock.get_mock_model()
+    >>> handler = vetiver.create_handler(model, X)
+    >>> handler.describe()
+    "Scikit-learn <class 'sklearn.dummy.DummyRegressor'> model"
     """
-    if torch_exists:
-        if isinstance(model, torch.nn.Module):
-            return pytorch_vt.TorchHandler(model, ptype_data)
 
-    if isinstance(model, sklearn.base.BaseEstimator):
-        return sklearn_vt.SKLearnHandler(model, ptype_data)
+    raise InvalidModelError(message=CREATE_PTYPE_TPL.format(_model_type=type(model)))
+
+create_handler.register(sklearn.SKLearnHandler.base_class, sklearn.SKLearnHandler)
+
+create_handler.register(torch.TorchHandler.base_class, torch.TorchHandler)
 
-    else:
-        raise NotImplementedError
+@create_handler.register
+def _(model:base.VetiverHandler, ptype_data):
+    if model.ptype_data is None and ptype_data is not None:
+        model.ptype_data = ptype_data
+    
+    return model

vetiver/handlers/base.py

@@ -0,0 +1,81 @@
+from ..ptype import vetiver_create_ptype
+from ..meta import vetiver_meta
+from abc import ABCMeta
+
+class VetiverHandler(metaclass=ABCMeta):
+    """Base handler class for creating VetiverModel of different type.
+
+    Parameters
+    ----------
+    model :
+        a trained model
+    ptype_data :
+        An object with information (data) whose layout is to be determined.
+    """
+
+    def __init__(self, model, ptype_data):
+        self.model = model
+        self.ptype_data = ptype_data
+
+
+    def describe(self):
+        """Create description for model"""
+        desc = f"{self.model.__class__} model"
+        return desc
+
+    def create_meta(
+        user: list = None,
+        version: str = None,
+        url: str = None,
+        required_pkgs: list = [],
+    ):
+        """Create metadata for sklearn model"""
+        meta = vetiver_meta(user, version, url, required_pkgs)
+
+        return meta
+
+    def construct_ptype(self):
+        """Create data prototype for torch model
+
+        Parameters
+        ----------
+        ptype_data : pd.DataFrame, np.ndarray, or None
+            Training data to create ptype
+
+        Returns
+        -------
+        ptype : pd.DataFrame or None
+            Zero-row DataFrame for storing data types
+        """
+        ptype = vetiver_create_ptype(self.ptype_data)
+        return ptype
+
+    def handler_startup():
+        """Include required packages for prediction
+
+        The `handler_startup` function executes when the API starts. Use this
+        function for tasks like loading packages.
+        """
+        ...
+
+
+    def handler_predict(self, input_data, check_ptype):
+        """Generates method for /predict endpoint in VetiverAPI
+
+        The `handler_predict` function executes at each API call. Use this
+        function for calling `predict()` and any other tasks that must be executed
+        at each API call.
+
+        Parameters
+        ----------
+        input_data:
+            Data used to generate prediction
+        check_ptype:
+            If type should be checked against `ptype` or not
+
+        Returns
+        -------
+        prediction
+            Prediction from model
+        """
+        ...

vetiver/handlers/sklearn_vt.py vetiver/handlers/sklearn.pyvetiver/handlers/sklearn_vt.py renamed to vetiver/handlers/sklearn.py

@@ -1,28 +1,29 @@
-from ..ptype import vetiver_create_ptype
 import pandas as pd
-from ..meta import vetiver_meta
 import sklearn
 
-class SKLearnHandler:
+from .base import VetiverHandler
+from ..meta import vetiver_meta
+
+class SKLearnHandler(VetiverHandler):
     """Handler class for creating VetiverModels with sklearn.
 
     Parameters
     ----------
     model : sklearn.base.BaseEstimator
         a trained sklearn model
     """
-
+    base_class = sklearn.base.BaseEstimator
+    
     def __init__(self, model, ptype_data):
-        self.model = model
-        self.ptype_data = ptype_data
+        super().__init__(model, ptype_data)
 
-    def create_description(self):
+    def describe(self):
         """Create description for sklearn model
         """
         desc = f"Scikit-learn {self.model.__class__} model"
         return desc
 
-    def vetiver_create_meta(
+    def construct_meta(
         user: list = None,
         version: str = None,
         url: str = None,
@@ -34,30 +35,6 @@ def vetiver_create_meta(
 
         return meta
 
-    def ptype(self):
-        """Create data prototype for torch model
-
-        Parameters
-        ----------
-        ptype_data : pd.DataFrame, np.ndarray, or None
-            Training data to create ptype
-
-        Returns
-        -------
-        ptype : pd.DataFrame or None
-            Zero-row DataFrame for storing data types
-        """
-        ptype = vetiver_create_ptype(self.ptype_data)
-        return ptype
-
-    def handler_startup():
-        """Include required packages for prediction
-
-        The `handler_startup` function executes when the API starts. Use this
-        function for tasks like loading packages.
-        """
-        ...
-
 
     def handler_predict(self, input_data, check_ptype):
         """Generates method for /predict endpoint in VetiverAPI