1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297

import numpy as np
import shap
from lime.lime_tabular import LimeTabularExplainer
from sklearn.inspection import permutation_importance, PartialDependenceDisplay
import matplotlib.pyplot as plt
 
class AutoMLExplainer:
    """
    Comprehensive explainability toolkit for AutoML models.
    
    Provides multiple explanation methods to understand model behavior
    at global (model-wide) and local (single prediction) levels.
    """
    
    def __init__(self, model, X_train, feature_names=None):
        """
        Args:
            model: Trained model with predict/predict_proba methods
            X_train: Training data for background/reference
            feature_names: List of feature names
        """
        self.model = model
        self.X_train = X_train
        self.feature_names = feature_names or [f'feature_{i}' for i in range(X_train.shape[1])]
        
        # Initialize SHAP explainer (auto-selects appropriate type)
        self._init_shap_explainer()
        
    def _init_shap_explainer(self):
        """Initialize SHAP explainer with appropriate backend."""
        try:
            # Try TreeExplainer for tree-based models (fast)
            self.shap_explainer = shap.TreeExplainer(self.model)
            self.shap_type = 'tree'
        except:
            try:
                # Fall back to KernelExplainer (model-agnostic but slower)
                background = shap.kmeans(self.X_train, 50)  # Summarized background
                self.shap_explainer = shap.KernelExplainer(
                    self.model.predict_proba if hasattr(self.model, 'predict_proba') 
                    else self.model.predict,
                    background
                )
                self.shap_type = 'kernel'
            except:
                self.shap_explainer = None
                self.shap_type = None
    
    # ========================
    # Global Explanations
    # ========================
    
    def global_feature_importance(self, X_test=None, method='shap'):
        """
        Compute global feature importance.
        
        Args:
            X_test: Test data for importance computation
            method: 'shap' or 'permutation'
            
        Returns:
            Dict of feature_name -> importance_score
        """
        if X_test is None:
            X_test = self.X_train[:1000]  # Use subset
            
        if method == 'shap' and self.shap_explainer:
            shap_values = self.shap_explainer.shap_values(X_test)
            
            # Handle multi-class case
            if isinstance(shap_values, list):
                shap_values = shap_values[1]  # Positive class for binary
            
            importance = np.abs(shap_values).mean(axis=0)
            
        elif method == 'permutation':
            result = permutation_importance(
                self.model, X_test, 
                self.model.predict(X_test) if hasattr(self.model, 'predict') else None,
                n_repeats=10, random_state=42
            )
            importance = result.importances_mean
        else:
            raise ValueError(f"Unknown method: {method}")
        
        # Create sorted importance dict
        importance_dict = dict(zip(self.feature_names, importance))
        importance_dict = dict(sorted(importance_dict.items(), 
                                      key=lambda x: x[1], reverse=True))
        
        return importance_dict
    
    def plot_global_importance(self, X_test=None, top_n=20):
        """Plot global feature importance using SHAP summary plot."""
        if X_test is None:
            X_test = self.X_train[:500]
            
        shap_values = self.shap_explainer.shap_values(X_test)
        
        if isinstance(shap_values, list):
            shap_values = shap_values[1]
        
        shap.summary_plot(
            shap_values, X_test,
            feature_names=self.feature_names,
            max_display=top_n,
            show=True
        )
    
    def partial_dependence(self, feature_idx, X_sample=None, grid_resolution=50):
        """
        Compute partial dependence for a single feature.
        
        Shows average model prediction as feature varies across its range.
        """
        if X_sample is None:
            X_sample = self.X_train[:500]
            
        PartialDependenceDisplay.from_estimator(
            self.model, X_sample, [feature_idx],
            feature_names=self.feature_names,
            grid_resolution=grid_resolution
        )
        plt.show()
    
    # ========================
    # Local Explanations
    # ========================
    
    def explain_instance_shap(self, instance):
        """
        Explain single prediction using SHAP.
        
        Args:
            instance: Single input sample (1D or 2D array)
            
        Returns:
            Dict with explanation details
        """
        instance = np.atleast_2d(instance)
        
        shap_values = self.shap_explainer.shap_values(instance)
        
        if isinstance(shap_values, list):
            shap_values = shap_values[1]  # Positive class
        
        # Get prediction
        if hasattr(self.model, 'predict_proba'):
            prediction = self.model.predict_proba(instance)[0]
        else:
            prediction = self.model.predict(instance)[0]
        
        # Create explanation
        contributions = dict(zip(self.feature_names, shap_values[0]))
        contributions = dict(sorted(contributions.items(), 
                                   key=lambda x: abs(x[1]), reverse=True))
        
        return {
            'prediction': prediction,
            'base_value': self.shap_explainer.expected_value,
            'contributions': contributions,
            'shap_values': shap_values[0],
        }
    
    def explain_instance_lime(self, instance, num_features=10):
        """
        Explain single prediction using LIME.
        
        Args:
            instance: Single input sample (1D array)
            num_features: Number of top features to show
            
        Returns:
            LIME explanation object
        """
        explainer = LimeTabularExplainer(
            self.X_train,
            feature_names=self.feature_names,
            mode='classification' if hasattr(self.model, 'predict_proba') else 'regression',
            discretize_continuous=True,
        )
        
        if hasattr(self.model, 'predict_proba'):
            predict_fn = self.model.predict_proba
        else:
            predict_fn = self.model.predict
        
        explanation = explainer.explain_instance(
            instance,
            predict_fn,
            num_features=num_features,
        )
        
        return explanation
    
    def counterfactual_explanation(self, instance, target_class, max_changes=3):
        """
        Find minimal changes to flip prediction to target class.
        
        Simplified implementation using feature importance to guide search.
        """
        instance = np.atleast_2d(instance).copy()
        original_pred = self.model.predict(instance)[0]
        
        if original_pred == target_class:
            return {'message': 'Already predicted as target class', 'changes': []}
        
        # Get feature importance for this instance
        shap_explanation = self.explain_instance_shap(instance[0])
        sorted_features = list(shap_explanation['contributions'].keys())
        
        changes = []
        modified = instance.copy()
        
        for i, feature in enumerate(sorted_features[:max_changes]):
            feat_idx = self.feature_names.index(feature)
            
            # Try changing this feature
            # Simple strategy: move toward mean of target class
            # In practice, would use more sophisticated perturbation
            original_value = modified[0, feat_idx]
            
            # Perturb toward opposite direction of SHAP contribution
            contribution = shap_explanation['contributions'][feature]
            perturbation = -np.sign(contribution) * np.std(self.X_train[:, feat_idx])
            modified[0, feat_idx] += perturbation
            
            new_pred = self.model.predict(modified)[0]
            
            changes.append({
                'feature': feature,
                'original_value': original_value,
                'new_value': modified[0, feat_idx],
                'prediction_after': new_pred,
            })
            
            if new_pred == target_class:
                break
        
        return {
            'original_prediction': original_pred,
            'target_class': target_class,
            'final_prediction': self.model.predict(modified)[0],
            'changes': changes,
            'success': self.model.predict(modified)[0] == target_class,
        }
    
    # ========================
    # Explanation Reports
    # ========================
    
    def generate_explanation_report(self, instance, include_global=True):
        """
        Generate comprehensive explanation report for a prediction.
        """
        report = []
        report.append("=" * 60)
        report.append("MODEL EXPLANATION REPORT")
        report.append("=" * 60)
        
        # Prediction
        if hasattr(self.model, 'predict_proba'):
            proba = self.model.predict_proba(np.atleast_2d(instance))[0]
            pred = self.model.predict(np.atleast_2d(instance))[0]
            report.append(f"\nPrediction: Class {pred}")
            report.append(f"Probability: {proba[int(pred)]:.3f}")
        else:
            pred = self.model.predict(np.atleast_2d(instance))[0]
            report.append(f"\nPrediction: {pred:.4f}")
        
        # Local SHAP explanation
        report.append("\n" + "-" * 40)
        report.append("LOCAL FEATURE CONTRIBUTIONS (SHAP)")
        report.append("-" * 40)
        
        shap_exp = self.explain_instance_shap(instance)
        for i, (feature, contribution) in enumerate(shap_exp['contributions'].items()):
            if i >= 10:  # Top 10
                break
            direction = "↑" if contribution > 0 else "↓"
            report.append(f"{feature}: {contribution:+.4f} {direction}")
        
        # Global importance (optional)
        if include_global:
            report.append("\n" + "-" * 40)
            report.append("GLOBAL FEATURE IMPORTANCE")
            report.append("-" * 40)
            
            importance = self.global_feature_importance(method='shap')
            for i, (feature, imp) in enumerate(importance.items()):
                if i >= 10:
                    break
                report.append(f"{feature}: {imp:.4f}")
        
        report.append("\n" + "=" * 60)
        
        return "\n".join(report)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

