Add optional dependency management

.github/workflows/ci.yml

@@ -54,7 +54,7 @@ jobs:
           if [ "$RUNNER_OS" != "Windows" ] && [ ${{ matrix.python }} < '3.10' ]; then  # Skip Prophet tests on Windows as installation complex. Skip on Python 3.10 as not supported.
             python -m pip install --upgrade --upgrade-strategy eager -e .[prophet]
           fi
-          python -m pip install --upgrade --upgrade-strategy eager -e .[torch]
+          python -m pip install --upgrade --upgrade-strategy eager -e .[tensorflow,torch]
           python -m pip freeze
 
       - name: Lint with flake8
@@ -118,3 +118,17 @@ jobs:
           pip install "tox>=3.21.0,<4.0.0"
           make licenses
           make check_licenses
+
+  optional_dependencies:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.8'
+      - name: Check optional dependency imports are protected
+        run: |
+          pip install "tox>=3.21.0,<4.0.0"
+          tox

.github/workflows/test_changed_notebooks.yml

@@ -59,7 +59,7 @@ jobs:
           if [ "$RUNNER_OS" != "Windows" ] && [ ${{ matrix.python }} < '3.10' ]; then  # Skip Prophet tests on Windows as installation complex. Skip on Python 3.10 as not supported.
             python -m pip install --upgrade --upgrade-strategy eager -e .[prophet]
           fi
-          python -m pip install --upgrade --upgrade-strategy eager -e .[torch]
+          python -m pip install --upgrade --upgrade-strategy eager -e .[torch,tensorflow]
           python -m pip freeze
 
       - name: Run notebooks

CONTRIBUTING.md

@@ -45,3 +45,63 @@ the docs will be built under `doc/_build/html`.
 
 ## CI
 All PRs triger a Github Actions  build to run linting, type checking, tests, and build docs.
+
+## Optional Dependencies
+
+Alibi-detect uses optional dependencies to allow users to avoid installing large or challenging to install dependencies. 
+Alibi-detect manages modularity of components that depend on optional dependencies using the `import_optional` function 
+defined in `alibi_detect/utils/missing_optional_dependency.py`. This replaces the dependency with a dummy object that 
+raises an error when called. If you are working on public functionality that is dependent on an optional dependency you 
+should expose the functionality via the relevant `__init__.py` file by importing it there using the `optional_import` 
+function. Currently, optional dependencies are tested by importing all the public functionality and checking that the 
+correct errors are raised dependent on the environment. Developers can run these tests using `tox`. These tests are in 
+`alibi_detect/tests/test_dep_mangement.py`. If implementing functionality that is dependent on a new optional dependency
+then you will need to:
+
+1. Add it to `extras_require` in `setup.py`.
+2. Create a new `tox` environment in `setup.cfg` with the new dependency.
+3. Add a new dependency mapping to `ERROR_TYPES` in `alibi_detect/utils/missing_optional_dependency.py`. 
+4. Make sure any public functionality is protected by the `import_optional` function.
+5. Make sure the new dependency is tested in `alibi_detect/tests/test_dep_mangement.py`.
+
+Note that subcomponents can be dependent on optional dependencies too. In this case the user should be able to import 
+and use the relevant parent component. The user should only get an error message if: 
+1. They don't have the optional dependency installed and,
+2. They configure the parent component in such as way that it uses the subcomponent functionality.
+
+Developers should implement this by importing the subcomponent into the source code defining the parent component using 
+the `optional_import` function. The general layout of a subpackage with optional dependencies should look like: 
+
+```
+alibi_detect/subpackage/
+  __init__.py  # expose public API with optional import guards
+  defaults.py  # private implementations requiring only core deps
+  optional_dep.py # private implementations requiring an optional dependency (or several?)
+```
+
+any public functionality that is dependent on an optional dependency should be imported into `__init__.py` using the 
+`import_optional` function. 
+
+#### Note:
+- The `import_optional` function returns an instance of a class and if this is passed to type-checking constructs, such 
+as Union, it will raise errors. Thus, in order to do type-checking, we need to 1. Conditionally import the true object 
+dependent on `TYPE_CHECKING` and 2. Use forward referencing when passing to typing constructs such as `Union`. We use 
+forward referencing because in a user environment the optional dependency may not be installed in which case it'll be 
+replaced with an instance of the MissingDependency class. For example: 
+  ```py
+  from typing import TYPE_CHECKING, Union
+
+  if TYPE_CHECKING:
+    # Import for type checking. This will be type `UsefulClass`. Note import is from implementation file.
+    from alibi_detect.utils.useful_classes import UsefulClass
+  else:
+    # Import is from `__init__` public API file. Class will be protected by optional_import function and so this will 
+    # be type any.
+    from alibi.utils import UsefulClass
+
+  # The following will not throw an error because of the forward reference but mypy will still work.
+  def example_function(useful_class: Union['UsefulClass', str]) -> None:
+    ...
+  ```
+- Developers can use `make repl tox-env=<tox-env-name>` to run a python REPL with the specified optional dependency 
+installed. This is to allow manual testing.

