ml-explain

ML model explainability reports with SHAP, feature importance, and LLM-generated narratives.

---

Feed any scikit-learn or XGBoost model + dataset to get a complete explainability report with SHAP values, feature importance analysis, and optional LLM-generated narratives via Claude.

Features

• Model Inspection - Automatically detect model type, task, feature names, and parameters
• Feature Importance - Built-in importance, permutation importance, and combined rankings
• SHAP Analysis - Auto-selects TreeExplainer or KernelExplainer based on model type
• LLM Narratives - Plain-English interpretation of results powered by Claude
• HTML Reports - Self-contained reports with embedded charts and inline CSS
• CLI Interface - One command to generate a full report from a saved model and CSV

Quick Start

Installation

pip install ml-explain

Explain a Model

from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import make_classification
from ml_explain.report import generate_report

# Train a model
X, y = make_classification(n_samples=500, n_features=10, random_state=42)
model = RandomForestClassifier(n_estimators=100, random_state=42)
model.fit(X, y)

# Generate report
result = generate_report(model, X, y, output_dir="./report_output")
print(f"Report saved to: {result.html_path}")

CLI Usage

# Save your model first
python -c "
import joblib
from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import make_classification
X, y = make_classification(n_samples=200, n_features=5, random_state=42)
model = RandomForestClassifier(random_state=42).fit(X, y)
joblib.dump(model, 'model.joblib')
import pandas as pd
df = pd.DataFrame(X, columns=[f'f{i}' for i in range(5)])
df['target'] = y
df.to_csv('data.csv', index=False)
"

# Generate the report
ml-explain explain --model model.joblib --data data.csv --target target --output-dir ./output

# Without LLM narrative
ml-explain explain --model model.joblib --data data.csv --target target --no-narrate

With LLM Narrative

Set your Anthropic API key to get AI-generated interpretations:

export ANTHROPIC_API_KEY=your-key-here
ml-explain explain --model model.joblib --data data.csv --target target

API Reference

Inspector

from ml_explain.inspector import inspect_model

info = inspect_model(model)
print(info.model_type)      # "sklearn._forest.RandomForestClassifier"
print(info.is_classifier)   # True
print(info.n_features)      # 10
print(info.supports_shap)   # True

Feature Importance

from ml_explain.feature_importance import permutation_importance, builtin_importance, combined_importance

# Permutation importance
perm_df = permutation_importance(model, X, y)

# Built-in (coef_ or feature_importances_)
builtin_df = builtin_importance(model)

# Combined view
combined_df = combined_importance(model, X, y)

SHAP Analysis

from ml_explain.shap_analyzer import compute_shap_values, plot_shap_summary

result = compute_shap_values(model, X)
plot_shap_summary(result, "shap_summary.png")

License

MIT - see LICENSE for details.