AIR Release - V0.5.1

AIR Tool

Copyright 2024 Carnegie Mellon University.

NO WARRANTY. THIS CARNEGIE MELLON UNIVERSITY AND SOFTWARE ENGINEERING INSTITUTE
MATERIAL IS FURNISHED ON AN "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO
WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, AS TO ANY MATTER
INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE OR
MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF THE MATERIAL.
CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT
TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT.

Licensed under a MIT (SEI)-style license, please see license.txt or contact
permission_at_sei.cmu.edu for full terms.

[DISTRIBUTION STATEMENT A] This material has been approved for public release
and unlimited distribution. Please see Copyright notice for non-US Government
use and distribution.

This Software includes and/or makes use of Third-Party Software each subject to
its own license.

DM24-1686

Title: AI Robustness (AIR) Tool

Version: 2.3.0

Release Date: 12/18/2024

Introduction

• Brief Overview: Modern analytic methods, including Artificial
  Intelligence (AI) and Machine Learning (ML) classifiers, depend on
  correlations; however, such approaches often fail to account for
  confounding in the data, which prevents accurate modeling of cause
  and effect, which often leads to prediction bias. The AI Robustness
  (AIR) tool allows users to gauge AI/ML classifier performance with
  unprecedented confidence.

• Target Audience: Projects that have an established AI classifier
  workflow, complete with data dictionaries and subject-matter
  experts. These release notes are for potential partners that would
  like to install the AIR tool in their own environment.

New Features

• Detailed Descriptions: Initial release.

• Benefits: NA for this release.

• Screenshots or Visuals: (see tutorial)

System Requirements and Installation

AIR tool can be installed at partner site or run in the SEI environment.
Classified options are not available at the SEI at this point.

Requirements for running AIR:

• Hardware:

  • 10+GiB of storage + any additional for your data

  • 12GiB+ memory (Estimate is based on our testing, but may vary)

• Software:

  • Docker-capable system (i.e., Linux/Mac/Windows)

  • WSL2/Docker/Docker Desktop software

  • A text editor

  • A web browser (used for viewing/interacting with local .html
    files)

• User:

  • Permissions to run a Docker container and any other supporting
    tools

  • Local copies of datasets to use with the AIR tool

Model and Data Requirements

The AIR Tool has requirements for data and model that must be followed
for it to work properly. This is important for the user to understand
before using the tool.

• Model:

  • The model must be an AI/ML classifier that operates on
    structured or tabular data, relying on numerical, categorical*,
    or time-series features, rather than unstructured data such as
    images, audio, or natural language text.

  • Unsupervised models, text classifiers, image classifiers, and
    most applications of generative AI are not currently supported.

  • Must have a single outcome variable that the classifier is
    predicting. This could be something like mission success, threat
    assessment, component failure, etc...

  • Must be run against multiple scenarios to predict outcome above.
    For example, does location affect mission success, does
    operating system affect threat assessment, does weather affect
    component failure, etc...

  • Must be compatible with use in an R environment and be able to
    utilize a predict() function OR allow the user to predict output
    given user-defined input (to predict ATE).

  • Must not require GPU acceleration or external hardware not
    currently supported by the tool.

• Data:

  • Must be .csv formatted.

  • Must be tabular format with header specifying variable names.

  • Must contain all variables used in the model provided (where
    applicable).

  • Variable names in data file must be identical to those in
    provided model (where applicable).

  • Data and model are recommended to contain less than 1,000 or so
    variables. Above this threshold, behavior of causal discovery
    algorithms may slow significantly.

  • All categorical variables must be one-hot encoded.

  • All time-series data must be consistently formatted.

  • No missing or null entries in the data.

  • Features must have variability (i.e., no constant columns) and
    not be intentional duplicates of one another.

Installation Instructions

Having met the usage requirements above, installation is a matter of
copying the container to a location that is accessible from the Docker
host. You'll want to have your data and knowledge files accessible to
the Docker host as well. A sample run command for using the container
would be:

Container Image

General Guidance

docker run -it -p 4173:4173 -u root --rm --name airtool airtool-image:latest

This Specific Release

The airtool-dev container for this release is available on GHCR:

docker pull ghcr.io/cmu-sei/airtool-dev:v0.5.1

Flag definitions:

• 4173: Default port that the development server runs on, it can be
  re-mapped if this port is inconvenient in your environment by simply
  changing the docker command.

• '-u root': Indicates what user the process inside the container will
  think it is running as (Note: Does not mean you need root
  permissions to run the container)

• '--rm': Indicates to remove the container after you've finished with
  it. If you wish to keep it around, remove this parameter.

• '--name': provides the name Docker will use to refer to this
  container. This is important, as if you don't choose a name, a new
  one will be assigned every time you run the container. If you are
  not removing the container, you will soon find you are running out
  of hard drive storage, after a handful of runs.

• 'airtool-image:latest': is the tagged name for the container. If you
  loaded the image to a local registry, using:

docker load < airtool.tar
docker tag airtool-image:latest

then the container will be viewable in your local docker registry,
using:

docker images

You may wish to add a data volume to your container. A limitation of the
current release is that intermediate products are not stored within the
container. I.e., every run starts from a new state.

Getting Started

Step 1: Building your Causal Graph

The tool will first prompt the user for their data file. This file
should conform to the characteristics outlined in the "Model and Data
Requirements" section above. This file is most helpful if it is either
the same data that was used to build the AI classifier in question or if
it is data that is otherwise fed (or could be fed) to the AI classifier
to make predictions.

After a data file is uploaded, the user will then select their knowledge
file for upload. Knowledge files used here will define rough hierarchies
of three or more levels of causation as determined logically or by
subject matter experts. Levels are defined as follows:

• Tier 0 -- Exogenous variables: These variables are not
  influenced by any other variables. Often used as starting points for
  causal graphs.

• Tier 1 -- Endogenous variables: Variables in this tier are
  potentially influenced by those in tier 0 and possibly other tier 1
  variables.

• Tier 2 and up -- Higher-tier variables: These variables may be
  influenced by any preceding tiers or its own. There can be any
  number of tiers, though as few as three tiers are strictly
  necessary.

Currently, all knowledge assertions will need to be done ahead of time
by the user as in-place editing is not yet supported by the tool. The
file format should be similar to the data file (i.e., .csv tabular
format with header), but will contain only two columns: level and
variable, where level contains a value for tier, 0-n, and variable
contains the variable name as written in the data file (must match
exactly with each). ). Each variable name should be represented exactly
once and on its own line (i.e., file must contain all names), each with
a corresponding numeric value in the 'level' column.

Once both files are uploaded and accepted a new button, "Build Graph,"
will appear. Once activated, the tool will run Causal Discovery
algorithms to build your causal graph and display it in the main panel
(right). If you are unsatisfied with the graph and feel that updating
your data and/or knowledge file might help, you can select new files and
re-build your graph until satisfied.

Step 2: Identifying potential sources of bias

The tool will now prompt users for additional information about the
problem the classifier is attempting to solve. Most important will be
identifying both the experimental/treatment (x) and outcome (y)
variables. Each variable definition will be pulled from the data file
(above).

*Note: in the current version of the tool, both x and y variables must
be treated as binary. Both variables will prompt the user for
definitions as to what constitutes "treated" vs "untreated" and
"success" vs "fail" for both the x and y variables, respectively. Data
distributio...