Makefile

@@ -60,4 +60,7 @@ licenses:
 check_licenses:
 	git --no-pager diff --exit-code ./licenses/license_info.no_versions.csv
 
-
+.PHONY: repl
+tox-env=default
+repl:
+	env COMMAND="python" tox -e $(tox-env)

README.md

@@ -69,18 +69,21 @@ The package, `alibi-detect` can be installed from:
 ### With pip
 
 - alibi-detect can be installed from [PyPI](https://pypi.org/project/alibi-detect):
-
    ```bash
    pip install alibi-detect
    ```
 
 - Alternatively, the development version can be installed:
-
    ```bash
    pip install git+https://github.com/SeldonIO/alibi-detect.git
    ```
 
-- To install with the PyTorch backend (in addition to the default TensorFlow backend):
+- To install with the tensorflow backend:
+  ```bash
+  pip install alibi-detect[tensorflow]
+  ```
+
+- To install with the PyTorch backend:
   ```bash
   pip install alibi-detect[torch]
   ```
@@ -91,6 +94,7 @@ The package, `alibi-detect` can be installed from:
    pip install alibi-detect[prophet]
    ```
 
+
 ### With conda
 
 To install from [conda-forge](https://conda-forge.org/) it is recommended to use [mamba](https://mamba.readthedocs.io/en/stable/), 
@@ -100,24 +104,19 @@ which can be installed to the *base* conda enviroment with:
 conda install mamba -n base -c conda-forge
 ```
 
-- To install alibi-detect with the default TensorFlow backend:
+To install alibi-detect:
 
-  ```bash
-  mamba install -c conda-forge alibi-detect
-  ```
-
-- To install with the PyTorch backend:
+```bash
+mamba install -c conda-forge alibi-detect
+```
 
-  ```bash
-  mamba install -c conda-forge alibi-detect pytorch
-  ```
 
 ### Usage
 We will use the [VAE outlier detector](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/vae.html) to illustrate the API.
 
 ```python
 from alibi_detect.od import OutlierVAE
-from alibi_detect.utils import save_detector, load_detector
+from alibi_detect.saving import save_detector, load_detector
 
 # initialize and fit detector
 od = OutlierVAE(threshold=0.1, encoder_net=encoder_net, decoder_net=decoder_net, latent_dim=1024)
@@ -181,8 +180,8 @@ The following tables show the advised use cases for each algorithm. The column *
 
 #### TensorFlow and PyTorch support
 
-The drift detectors support TensorFlow and PyTorch backends. Alibi Detect does however not install PyTorch for you. 
-Check the [PyTorch docs](https://pytorch.org/) how to do this. Example:
+The drift detectors support TensorFlow and PyTorch backends. Alibi Detect does not install these as default. See the 
+[installation options](#installation-and-usage) for more details.
 
 ```python
 from alibi_detect.cd import MMDDrift

alibi_detect/ad/__init__.py

@@ -1,5 +1,7 @@
-from .adversarialae import AdversarialAE
-from .model_distillation import ModelDistillation
+from alibi_detect.utils.missing_optional_dependency import import_optional
+
+AdversarialAE = import_optional('alibi_detect.ad.adversarialae', names=['AdversarialAE'])
+ModelDistillation = import_optional('alibi_detect.ad.model_distillation', names=['ModelDistillation'])
 
 __all__ = [
     "AdversarialAE",

alibi_detect/base.py

@@ -3,8 +3,10 @@
 import json
 import numpy as np
 from typing import Dict, Any, Optional
+from typing_extensions import Protocol, runtime_checkable
 from alibi_detect.version import __version__, __config_spec__
 
+
 DEFAULT_META = {
     "name": None,
     "detector_type": None,  # online or offline
@@ -175,6 +177,38 @@ def _set_config(self, inputs):  # TODO - move to BaseDetector once config save/l
         self.config.update(inputs)
 
 
+@runtime_checkable
+class Detector(Protocol):
+    """Type Protocol for all detectors.
+
+    Used for typing legacy save and load functionality in `alibi_detect.saving.tensorflow._saving.py`.
+
+    Note:
+        This exists to distinguish between detectors with and without support for config saving and loading. Once all
+        detector support this then this protocol will be removed.
+    """
+    meta: Dict
+
+    def predict(self) -> Any: ...
+
+
+@runtime_checkable
+class ConfigurableDetector(Detector, Protocol):
+    """Type Protocol for detectors that have support for saving via config.
+
+    Used for typing save and load functionality in `alibi_detect.saving.saving.py`.
+
+    Note:
+        This exists to distinguish between detectors with and without support for config saving and loading. Once all
+        detector support this then this protocol will be removed.
+    """
+    def get_config(self): ...
+
+    def from_config(self): ...
+
+    def _set_config(self): ...
+
+
 class NumpyEncoder(json.JSONEncoder):
     def default(self, obj):
         if isinstance(

alibi_detect/cd/classifier.py

@@ -1,11 +1,12 @@
 import numpy as np
 from typing import Callable, Dict, Optional, Union
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, has_sklearn
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, \
+    BackendValidator
 from alibi_detect.base import DriftConfigMixin
 
-if has_sklearn:
-    from sklearn.base import ClassifierMixin
-    from alibi_detect.cd.sklearn.classifier import ClassifierDriftSklearn
+
+from sklearn.base import ClassifierMixin
+from alibi_detect.cd.sklearn.classifier import ClassifierDriftSklearn
 
 if has_pytorch:
     from torch.utils.data import DataLoader
@@ -147,12 +148,12 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if (backend == 'tensorflow' and not has_tensorflow) or (backend == 'pytorch' and not has_pytorch) or \
-                (backend == 'sklearn' and not has_sklearn):
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'ClassifierDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch', 'sklearn']:
-            raise NotImplementedError(f"{backend} not implemented. Use 'tensorflow', 'pytorch' or 'sklearn' instead.")
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch'],
+                             'sklearn': ['sklearn']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['model']]

alibi_detect/cd/context_aware.py

@@ -1,7 +1,7 @@
 import logging
 import numpy as np
 from typing import Callable, Dict, Optional, Union, Tuple
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.utils.warnings import deprecated_alias
 from alibi_detect.base import DriftConfigMixin
 
@@ -92,11 +92,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'ContextMMMDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['c_ref']]

alibi_detect/cd/learned_kernel.py

@@ -1,6 +1,6 @@
 import numpy as np
 from typing import Callable, Dict, Optional, Union
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.utils.warnings import deprecated_alias
 from alibi_detect.base import DriftConfigMixin
 
@@ -121,11 +121,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'LearnedKernel detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['kernel']]

alibi_detect/cd/lsdd.py

@@ -1,6 +1,6 @@
 import numpy as np
 from typing import Callable, Dict, Optional, Union, Tuple
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.utils.warnings import deprecated_alias
 from alibi_detect.base import DriftConfigMixin
 
@@ -81,11 +81,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'LSDDDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref']]

alibi_detect/cd/lsdd_online.py

@@ -1,6 +1,6 @@
 import numpy as np
 from typing import Any, Callable, Dict, Optional, Union
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.base import DriftConfigMixin
 if has_pytorch:
     from alibi_detect.cd.pytorch.lsdd_online import LSDDDriftOnlineTorch
@@ -82,11 +82,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'MMDDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['ert'], kwargs['window_size']]