shap-monitor

Production ML explainability toolkit for monitoring SHAP values over time. Track how your model's explanations evolve, detect explanation drift, and maintain interpretability at scale.

Overview

Most SHAP tooling focuses on development and analysis. shap-monitor bridges the gap for production monitoring, helping ML teams understand when and how their models' explanations change over time, compare reasoning across model versions, and detect shifts in feature importance patterns.

Key Features

• Explanation Logging: Automatically log SHAP values for production predictions with configurable sampling
• Flexible Storage: Parquet-based storage with pluggable backend support
• Multiple Explainers: Works with TreeExplainer, LinearExplainer, and other SHAP explainers

Installation

You can install shap-monitor via pip:

pip install shap-monitor

Installation from Source

This project uses Poetry for dependency management. Ensure you have Python 3.10 or higher installed.

# Clone the repository
git clone https://github.com/ab93/shap-monitor.git
cd shap-monitor

# Install with Poetry
poetry install

# Or install for development with all dev dependencies
poetry install --with dev

Quick Start

Here's a minimal example to get started with shap-monitor:

from shapmonitor import SHAPMonitor
import shap
from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import make_classification

# Train a simple model
X, y = make_classification(n_samples=1000, n_features=10, random_state=42)
model = RandomForestClassifier(random_state=42)
model.fit(X, y)

# Create SHAP explainer
explainer = shap.TreeExplainer(model)

# Initialize the monitor
monitor = SHAPMonitor(
    explainer=explainer,
    data_dir="./shap_logs",
    sample_rate=0.1,  # Log 10% of predictions
    model_version="v1.0",
    feature_names=[f"feature_{i}" for i in range(10)]
)

# In your prediction loop
predictions = model.predict(X[:100])
monitor.log_batch(X[:100], predictions)

# Or compute SHAP values directly
explanation = monitor.compute(X[:10])

The monitor will automatically:

1. Sample predictions based on the configured sample_rate
2. Compute SHAP values for sampled predictions
3. Store explanations to Parquet files in the specified data_dir

Command-Line Interface

shap-monitor includes an optional CLI for inspecting logged SHAP data from the terminal. Install it with:

pip install shap-monitor[cli]
# or with pipx for an isolated install:
pipx install shap-monitor[cli]

The CLI provides four commands:

# Log SHAP values for a batch of predictions
shapmonitor log batch.csv --model model.pkl --data-dir ./shap_logs

# View a summary of feature importances
shapmonitor report summary --data-dir ./shap_logs --period last-7d

# Compare drift between two time periods
shapmonitor report drift --data-dir ./shap_logs --ref last-14d..last-7d --curr last-7d..now

# Launch a live monitoring dashboard (TUI)
shapmonitor watch --data-dir ./shap_logs

All report commands support --json for machine-readable output (e.g. shapmonitor report summary --json | jq). Run shapmonitor --help for full usage details.

Current Status

This project is in early development (v0.1). The core functionality is being actively developed.

Roadmap

• v0.1 (Current): Core synchronous monitoring, Parquet storage
• v0.2 (Planned): Drift detection, asynchronous processing, MLflow integration
• v0.3+ (Future): Dashboard/visualization, additional framework integrations, advanced alerting

Development

Prerequisites

• Python 3.11 or higher
• Poetry for dependency management

Setup

# Install development dependencies
make setup

# Install pre-commit hooks
poetry run pre-commit install

# Run tests
make test

# Format code
make lint

Code Quality

This project uses:

• black for code formatting (line length: 100)
• ruff for linting
• pytest for testing
• pre-commit for automated checks

Contributing

Contributions are welcome! This project is in early development, and we're building the foundation for production ML explainability monitoring.

How to Contribute

1. Report Issues: Found a bug or have a feature request? Open an issue on GitHub
2. Submit Pull Requests:
   • Fork the repository
   • Create a feature branch (git checkout -b feature/your-feature)
   • Make your changes with tests
   • Ensure code passes all checks (poetry run pytest && poetry run black . && poetry run ruff check .)
   • Submit a pull request

Development Guidelines

• Write tests for new features
• Follow existing code style (enforced by black and ruff)
• Use type hints for all function signatures
• Add docstrings for public APIs
• Keep commits focused and write clear commit messages

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Acknowledgments

Built on top of the excellent SHAP library by Scott Lundberg and the SHAP community.