"""
Constrain AutoML to Interpretable Models
"""
 
# ============================================
# InterpretML: Explainable Boosting Machine
# ============================================
from interpret.glassbox import ExplainableBoostingClassifier
from interpret import show
 
# EBM is a GAM that achieves near-black-box accuracy
# while remaining fully interpretable
ebm = ExplainableBoostingClassifier(
    max_bins=256,
    interactions=10,           # Number of pairwise interactions
    outer_bags=8,
    inner_bags=0,
    learning_rate=0.01,
    validation_size=0.15,
    early_stopping_rounds=50,
    n_jobs=-1,
)
 
ebm.fit(X_train, y_train)
 
# Global interpretation
ebm_global = ebm.explain_global()
show(ebm_global)
 
# Local interpretation
ebm_local = ebm.explain_local(X_test[:5], y_test[:5])
show(ebm_local)
 
# ============================================
# Auto-sklearn: Constrained to Interpretable
# ============================================
from autosklearn.classification import AutoSklearnClassifier
 
# Only allow interpretable classifiers
interpretable_automl = AutoSklearnClassifier(
    time_left_for_this_task=1800,
    per_run_time_limit=180,
    
    # Restrict to interpretable models only
    include={
        'classifier': [
            'decision_tree',
            'extra_trees',
            'k_nearest_neighbors',  # Instance-based, explainable via examples
        ],
    },
    
    # Further constrain decision tree depth for interpretability
    # (via initial_configurations_via_metalearning)
    
    ensemble_size=1,      # No ensemble = more interpretable
    ensemble_nbest=1,
)
 
# ============================================
# GAMs with pyGAM
# ============================================
from pygam import LogisticGAM, s, f
 
# Build GAM with specified smoothness
gam = LogisticGAM(
    s(0) +   # Smooth term for feature 0
    s(1) +   # Smooth term for feature 1
    f(2) +   # Factor (categorical) for feature 2
    s(3, n_splines=8, spline_order=3)  # Customized smoothness
)
 
gam.fit(X_train, y_train)
 
# Visualize individual feature effects
for i, feature in enumerate(feature_names[:5]):
    XX = gam.generate_X_grid(term=i)
    plt.figure()
    plt.plot(XX[:, i], gam.partial_dependence(term=i, X=XX))
    plt.title(f'Partial Dependence: {feature}')
    plt.show()
 
# ============================================
# Rule Lists with CORELS
# ============================================
# Note: CORELS produces certifiably optimal rule lists
# Requires discretized features
 
from corels import CorelsClassifier
 
# Discretize features for rule learning
from sklearn.preprocessing import KBinsDiscretizer
discretizer = KBinsDiscretizer(n_bins=5, encode='onehot-dense', strategy='quantile')
X_discrete = discretizer.fit_transform(X_train)
 
# Generate feature names for discretized features
discrete_feature_names = []
for i, edges in enumerate(discretizer.bin_edges_):
    for j in range(len(edges) - 1):
        discrete_feature_names.append(f'{feature_names[i]}_bin{j}')
 
