xai-gpt-shap

xai-gpt-shap is a Python library for explainable AI (XAI) that combines SHAP (SHapley Additive exPlanations) value analysis with OpenAI GPT-based explanations to make machine learning model predictions more interpretable.

This library allows you to:

• Perform SHAP analysis on machine learning models.
• Generate role-specific explanations for SHAP results using OpenAI GPT (e.g., for beginners, analysts, or researchers).
• Interactively explore and understand SHAP results via a command-line interface (CLI).

Key Features

• SHAP Integration: Calculate SHAP values for any machine learning model and dataset.
• OpenAI GPT Integration: Automatically explain SHAP results using OpenAI GPT with role-specific messages (e.g., beginner, analyst, executive summary).
• Interactive Chat: Engage in an interactive conversation with GPT to further explore results.
• CLI Support: Easily run SHAP analysis and explanations directly from the command line.

Installation

Install the library using pip:

pip install xai-gpt-shap

Running

After installing the package, you can run it directly from the terminal using the xai-gpt-shap command.

Example:

xai-gpt-shap  --model_path YOUR_MODEL_PATH \
        --data_path YOUR_DATA_PATH \
        --instance_path YOUR_INSTANCE_PATH \
        --target_class YOUR_TARGET_CLASS \
        --output_csv YOUR_OUTPUT_FILE_PATH \
        --role YOUR_DESIRED_ROLES \
        --api_key YOUR_API_KEY

Available Options:

• --api_key: Your OpenAI API key.
• --model_path: Path to the saved machine learning model (e.g., model.pkl or model.onnx).
• --data_path: Path to the dataset used for SHAP analysis (e.g., data.csv).
• --instance_path: Path to a CSV file containing the instance to analyze (e.g., instance.csv).
• --target_class: The target class for SHAP analysis (e.g., 1 for binary classification).
• --role: Role for the GPT explanation (beginner, student, analyst, researcher, executive_summary).
• --interactive: Enable interactive chat mode after the initial explanation.
• --show_waterfall: If flag shown it display's SHAP results in a graph in a seperate window.

3. Programmatic Usage

You can also use the library programmatically in Python scripts.

Example Code:

from xai_gpt_shap import ChatGptClient, ShapCalculator
import shap
# Initialize the SHAP calculator
calculator = ShapCalculator(model_path="./model.pkl", data_path="./data.csv", target_class=1)
calculator.load_model()
calculator.load_data()

# Select an instance for SHAP analysis
selected_instance = calculator.data.iloc[[0]] 

# we receive resulsts from shap analysis as an DataFrame and 
# numpy.ndarray: A 1D array containing SHAP values for the specified target class. compatible for plotting results
shap_results, shap_results_for_waterfall = calculator.calculate_shap_values_for_instance(selected_instance)

# we can plot the results
shap.plots.waterfall(shap_results_for_waterfall[0], max_display=14)   

# Initialize ChatGPT client
gpt_client = ChatGptClient(api_key="YOUR_API_KEY")


# Generate a role-specific explanation
message = gpt_client.create_summary_and_message(
    shap_df=shap_results,
    model="XGBoost",
    short_summary="Predicted income > 50k",
    choice_class=1,
    role="beginner",
)

# For testing purposes seting print_response to false, default is true
response = gpt_client.send_initial_prompt(message,print_response=False)

# manually printing response
print(response)

# Start an interactive chat for follow-up questions
gpt_client.interactive_chat()

How to Use Roles

Using CLI

You can specify a role by using the --role option in the CLI.

xai-gpt-shap --role beginner

Using programaticaly

You can also specify a role programmaticaly by using the get_role_message function.

from xai_gpt_shap import get_role_message

# Example: Get role message for "pirate"
role_message = get_role_message("pirate")
print(role_message)

Supported Model Formats

This library supports the following model formats:

1. ONNX (recommended): Platform-independent and standardized format.
2. Pickle: Python models saved with pickle (e.g., Scikit-learn, XGBoost).

Note: When using Pickle models, the user must ensure that the required libraries (e.g., scikit-learn, xgboost) are installed.

Key Methods

Here’s a breakdown of key methods in the library: