Merge branch 'main' into main-public

.dockerignore

@@ -0,0 +1,4 @@
+.venv**
+.git**
+docker
+poetry.lock

.gitignore

@@ -153,3 +153,8 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# poetry lock files
+poetry.lock
+**/poetry.lock
+**/**/poetry.lock

Makefile

@@ -16,46 +16,42 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 
-ACTIVATE_TF = "intel_tf/bin/activate"
-ACTIVATE_PYT = "intel_pyt/bin/activate"
-ACTIVATE_TEST = "test_env/bin/activate"
+VENV_DIR = ".venv"
+ACTIVATE_TEST = "$(VENV_DIR)/bin/activate"
 ACTIVATE_DOCS = $(ACTIVATE_TEST)
 ACTIVATE_NOTEBOOK = $(ACTIVATE_TEST)
 
 LISTEN_IP ?= 127.0.0.1
 LISTEN_PORT ?= 9090
 DOCS_DIR ?= docs
 
-venv-test:
-	@echo "Creating a virtualenv test_env..."
-	@test -d test_env || virtualenv -p python test_env
+venv-test: poetry-lock
+	@echo "Creating a virtualenv $(VENV_DIR)..."
+	@poetry install --with test --extras all
 
-	@echo "Building the XAI API in test_env env..."
-	@. $(ACTIVATE_TEST) && pip install --extra-index-url https://download.pytorch.org/whl/cpu --editable .[test]
+test-mcg: venv-test
+	@echo "Testing the Model Card Gen API..."
+	@. $(ACTIVATE_TEST) && pytest model_card_gen/tests
 
-# TODO: running all tests in one pytest session randomly causes torch test to hang at last epoch
-test-torch: venv-test
-	@echo "Testing the API..."
-	@. $(ACTIVATE_TEST) && PYTHONPATH="$(CURDIR)/model_card_gen/tests" pytest -s model_card_gen/tests/test_end_to_end_torch.py
+install: poetry-lock
+	@poetry install --extras all
 
-test-mcg: test-torch
-	@echo "Testing the API..."
-	@. $(ACTIVATE_TEST) && PYTHONPATH="$(CURDIR)/model_card_gen/tests" pytest -s -k "not torch"
-
-install:
-	@pip install --extra-index-url https://download.pytorch.org/whl/cpu --editable .
-
-xai-whl:
-	@python setup.py bdist_wheel
+build-whl:
+	@poetry build
 
 clean:
-	@rm -rf build dist intel_xai_tools.egg-info
-	@rm -rf test_env
+	@rm -rf build dist intel_ai_safety.egg-info
+	@rm -rf $(VENV_DIR)
 
-test-explainer: venv-test 
-	@. $(ACTIVATE_TEST) && pytest explainer/tests
+test-explainer: venv-test
+	@echo "Testing the Explainer API..."
+	@. $(ACTIVATE_TEST) && pytest plugins/explainers/attributions/tests
+	@. $(ACTIVATE_TEST) && pytest plugins/explainers/attributions-hugging-face/tests
+	@. $(ACTIVATE_TEST) && pytest plugins/explainers/cam-tensorflow/tests
+	@. $(ACTIVATE_TEST) && pytest plugins/explainers/cam-pytorch/tests
+	@. $(ACTIVATE_TEST) && pytest plugins/explainers/metrics/tests
 
-test: clean test-mcg test-explainer
+test: test-mcg test-explainer
 
 venv-docs: venv-test ${DOCS_DIR}/requirements-docs.txt
 	@echo "Installing docs dependencies..."
@@ -74,13 +70,44 @@ test-notebook: venv-test
 	@. $(ACTIVATE_NOTEBOOK) && \
 	bash run_notebooks.sh $(CURDIR)/notebooks/explainer/imagenet_with_cam/ExplainingImageClassification.ipynb
 
-dist: venv-test
+dist: build-whl
 	@echo "Create binary wheel..."
-	@. $(ACTIVATE_DOCS) && python setup.py bdist_wheel
 
 check-dist: dist
 	@echo "Testing the wheel..."
 	@. $(ACTIVATE_DOCS) && \
 	pip install twine && \