# Train CORELS
corels = CorelsClassifier(
    max_card=2,               # Max features per rule
    c=0.001,                  # Regularization (larger = simpler rules)
    policy='curious',
    verbosity=[]
)
 
corels.fit(X_discrete, y_train, features=discrete_feature_names)
 
# Print learned rules
print(corels.rl().rules)
 
# ============================================
# Decision Tree with Depth Limit
# ============================================
from sklearn.tree import DecisionTreeClassifier, export_text, plot_tree
 
# Shallow tree for interpretability
shallow_tree = DecisionTreeClassifier(
    max_depth=4,              # Human-comprehensible depth
    min_samples_leaf=50,      # Statistically reliable leaves
    min_impurity_decrease=0.01,
)
 
shallow_tree.fit(X_train, y_train)
 
# Export as text rules
rules = export_text(shallow_tree, feature_names=feature_names)
print(rules)
 
# Visual representation
plt.figure(figsize=(20, 10))
plot_tree(
    shallow_tree,
    feature_names=feature_names,
    class_names=['Negative', 'Positive'],
    filled=True,
    rounded=True,
    fontsize=10
)
plt.tight_layout()
plt.savefig('decision_tree.png', dpi=150)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

"""
Model Documentation for Regulatory Compliance
"""
 
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from datetime import datetime
import json
 
@dataclass
class ModelCard:
    """
    Model documentation following industry best practices.
    
    Based on Google Model Cards (Mitchell et al., 2019) and
    regulatory requirements for model risk management.
    """
    
    # Basic Information
    model_name: str
    version: str
    created_date: datetime
    author: str
    owner: str
    
    # Model Details
    model_type: str                      # e.g., "XGBoost Classifier"
    automl_system: str                   # e.g., "AutoGluon v0.8.0"
    parameters: Dict                     # Key hyperparameters
    training_time_hours: float
    
    # Intended Use
    primary_use_case: str
    intended_users: List[str]
    out_of_scope_uses: List[str]
    
    # Training Data
    training_data_description: str
    training_data_size: int
    training_data_date_range: str
    feature_list: List[str]
    target_variable: str
    
    # Performance Metrics
    performance_metrics: Dict[str, float]  # metric_name -> value
    performance_by_subgroup: Optional[Dict] = None  # For fairness
    
    # Fairness Analysis
    protected_attributes_used: List[str] = field(default_factory=list)
    fairness_metrics: Dict[str, float] = field(default_factory=dict)
    disparate_impact_analysis: Optional[str] = None
    
    # Explainability
    explainability_approach: str = ""     # e.g., "SHAP with TreeExplainer"
    global_feature_importance: Dict[str, float] = field(default_factory=dict)
    example_explanations: List[Dict] = field(default_factory=list)
    
    # Limitations and Risks
    known_limitations: List[str] = field(default_factory=list)
    ethical_considerations: List[str] = field(default_factory=list)
    out_of_distribution_warning: str = ""
    
    # Maintenance
    retraining_frequency: str = ""
    monitoring_metrics: List[str] = field(default_factory=list)
    model_drift_detection: str = ""
    
    def to_json(self) -> str:
        """Serialize to JSON for storage."""
        data = {
            'created_date': self.created_date.isoformat(),
            **{k: v for k, v in self.__dict__.items() if k != 'created_date'}
        }
        return json.dumps(data, indent=2)
    
    def generate_report(self) -> str:
        """Generate human-readable model card report."""
        lines = [
            "=" * 70,
            f"MODEL CARD: {self.model_name} (v{self.version})",
            "=" * 70,
            "",
            "OVERVIEW",
            "-" * 40,
            f"Model Type: {self.model_type}",
            f"AutoML System: {self.automl_system}",
            f"Created: {self.created_date.strftime('%Y-%m-%d')}",
            f"Author: {self.author}",
            f"Owner: {self.owner}",
            "",
            "INTENDED USE",
            "-" * 40,
            f"Primary Use: {self.primary_use_case}",
            f"Users: {', '.join(self.intended_users)}",
            "Out of Scope:",
            *[f"  - {use}" for use in self.out_of_scope_uses],
            "",
            "TRAINING DATA",
            "-" * 40,
            f"Description: {self.training_data_description}",
            f"Size: {self.training_data_size:,} samples",
            f"Date Range: {self.training_data_date_range}",
            f"Features: {len(self.feature_list)} features",
            f"Target: {self.target_variable}",
            "",
            "PERFORMANCE",
            "-" * 40,
            *[f"{metric}: {value:.4f}" for metric, value in self.performance_metrics.items()],
        ]
        
        if self.fairness_metrics:
            lines.extend([
                "",
                "FAIRNESS ANALYSIS",
                "-" * 40,
                *[f"{metric}: {value:.4f}" for metric, value in self.fairness_metrics.items()],
            ])
        
        if self.global_feature_importance:
            lines.extend([
                "",
                "TOP FEATURES",
                "-" * 40,
            ])
            sorted_features = sorted(
                self.global_feature_importance.items(),
                key=lambda x: x[1],
                reverse=True
            )
            for feature, importance in sorted_features[:10]:
                lines.append(f"  {feature}: {importance:.4f}")
        
        if self.known_limitations:
            lines.extend([
                "",
                "LIMITATIONS",
                "-" * 40,
                *[f"  - {limitation}" for limitation in self.known_limitations],
            ])
        
        if self.ethical_considerations:
            lines.extend([
                "",
                "ETHICAL CONSIDERATIONS",
                "-" * 40,
                *[f"  - {consideration}" for consideration in self.ethical_considerations],
            ])
        
        lines.extend([
            "",
            "MAINTENANCE",
            "-" * 40,
            f"Retraining: {self.retraining_frequency}",
            f"Monitored Metrics: {', '.join(self.monitoring_metrics)}",
            "",
            "=" * 70,
        ])
        
        return "\n".join(lines)
 
 
# Example usage
model_card = ModelCard(
    model_name="Customer Churn Predictor",
    version="2.1.0",
    created_date=datetime.now(),
    author="ML Team",
    owner="Customer Success Department",
    model_type="LightGBM Classifier (AutoML Ensemble)",
    automl_system="AutoGluon v0.8.0",
    parameters={'num_boost_round': 500, 'learning_rate': 0.05},
    training_time_hours=2.5,
    primary_use_case="Predict 30-day customer churn probability",
    intended_users=["Customer Success Managers", "Retention Team"],
    out_of_scope_uses=[
        "Individual customer decisions without human review",
        "Legal or contract enforcement",
    ],
    training_data_description="12 months of customer behavior data",
    training_data_size=250000,
    training_data_date_range="2023-01-01 to 2023-12-31",
    feature_list=["tenure", "usage_last_30d", "support_tickets", "..."],
    target_variable="churned_within_30d",
    performance_metrics={
        "AUC": 0.847,
        "Precision@10%": 0.62,
        "Recall@10%": 0.35,
    },
    fairness_metrics={
        "Demographic Parity (Gender)": 0.03,
        "Equalized Odds (Age Group)": 0.05,
    },
    global_feature_importance={
        "usage_decline_rate": 0.23,
        "days_since_last_login": 0.18,
        "support_tickets_30d": 0.12,
    },
    known_limitations=[
        "Performance degrades for customers < 30 days tenure",
        "Not validated for enterprise segment",
    ],
    ethical_considerations=[
        "Churn interventions should not be discriminatory",
        "Model outputs are probabilistic, not deterministic",
    ],
    retraining_frequency="Monthly",
    monitoring_metrics=["AUC", "Calibration", "Feature drift"],
)
 
print(model_card.generate_report())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238

"""
Templates for Stakeholder-Appropriate Explanations
"""
 
from typing import Dict, List
 
class ExplanationGenerator:
    """
    Generate stakeholder-appropriate explanations from raw model outputs.
    """
    
    def __init__(
        self,
        feature_descriptions: Dict[str, str],
        class_names: List[str] = None,
    ):
        """
        Args:
            feature_descriptions: Human-readable descriptions for each feature
            class_names: Names for prediction classes
        """
        self.feature_descriptions = feature_descriptions
        self.class_names = class_names or ['Negative', 'Positive']
    
    def explain_for_end_user(
        self,
        prediction: int,
        probability: float,
        top_factors: List[Dict],  # [{feature, contribution, value}]
    ) -> str:
        """
        Generate plain-language explanation for end user.
        
        Focus on actionable insights and clear language.
        """
        class_name = self.class_names[prediction]
        
        # Determine confidence level in plain language
        if probability > 0.9:
            confidence = "very likely"
        elif probability > 0.7:
            confidence = "likely"
        elif probability > 0.5:
            confidence = "somewhat likely"
        else:
            confidence = "less likely"
        
        lines = [
            f"**Outcome**: {class_name}",
            f"**Confidence**: This outcome is {confidence} ({probability:.0%} probability)",
            "",
            "**Key Factors in This Decision:**",
        ]
        
        for i, factor in enumerate(top_factors[:3], 1):
            feature = factor['feature']
            contribution = factor['contribution']
            
            # Get human-readable description
            description = self.feature_descriptions.get(
                feature, 
                feature.replace('_', ' ').title()
            )
            
            # Determine direction
            if contribution > 0:
                direction = "increased" if prediction == 1 else "decreased"
            else:
                direction = "decreased" if prediction == 1 else "increased"
            
            lines.append(f"{i}. Your {description} {direction} the likelihood of this outcome.")
        
        lines.extend([
            "",
            "*This explanation highlights the main factors but does not capture all model inputs.*",
        ])
        
        return "\n".join(lines)
    
    def explain_for_business(
        self,
        predictions_summary: Dict,
        feature_importance: Dict[str, float],
        business_metrics: Dict[str, float],
    ) -> str:
        """
        Generate business-oriented summary of model behavior.
        """
        lines = [
            "## Model Behavior Summary",
            "",
            "### Key Prediction Drivers",
            "",
        ]
        
        # Top features with business context
        sorted_features = sorted(
            feature_importance.items(),
            key=lambda x: abs(x[1]),
            reverse=True
        )
        
        for feature, importance in sorted_features[:5]:
            description = self.feature_descriptions.get(
                feature,
                feature.replace('_', ' ').title()
            )
            pct = importance * 100
            lines.append(f"- **{description}**: {pct:.1f}% importance")
        
        lines.extend([
            "",
            "### Business Impact",
            "",
        ])
        
        for metric, value in business_metrics.items():
            lines.append(f"- {metric}: {value:.2%}")
        
        lines.extend([
            "",
            "### Recommendations",
            "",
            "1. Focus retention efforts on high-risk segments identified by top factors",
            "2. Monitor feature distributions for drift that may affect model accuracy",
            "3. Review decisions in borderline (40-60% probability) cases manually",
        ])
        
        return "\n".join(lines)
    
    def explain_for_regulator(
        self,
        model_card: Dict,
        fairness_report: Dict,
        audit_sample: List[Dict],
    ) -> str:
        """
        Generate regulatory compliance report.
        """
        lines = [
            "# Model Compliance Report",
            "",
            "## Model Overview",
            f"- Model Name: {model_card['name']}",
            f"- Version: {model_card['version']}",
            f"- Purpose: {model_card['purpose']}",
            f"- Model Type: {model_card['model_type']}",
            "",
            "## Fairness Analysis",
            "",
        ]
        
        for metric, value in fairness_report.items():
            status = "✓ PASS" if value < 0.1 else "⚠ REVIEW"
            lines.append(f"- {metric}: {value:.4f} {status}")
        
        lines.extend([
            "",
            "## Sample Decisions with Explanations",
            "",
        ])
        
        for i, sample in enumerate(audit_sample[:5], 1):
            lines.extend([
                f"### Decision {i}",
                f"- Outcome: {sample['prediction']}",
                f"- Probability: {sample['probability']:.3f}",
                f"- Top Factor: {sample['top_factor']}",
                "",
            ])
        
        lines.extend([
            "## Attestations",
            "",
            "- [ ] Model validated by independent team",
            "- [ ] Fairness metrics reviewed and approved",
            "- [ ] Human-in-loop procedures documented",
            "- [ ] Monitoring alerts configured",
        ])
        
        return "\n".join(lines)
    
    def generate_decision_rationale(
        self,
        instance_values: Dict[str, float],
        shap_contributions: Dict[str, float],
        prediction: int,
        probability: float,
    ) -> str:
        """
        Generate detailed rationale for individual decision.
        Suitable for adverse action notices (loan denial, etc.)
        """
        class_name = self.class_names[prediction]
        
        # Sort contributions by absolute value
        sorted_contributions = sorted(
            shap_contributions.items(),
            key=lambda x: abs(x[1]),
            reverse=True
        )
        
        lines = [
            f"Decision: {class_name}",
            f"Confidence: {probability:.1%}",
            "",
            "Principal Factors Contributing to This Decision:",
            "",
        ]
        
        for i, (feature, contribution) in enumerate(sorted_contributions[:4], 1):
            description = self.feature_descriptions.get(
                feature,
                feature.replace('_', ' ')
            )
            value = instance_values.get(feature, 'N/A')
            
            if contribution > 0:
                effect = "contributed positively to"
            else:
                effect = "contributed negatively to"
            
            lines.append(
                f"{i}. {description} (your value: {value}) {effect} this outcome"
            )
        
        return "\n".join(lines)
 
 
