xai-auditor

Quantitative Explainability Auditing and Model Risk Management for Machine Learning.

xai-auditor is an independent, lightweight Python library designed to audit the reliability, stability, fidelity, consistency, manipulation resistance, distributional drift, and operational coverage of post-hoc Explainable AI (XAI) pipelines such as SHAP and LIME.

Author: Fdere AI, Explainability Auditor Team
License: Apache License 2.0
Current Version: 0.2.2

Overview

In production machine learning systems, post-hoc explanations generated by surrogate methods like SHAP and LIME are frequently used for model validation, customer adverse action notices, and regulatory compliance. However, surrogate explanations are empirical approximations that can suffer from numerical instability, cross-method disagreement, hyperparameter sensitivity, and silent attribution drift over time.

xai-auditor provides an objective, automated auditing framework to verify whether your model explanations are mathematically faithful, locally stable, consistent across methods, robust against manipulation, and stationary across production cohorts.

Key Capabilities

• Universal Model Compatibility: Works with Scikit-Learn models, gradient boosted trees (XGBoost, LightGBM, CatBoost), PyTorch/TensorFlow networks, built-in estimators, or any prediction callable returning probabilities.
• Built-in Explainers: Includes self-contained implementations of Permutation SHAP (with additivity constraints) and Kernel LIME, requiring zero external explainer dependencies.
• Six Independent Audit Dimensions: Evaluates attribution fidelity, local Lipschitz stability, cross-method consistency, adversarial manipulation resistance, explanation drift, and operational latency.
• Calibrated Scoring and Risk Tiers: Maps empirical measurements to a composite Explainability Trust Score (0 to 100) and standardized risk classifications (Low Risk, Medium Risk, High Risk, Critical Risk).
• Multi-Format Reporting: Exports structured JSON audit certificates, CLI summaries, and self-contained HTML assurance reports.
• Lightweight and Self-Contained: Core algorithms, linear algebra, and statistical distance metrics are implemented in pure Python with standard library support.

Auditing Dimensions

The overall Explainability Trust Score aggregates six evaluation dimensions using balanced governance weights:

1. Attribution Fidelity (25% weight): Evaluates whether feature attributions reflect true model decision logic through systematic feature removal (ROAR) and retention (KAR).
2. Local Lipschitz Stability (20% weight): Measures the invariance of feature importance rankings when small Gaussian perturbations are applied to input instances.
3. Cross-Method Consistency (15% weight): Quantifies agreement between independent explanation methods (such as SHAP and LIME) using Rank-Biased Overlap (RBO), top-k Jaccard similarity, and sign agreement.
4. Adversarial Manipulation Resistance (15% weight): Evaluates explanation stability across variations in explainer hyperparameters, such as kernel bandwidths and background sample sizes.
5. Distributional Explanation Drift (15% weight): Detects cohort and temporal shifts between baseline and monitoring attribution distributions using quantile stability metrics and standardized distance measures.
6. Operational Coverage and Latency (10% weight): Measures explanation generation success rates and monitors execution latency against production service level agreements.

DriftAuditor

The DriftAuditor module monitors shifts in feature attributions between baseline training distributions and incoming production monitoring data. Key capabilities in the v0.2.x engine include:

• Baseline-Anchored Empirical Quantile Binning: Quantile boundary cutpoints are established from baseline data so each bin contains equal baseline sample mass, avoiding empty bins in long-tailed attribution distributions.
• Support Boundary Expansion: Quantile boundaries dynamically adjust to encompass the full range of both baseline and monitoring samples, eliminating bin clipping on out-of-bounds values.
• Mean Quantile PSI: Population Stability Index values are computed across all feature attributions and aggregated using dimension-wide mean stability, preventing a single noisy tail feature from dominating the audit.
• Standardized Wasserstein Distance: Continuous distribution shift is measured using the closed-form one-dimensional Earth Mover Distance normalized by baseline standard deviation, ensuring scale invariance across features with different units.
• Dynamic Window Sizing: For small datasets, sample window sizes automatically adapt to available records, preventing sampling collapse.
• Hybrid Drift Scoring: Combines non-parametric bin frequency shifts and optimal transport distance into a calibrated, monotonic score between 35 and 98.
• Backward Compatibility: Fully supports legacy constructor arguments and preserves earlier metric keys (including max_feature_psi) alongside newer metrics.

