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.

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.

• 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

You can install shap-monitor via pip:

pip install shap-monitor

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

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

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.

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

• 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

• Python 3.11 or higher
• Poetry for dependency management

# Install development dependencies
make setup

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

# Run tests
make test

# Format code
make lint

This project uses:

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

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

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

• 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

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

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