# Example feature descriptions
FEATURE_DESCRIPTIONS = {
    'credit_score': 'credit score',
    'debt_to_income': 'debt-to-income ratio',
    'years_employed': 'employment history',
    'recent_inquiries': 'recent credit inquiries',
    'payment_history': 'payment history',
    'account_age': 'credit account age',
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196

import numpy as np
from typing import List, Dict, Callable
from scipy import stats
 
class ExplanationValidator:
    """
    Validate quality of model explanations.
    """
    
    def __init__(self, model, explainer):
        self.model = model
        self.explainer = explainer
    
    def test_fidelity(
        self,
        X: np.ndarray,
        explanations: List[Dict],
        top_k: int = 3,
    ) -> Dict:
        """
        Test explanation fidelity by removing top features.
        
        If explanations are faithful, removing top-importance features
        should significantly change predictions.
        """
        results = []
        
        for i, (x, explanation) in enumerate(zip(X, explanations)):
            original_pred = self.model.predict_proba(x.reshape(1, -1))[0, 1]
            
            # Get top-k important features
            top_features = sorted(
                explanation['contributions'].items(),
                key=lambda x: abs(x[1]),
                reverse=True
            )[:top_k]
            
            # Zero out top features
            x_modified = x.copy()
            for feature_idx, _ in top_features:
                if isinstance(feature_idx, str):
                    # Convert feature name to index
                    feature_idx = list(explanation['contributions'].keys()).index(feature_idx)
                x_modified[feature_idx] = 0
            
            modified_pred = self.model.predict_proba(x_modified.reshape(1, -1))[0, 1]
            
            results.append({
                'original_pred': original_pred,
                'modified_pred': modified_pred,
                'change': abs(original_pred - modified_pred),
            })
        
        avg_change = np.mean([r['change'] for r in results])
        
        return {
            'avg_prediction_change': avg_change,
            'fidelity_score': min(avg_change * 5, 1.0),  # Scale to [0, 1]
            'passed': avg_change > 0.1,  # Expect >10% change
            'details': results,
        }
    
    def test_stability(
        self,
        X: np.ndarray,
        noise_level: float = 0.01,
        n_perturbations: int = 10,
    ) -> Dict:
        """
        Test explanation stability under small perturbations.
        
        Similar inputs should have similar explanations.
        """
        stabilities = []
        
        for x in X[:50]:  # Test subset
            # Get original explanation
            original_exp = self.explainer.explain_instance_shap(x)
            original_top3 = set(
                list(original_exp['contributions'].keys())[:3]
            )
            
            # Generate perturbed versions
            agreement_scores = []
            for _ in range(n_perturbations):
                noise = np.random.normal(0, noise_level * np.std(X, axis=0), x.shape)
                x_perturbed = x + noise
                
                perturbed_exp = self.explainer.explain_instance_shap(x_perturbed)
                perturbed_top3 = set(
                    list(perturbed_exp['contributions'].keys())[:3]
                )
                
                # Jaccard similarity of top-3 features
                agreement = len(original_top3 & perturbed_top3) / len(original_top3 | perturbed_top3)
                agreement_scores.append(agreement)
            
            stabilities.append(np.mean(agreement_scores))
        
        avg_stability = np.mean(stabilities)
        
        return {
            'avg_stability': avg_stability,
            'stability_std': np.std(stabilities),
            'passed': avg_stability > 0.7,  # Expect >70% agreement
            'interpretation': 'High' if avg_stability > 0.8 else 'Medium' if avg_stability > 0.6 else 'Low',
        }
    
    def test_consistency_across_methods(
        self,
        X: np.ndarray,
        lime_explainer,
    ) -> Dict:
        """
        Test consistency between SHAP and LIME explanations.
        
        Major disagreements suggest unreliable explanations.
        """
        agreements = []
        
        for x in X[:30]:
            # SHAP explanation
            shap_exp = self.explainer.explain_instance_shap(x)
            shap_top5 = set(list(shap_exp['contributions'].keys())[:5])
            
            # LIME explanation
            lime_exp = lime_explainer.explain_instance(
                x,
                self.model.predict_proba,
                num_features=5,
            )
            lime_top5 = set([f for f, _ in lime_exp.as_list()][:5])
            
            # Calculate overlap
            overlap = len(shap_top5 & lime_top5) / 5
            agreements.append(overlap)
        
        avg_agreement = np.mean(agreements)
        
        return {
            'avg_shap_lime_agreement': avg_agreement,
            'passed': avg_agreement > 0.5,  # Expect >50% overlap in top-5
            'interpretation': 'Consistent' if avg_agreement > 0.6 else 'Somewhat consistent' if avg_agreement > 0.4 else 'Inconsistent',
        }
    
    def generate_validation_report(
        self,
        X: np.ndarray,
        explanations: List[Dict],
        lime_explainer=None,
    ) -> str:
        """
        Generate comprehensive explanation validation report.
        """
        lines = [
            "=" * 60,
            "EXPLANATION QUALITY VALIDATION REPORT",
            "=" * 60,
        ]
        
        # Fidelity
        fidelity = self.test_fidelity(X, explanations)
        lines.extend([
            "",
            "1. FIDELITY (Accuracy of explanations)",
            f"   Avg prediction change when removing top features: {fidelity['avg_prediction_change']:.3f}",
            f"   Status: {'✓ PASS' if fidelity['passed'] else '✗ FAIL'}",
        ])
        
        # Stability
        stability = self.test_stability(X)
        lines.extend([
            "",
            "2. STABILITY (Consistency under perturbation)",
            f"   Avg top-3 feature agreement: {stability['avg_stability']:.3f}",
            f"   Interpretation: {stability['interpretation']}",
            f"   Status: {'✓ PASS' if stability['passed'] else '✗ FAIL'}",
        ])
        
        # Cross-method consistency
        if lime_explainer:
            consistency = self.test_consistency_across_methods(X, lime_explainer)
            lines.extend([
                "",
                "3. CONSISTENCY (SHAP vs LIME agreement)",
                f"   Avg top-5 overlap: {consistency['avg_shap_lime_agreement']:.3f}",
                f"   Interpretation: {consistency['interpretation']}",
                f"   Status: {'✓ PASS' if consistency['passed'] else '✗ FAIL'}",
            ])
        
        lines.extend([
            "",
            "=" * 60,
        ])
        
        return "\n".join(lines)