Introducing XaiPient’s API for Model-Explanations

At XaiPient we’ve been developing a variety of tools to extract human-friendly insights from trained machine-learning models. Today we’re excited to expose some of our model-explanation tools via a REST API, which we’re making available in a private beta. To simplify working with this API we are releasing the XaiPient API Client (xac), which is a (pip-installable) Python-based command line interface (CLI) and Python library to interact with the XaiPient Explainability Server. The CLI can be used to interact with the API from the command-line in a terminal, whereas the Python library can be used in Python scripts or Jupyter and similar notebooks.

Why you might want to use the API

We envision two broad classes of uses of this API for developers:

• ML Engineers or Data Scientists can debug, validate and improve their models during model-development, and monitor production-deployed models.
• Developers can use the API to integrate the explanations into internal or external business-facing apps, dashboards, workflows, or reports (e.g. to consumers or regulators).

The business benefits of our human-friendly explanations include: (a) reducing regulatory risk, (b) improving customer trust, (c) actionable insights to improve business operations (e.g., what factors to adjust to reduce churn), and (d) enabling domain experts to easily vet and validate models, thus enhancing model adoption and trust.

What the API currently offers

Our robust explainability API server stack leverages best-of-breed technologies, including a FastAPI server, GraphQL server, Redis-backed job queue server, and custom-built explainability libraries.

The API currently supports binary classification models on tabular datasets. We will add support for continuous-output models, time-series, sequence and text models at a later date. We support models in a variety of frameworks (Tensorflow, Pytorch, Keras, XGBoost, LightGBM), and plan to add more depending on demand.

For a given model M and a test dataset D, the API provides several types of explanations (more details are in the docs):

• Global Feature Importances: average absolute feature-attributions over the dataset D.
• Global Feature Alignments: this measures, for each feature, on average over the dataset D, how well-aligned its contribution is with respect to the true target.
• Global Rules: Identifies clusters in D where the model’s classifications can be described via a simple, approximate decision rule (e.g. if an applicant has debt ratio > 5 and late payments > 2 then classify as Bad Credit).
• Local Attributions: For a specific row in D (or a given feature vector), the contributions of each feature to the model’s probability prediction.
• Local Rules: A justification of the model’s prediction on a specific row in D (or a given feature vector) in the form of a simple, approximate decision rule satisfied by points of D in the neighborhood of the given case.
• Counterfactual: For a given feature-vector (or row of D), a case with minimal feature-changes that the model classifies differently. This can serve as a contrastive explanation, or provide actionable insight to a business or consumer (e.g. what changes can lower risk, or improve my chances of loan acceptance?).

For maximum integration flexibility, the API calls return JSON strings, but more structured forms are available (like Pandas data-frames or dictionaries). For visually appealing, more business-friendly rendering of our explanations, we have developed a helper library to facilitate creating Streamlit apps using our API, and we’re happy to share this with interested developers.

How to integrate with your systems and workflow

While the underlying API is a cloud-based REST API, for businesses with data-security concerns, our API server can be readily deployed on a Kubernetes on-premise cluster or on your hybrid cloud environment. Contact us to discuss more on your specific requirements.

Example of using the Python API client

For those itching to dive in to the details, it’s best to head over to our docs, especially the Python quick-start, and checkout the Deepnote notebook we’ve published with a working walk-through. Here we’ll give a brief taste of what is involved in using the Python client.

First install the xac package following the instructions in the docs. Next, initialize the Explainer object with the login you receive from us, and the paths to your model, dataset and an optional column transformer. The column transformer encapsulates how you encode the original data (e.g. 1-hot encoding of categorical features, or standardization of numeric features) to a form suitable for passing as input to the model. This allows us to provide explanations in terms of the original features, which are more human-friendly (this is in contrast to many existing explainability tools, which produce explanations in the encoded space).

When you initialize the Explainer, you will be prompted for a password, which we would supply to you when you sign up.

Now the explainer object ex is ready to be queried for explanations, using various get_* methods, e.g.:

For example the global importances object gi is a JSON string, which we can view as a Python dict:

Behind the scenes, invoking a get_* method submits an explanation job, and waits for it to complete. If an explanation is time-consuming to compute, then this means a sequence of get_* calls can be somewhat slow. To alleviate this, we expose separate job submission and waiting using the notion of a promise object. Instead of a get_* method, we submit a request using an ask_* method, which immediately returns a promise object without waiting, and then we can query the promise object using a get() call:

We’d love to hear from you

We hope this post has given you a good idea of the why, what, and how of our API. If you’re interested in trying it out, please join the private beta wait-list. We’d love to hear about how you’re hoping to use the API, and any feedback you may have!