local-black-box

# Local black-box explanations Use this route when the user wants a local, post-hoc explanation of an already trained predictor: LIME, SHAP, feature attribution, GroupedCE/ICE, nearest- neighbor contrastive examples, faithfulness, monotonicity, or an explanation visualization. Start by identifying the input representation, the model output contract, and whether the requested result is an attribution, a perturbation curve, or a contrastive exemplar. ## Choose the method - **Tabular or generic structured classification/regression:** use `LimeTabularExplainer` for a sparse local surrogate, `KernelExplainer` for model-agnostic SHAP values, or `GroupedCEExplainer` for numeric ICE/GCE perturbation curves. Use a scalar target-output callable for one class or a regressor. - **Text:** use `LimeTextExplainer` with a callable that accepts a list of raw strings and returns a two-dimensional class-probability matrix. Use SHAP's own text-compatible model-specific API only when that optional SHAP version supports it; AIX360's `KernelExplainer` wrapper does not tokenize text for you. - **Image:** use `LimeImageExplainer` with a batch image classifier callable. It returns a LIME `Explanation`; use its mask accessor for visualization. SHAP `DeepExplainer` or `GradientExplainer` is a model/backend-specific alternative, not a drop-in image adapter. - **Contrastive structured examples:** use `NearestNeighborContrastiveExplainer` when a learned embedding and examples from a different predicted class are useful. It is not recourse: it does not promise feasible, actionable, or minimal changes. - **Feature-effect inspection:** use GroupedCE with one numeric feature for ICE, or several selected numeric features for pairwise GCE grids. It is model-agnostic but needs a representative reference data frame. Read [API reference](references/api-reference.md) for exact signatures and shapes, [workflows](references/workflows.md) for self-contained recipes, and [troubleshooting](references/troubleshooting.md) before changing dependencies. The bundled [output checker](scripts/check_model_output.py) validates the most common callable contracts without downloading data or importing an optional backend. ## Common callable contract Validate the callable independently before constructing an explainer. For classification, `predict_proba(X)` must preserve the batch axis and return `(n_rows, n_classes)`; class names must have exactly `n_classes` entries. Do not pass integer labels, a one-dimensional probability vector, or a single class column to a LIME classification callable without adapting it. For a single target output, use a callable such as `lambda X: model.predict_proba(X)[:, target_class]` and validate the resulting `(n_rows,)` scores for SHAP/GroupedCE as appropriate. For NN contrastive, the model callable must return integer-like class labels, not probabilities. For a single row, retain a two-dimensional input when the model expects a batch (`X[[i]]`, not `X[i]`). Text classifier callables receive a list of strings. Image classifier callables receive a batch/list of images. Keep feature order, sparse representation, preprocessing, feature names, and class order identical between the model and the explainer. ## Validate and report 1. Record input type/shape, feature names or token/image convention, model callable, class order, background/reference data, random seed, and optional dependency status. 2. Run a tiny prediction probe, then construct the chosen wrapper and explain one deliberately selected instance. 3. Check the returned structure rather than only printing it: LIME `Explanation.as_list(label=...)` or `as_map()`, SHAP value dimensions and class axis, GroupedCE grid lengths, or contrastive neighbor/distance alignment. 4. If explaining a classifier, compare the selected output class with the model's prediction. Use `faithfulness_metric` and `monotonicity_metric` only with aligned one-row feature arrays and a model exposing `predict_proba`; see the metric caveats in the references. 5. Report approximation, sampling, background-data, segmentation, and dependency limits. A plot is a presentation of an explanation, not proof of faithfulness. ## Boundaries and routes - CEM, recourse, certification, GLANCE, or OT matching: route to [counterfactual-and-certification](../counterfactual-and-certification/SKILL.md). - ProtoDash, rule induction, IMD, or TED: route to [interpretable-models](../interpretable-models/SKILL.md). - TSICE, TSLime, or TSSaliency: route to [time-series](../time-series/SKILL.md). - Dataset constructors, downloads, or dataset lifecycle: route to [datasets-and-metrics](../datasets-and-metrics/SKILL.md). Local explanation metrics themselves are covered here because their arguments must align with the selected explanation. This route does not promise that every optional backend is installable on a modern Python environment. LIME is an independent optional extra; SHAP and GroupedCE require SHAP; NN contrastive fitting requires TensorFlow. The historical package metadata also names incompatible legacy TensorFlow/Keras stacks for some SHAP/neural paths. If an import or backend probe fails, retain that failure in the report and follow the recovery matrix rather than silently substituting a different method.