Installation

Install xai-auditor from PyPI:

# Standard installation (pure Python, zero required external dependencies)
pip install xai-auditor

# Optional installation with integrations for scikit-learn, xgboost, and lightgbm
pip install xai-auditor[all]

Requirements: Python 3.8, 3.9, 3.10, 3.11, or 3.12 on Linux, macOS, or Windows.

Quick Start

from xai_auditor import Auditor
from xai_auditor.models.builtins import BuiltinLogisticRegression

# 1. Prepare tabular feature matrix and target labels
X = [
    [0.85, 1.2, 0.45, 0.90],
    [0.20, 0.4, 0.10, 0.25],
    [0.70, 1.0, 0.60, 0.75],
    [0.15, 0.3, 0.05, 0.10],
    [0.90, 1.5, 0.80, 0.95],
    [0.30, 0.5, 0.20, 0.35],
]
y = [1, 0, 1, 0, 1, 0]
feature_names = ["debt_to_income", "credit_lines", "delinquency", "utilization"]

# 2. Fit a classification model
model = BuiltinLogisticRegression().fit(X, y)

# 3. Instantiate and run the auditor
auditor = Auditor(
    model=model,
    X=X,
    y=y,
    feature_names=feature_names,
    dataset_name="Credit Underwriting Demo",
)
result = auditor.run()

# 4. Inspect audit findings
print(f"Trust Score:     {result.trust_score} / 100")
print(f"Risk Tier:       {result.risk_tier.value}")
print(f"Approval Status: {result.approval_status.value}")

DriftAuditor Usage

Use DriftAuditor independently to monitor explanation distributions between historical reference data and production cohorts:

import random
from xai_auditor import DriftAuditor
from xai_auditor.models.builtins import BuiltinLogisticRegression

feature_names = ["variance", "skewness", "curtosis", "entropy"]
model = BuiltinLogisticRegression(weights=[1.5, -2.1, 1.8, -0.4], bias=0.1)

# Baseline reference cohort
rng = random.Random(42)
X_baseline = [[rng.gauss(0.0, 1.0) for _ in range(4)] for _ in range(100)]

# Production monitoring cohort with shifted distribution
X_monitoring = [
    [row[0] + 0.8, row[1] - 0.5, row[2] + 0.3, row[3]]
    for row in [[rng.gauss(0.0, 1.0) for _ in range(4)] for _ in range(100)]
]

drift_auditor = DriftAuditor(n_samples_per_window=100, bin_strategy="quantile", seed=42)
result = drift_auditor.audit(
    model=model,
    X=X_baseline,
    X_monitoring=X_monitoring,
    feature_names=feature_names,
)

print(f"Drift Score:                   {result.score} / 100")
print(f"Mean Quantile PSI:             {result.metrics['mean_feature_psi']:.4f}")
print(f"Mean Standardized Wasserstein: {result.metrics['mean_standardized_wasserstein']:.4f}")

Full Governance Audit Example

Run a complete 6-dimension audit and export a self-contained HTML assurance report:

import random
from xai_auditor import Auditor
from xai_auditor.models.builtins import BuiltinRandomForest

# 30 diagnostic cell features (Wisconsin Diagnostic Breast Cancer schema)
feature_names = [f"cell_feature_{i+1}" for i in range(30)]

rng = random.Random(42)
X = [[rng.gauss(0.0, 1.0) for _ in range(30)] for _ in range(120)]
y = [1 if (row[0] * 1.5 + row[1] * 0.8 - row[2] * 1.2) > 0.0 else 0 for row in X]

model = BuiltinRandomForest(n_estimators=15, max_depth=4, seed=42).fit(X, y)

auditor = Auditor(
    model=model,
    X=X,
    y=y,
    feature_names=feature_names,
    dataset_name="WDBC Diagnostic Pathology Suite",
    model_name="Malignancy Classifier RF",
    explainer_type="shap",
    seed=42,
)

result = auditor.run()

print(f"Trust Score:     {result.trust_score} / 100")
print(f"Risk Tier:       {result.risk_tier.value}")
print(f"Approval Status: {result.approval_status.value}")

for dim in result.dimension_results:
    print(f" - {dim.name:<35} Score: {dim.score:>3} / 100 (Weight: {dim.weight*100:.0f}%)")

# Export report
result.save_html_report("governance_report.html")
print("HTML assurance certificate saved to governance_report.html")