-	python setup.py bdist_wheel && \
 	twine check dist/*
+
+bump: venv-test
+	@poetry self add poetry-bumpversion
+	@poetry version patch --dry-run
+	@(cd model_card_gen ; poetry version patch --dry-run)
+	@(cd explainer; poetry version patch --dry-run)
+	@echo -n "Are you sure you want to make above changes? [y/N] " && read ans && [ $${ans:-N} = y ]
+	@poetry version patch
+	@(cd model_card_gen ; poetry version patch)
+	@(cd explainer; poetry version patch)
+
+poetry-lock:
+	@echo "Lock all project dependency versions"
+	@poetry update --lock
+	@cd explainer && poetry lock && cd -
+	@cd model_card_gen && poetry lock && cd -
+	@cd plugins/explainers/attributions-hugging-face && poetry lock && cd -
+	@cd plugins/explainers/attributions && poetry lock && cd -
+	@cd plugins/explainers/cam-pytorch && poetry lock && cd -
+	@cd plugins/explainers/cam-tensorflow && poetry lock && cd -
+	@cd plugins/explainers/captum && poetry lock && cd -
+	@cd plugins/explainers/metrics && poetry lock && cd -
+
+poetry-lock-update:
+	@echo "Update and Lock all project dependency versions"
+	@poetry update --lock
+	@cd model_card_gen && poetry update --lock && cd -
+	@cd plugins/explainers/attributions-hugging-face && poetry update --lock && cd -
+	@cd plugins/explainers/attributions && poetry update --lock && cd -
+	@cd plugins/explainers/cam-pytorch && poetry update --lock && cd -
+	@cd plugins/explainers/cam-tensorflow && poetry update --lock && cd -
+	@cd plugins/explainers/captum && poetry update --lock && cd -
+	@cd plugins/explainers/metrics && poetry update --lock && cd -

README.md

@@ -7,13 +7,13 @@ This repository provides tools for data scientists and MLOps engineers that have
 The Intel Explainable AI Tools are designed to help users detect and mitigate against issues of fairness and interpretability, while running best on Intel hardware.
 There are two Python* components in the repository:
 
-* [Model Card Generator](model_card_gen)
+* [Model Card Generator](intel_ai_safety/model_card_gen)
   * Creates interactive HTML reports containing model performance and fairness metrics
 * [Explainer](explainer)
   * Runs post-hoc model distillation and visualization methods to examine predictive behavior for both TensorFlow* and PyTorch* models via a simple Python API including the following modules:
-    * [Attributions](explainer/attributions/): Visualize negative and positive attributions of tabular features, pixels, and word tokens for predictions
-    * [CAM (Class Activation Mapping)](explainer/cam/): Create heatmaps for CNN image classifications using gradient-weight class activation CAM mapping
-    * [Metrics](explainer/metrics/): Gain insight into models with the measurements and visualizations needed during the machine learning workflow
+    * [Attributions](explainer/intel_ai_safety/explainer/attributions/): Visualize negative and positive attributions of tabular features, pixels, and word tokens for predictions
+    * [CAM (Class Activation Mapping)](explainer/intel_ai_safety/explainer/cam/): Create heatmaps for CNN image classifications using gradient-weight class activation CAM mapping
+    * [Metrics](explainer/intel_ai_safety/explainer/metrics/): Gain insight into models with the measurements and visualizations needed during the machine learning workflow
 
 ## Get Started
 
@@ -23,40 +23,85 @@ There are two Python* components in the repository:
 * Install required OS packages with `apt-get install build-essential python3-dev`
 * git (only required for the "Developer Installation")
 
-### Create and activate a Python3 virtual environment
-We encourage you to use a python virtual environment (virtualenv or conda) for consistent package management.
-There are two ways to do this:
+### Developer Installation with Poetry
+
+Use these instructions to install the Intel AI Safety python library with a clone of the
+GitHub repository. This can be done instead of the basic pip install, if you plan
+on making code changes.
+
+1. Clone this repo and navigate to the repo directory.
+
+2. Allow poetry to create virtual envionment contained in `.venv` directory of current directory. 
 
-a. Using `virtualenv`:
    ```
-   python3.9 -m virtualenv xai_env
-   source xai_env/bin/activate
+   poetry lock
+   ```
+   In addtion, you can explicitly tell poetry which python instance to use
+
+   ```
+   poetry env use /full/path/to/python
    ```
 
-b. Or `conda`:
+3. Choose the `intel_ai_safety` subpackages and plugins that you wish to install.
+
+   a. Install `intel_ai_safety` with all of its subpackages (e.g. `explainer` and `model_card_gen`) and plugins
    ```
-   conda create --name xai_env python=3.9
-   conda activate xai_env
+   poetry install --extras all
    ```
 
-### Basic Installation
-```
-pip install intel-xai
-```
-### Developer Installation
-Use these instructions to install the Intel Explainable AI Tools with a clone of the
-GitHub repository. This can be done instead of the basic pip install, if you plan
-on making code changes.
+   b. Install `intel_ai_safety` with just `explainer`
+   ```
+   poetry install --extras explainer
+   ```
+
+   c. Install `intel_ai_safety` with just `model_card_gen`
+   ```
+   poetry install --extras model-card
+   ```
+
+   d. Install `intel_ai_safety` with `explainer` and all of its plugins
+   ```
+   poetry install --extras explainer-all
+   ```
 
-1. Clone this repo and navigate to the repo directory:
+   e. Install `intel_ai_safety` with `explainer` and just its pytorch implementations
+
+   ```
+   poetry install --extras explainer-pytorch
+   ```
+
+   f. Install `intel_ai_safety` with `explainer` and just its pytorch implementations
+
    ```
-   git clone https://github.com/IntelAI/intel-xai-tools.git
+   poetry install --extras explainer-tensorflow
+   ``` 
 
-   cd intel-xai-tools
+4. Activate the enviornment:
+
+   ```
+   source .venv/bin/activate
    ```
-2. Install the Intel Explainable AI Tools using the following command:
+
+### Install to existing enviornment with Poetry
+
+#### Create and activate a Python3 virtual environment
+We encourage you to use a python virtual environment (virtualenv or conda) for consistent package management.
+There are two ways to do this:
+1. Choose a virtual enviornment to use:
+   a. Using `virtualenv`:
+      ```
+      python3.9 -m virtualenv xai_env
+      source xai_env/bin/activate
+      ```
+
+   b. Or `conda`:
+      ```
+      conda create --name xai_env python=3.9
+      conda activate xai_env
+      ```
+2. Install to current enviornment
    ```
-   make install
+   poetry config virtualenvs.create false && poetry install --extras all
    ```
 
 ### Additional Feature-Specific Steps
@@ -66,8 +111,8 @@ Notebooks may require additional dependencies listed in their associated documen
 
 Verify that your installation was successful by using the following commands, which display the Explainer and Model Card Generator versions:
 ```
-python -c "from explainer import version; print(version.__version__)"
-python -c "from model_card_gen import version; print(version.__version__)"
+python -c "from intel_ai_safety.explainer import version; print(version.__version__)"
+python -c "from intel_ai_safety.model_card_gen import version; print(version.__version__)"
 ```
 
 ## Running Notebooks

docker/Dockerfile.explainers

@@ -0,0 +1,89 @@
+#
+# Copyright (c) 2024 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+ARG IMAGE_NAME=ubuntu
+ARG IMAGE_TAG=22.04
+
+# Clean base for Explainer
+FROM ${IMAGE_NAME}:${IMAGE_TAG} as base
+
+ARG PY_VER=3.10
+
+RUN apt-get update && \
+    apt-get upgrade -y && \
+    apt-get autoclean && \
+    apt-get autoremove -y && \
+    DEBIAN_FRONTEND=noninteractive \
+    apt-get install --no-install-recommends --fix-missing -y \
+    graphviz \
+    libgl1 \
+    libglib2.0.0 \
+    python${PY_VER} \
+    python3-pip \
+    tzdata
+
+RUN ln -sf $( which python${PY_VER} ) /usr/bin/python
+
+# Development Explainer image
+FROM base as builder
+
+ARG PY_VER=3.10
+ARG APP_DIR=/intel-xai
+
+ARG POETRY_NO_INTERACTION=1 \
+    POETRY_VIRTUALENVS_IN_PROJECT=1 \
+    POETRY_VIRTUALENVS_CREATE=1
+
+RUN apt-get update && \
+    apt-get upgrade -y && \
+    apt-get autoclean && \
+    apt-get autoremove -y && \
+    apt-get install --no-install-recommends --fix-missing -y \
+    g++ \
+    python${PY_VER}-dev
+
+RUN python${PY_VER} -m pip install --no-cache-dir \
+    'poetry==1.8.2'
+
+COPY . ${APP_DIR}
+WORKDIR ${APP_DIR}
+
+RUN /usr/local/bin/poetry config virtualenvs.create false && \
+    poetry install --extras explainer --extras explainer-all && \
+    ${APP_DIR}/.venv/bin/pip install --no-cache-dir -r notebooks/explainer/requirements.txt && \
+    rm -rf ${HOME}/.cache/pypoetry ${HOME}/.cache/pip
+
+# Production Explainer image
+FROM base as runtime
+
+ARG APP_DIR=/intel-xai
+
+SHELL ["/bin/bash", "-c"]
+
+COPY --from=builder ${APP_DIR} ${APP_DIR}
+
+ENV VIRTUAL_ENV="${APP_DIR}/.venv" \
+    PATH="${APP_DIR}/.venv/bin:${PATH}"
+
+WORKDIR ${APP_DIR}/notebooks/explainer
+
+EXPOSE 8888
+
+RUN echo "source activate ${VIRTUAL_ENV}" >> ~/.bashrc
+
+CMD ["bash", "-c", "source activate ${VIRTUAL_ENV} && jupyter notebook --port 8888 --ip 0.0.0.0 --no-browser --allow-root"]