Real-World Examples

1. Banknote Authentication (Stationary Baseline Verification)

import random
from xai_auditor import DriftAuditor
from xai_auditor.models.builtins import BuiltinLogisticRegression

banknote_features = ["variance_wavelet", "skewness_wavelet", "curtosis_wavelet", "entropy_wavelet"]
model = BuiltinLogisticRegression(weights=[1.5, -2.1, 1.8, -0.4], bias=0.1)

rng = random.Random(101)
all_samples = [[rng.gauss(0.0, 1.0) for _ in range(4)] for _ in range(200)]
X_baseline = all_samples[:100]
X_monitoring = all_samples[100:]

auditor = DriftAuditor(n_samples_per_window=100, bin_strategy="quantile", seed=101)
result = auditor.audit(model=model, X=X_baseline, X_monitoring=X_monitoring, feature_names=banknote_features)

print(f"Banknote IID Drift Score: {result.score} / 100 (Pass threshold: >= 75)")
print(f"Mean Quantile PSI:        {result.metrics['mean_feature_psi']:.4f}")

2. Statlog Heart Disease (Clinical Cohort Drift Audit)

import random
from xai_auditor import DriftAuditor
from xai_auditor.models.builtins import BuiltinLogisticRegression

clinical_features = [
    "age", "sex", "chest_pain", "resting_bp", "cholesterol",
    "fasting_blood_sugar", "resting_ecg", "max_heart_rate",
    "exercise_angina", "oldpeak", "slope", "num_vessels", "thal"
]
weights = [0.4, 1.2, 0.8, 0.3, 0.2, 0.1, 0.3, -0.9, 0.7, 1.1, 0.6, 1.4, 0.9]
model = BuiltinLogisticRegression(weights=weights, bias=0.0)

rng = random.Random(42)
X_base = [[rng.gauss(0.0, 1.0) for _ in range(len(clinical_features))] for _ in range(100)]
# Shift clinical stress indicators in monitoring cohort
X_mon = [
    [val + (1.0 if j in (9, 10, 11) else 0.0) for j, val in enumerate(row)]
    for row in [[rng.gauss(0.0, 1.0) for _ in range(len(clinical_features))] for _ in range(100)]
]

auditor = DriftAuditor(n_samples_per_window=100, bin_strategy="quantile", seed=42)
result = auditor.audit(model=model, X=X_base, X_monitoring=X_mon, feature_names=clinical_features)

print(f"Clinical Drift Score:          {result.score} / 100")
print(f"Mean Standardized Wasserstein: {result.metrics['mean_standardized_wasserstein']:.4f}")

Command Line Interface (CLI)

xai-auditor provides a command-line tool xai-audit for auditing datasets directly from CSV files:

# Run audit on a CSV dataset with default logistic regression model
xai-audit --data dataset.csv --target label_column

# Specify a model family and export HTML and JSON reports
xai-audit \
  --data credit_data.csv \
  --target default \
  --model random_forest \
  --output audit_certificate.json \
  --html governance_report.html

CLI options:

• --data, -d: Path to input tabular dataset CSV file (required).
• --target, -t: Name of target binary classification column (default: last column).
• --model, -m: Built-in model architecture (logistic_regression, random_forest, xgboost, mlp).
• --output, -o: Path to save machine-readable JSON audit certificate.
• --html: Path to save standalone HTML governance report.
• --quiet, -q: Suppress plain-text terminal output.

Risk Tier Classification

xai-auditor maps composite Trust Scores to standard risk classifications:

• Low Risk (85 to 100): Approved for production deployment. Explanations exhibit high fidelity, stability, consistency, and stationary distributions.
• Medium Risk (75 to 84): Approved with standard production monitoring and scheduled re-auditing.
• High Risk (60 to 74): Conditional approval; requires model governance review and enhanced monitoring.
• Critical Risk (0 to 59): Remediation required. Explanations exhibit substantial instability, unfaithfulness, or drift.

Links

• GitHub Repository: https://github.com/cleanpigg/xai-auditor
• Issue Tracker: https://github.com/cleanpigg/xai-auditor/issues
• PyPI Package: https://pypi.org/project/xai-auditor/

Credits

Author: Fdere AI, Explainability Auditor Team

License

xai-auditor is licensed under the Apache License, Version 2.0. See the LICENSE file for details.