feat(explainability): add native XGBoost TreeSHAP - #68
Merged
Conversation
Signed-off-by: jiangxt2 <jiangxt2@vip.qq.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR adds an exact native TreeSHAP path for XGBoost
gbtreeanddartmodels when explainingmodel_output,raw, orraw_margin. The adapter uses XGBoost's contribution API without importing SHAP, enforces the XGBoost 2.1+ strict shape contract, maps the bias term tobase_value, verifies additivity against raw margins, and fails closed for unsupported boosters or malformed output shapes. Probability, log-loss, reference-data, and model-agnostic requests continue to use the existing SHAP paths.It also adds
output_selection=all|predicted, withallas the backward-compatible default. For multiclass native XGBoost explanations,predictedselects the class with the highest raw margin for each row while preserving the original output ID; binary classifiers retain their single margin output. The planner derives the XGBoost output bound from the typed Bundle manifest signature, and receipts and idempotency identity include the selection policy.Documentation, unit coverage, and the Docker Ray Jobs integration suite are updated for the native binary and multiclass paths. No new dependency is introduced.
Related issues
None.
Additional information
uv run --locked --no-sync python scripts/pr-precheck.pypassed. Its 16 non-blocking safety warnings were reviewed and correspond to existing broad-exception patterns, test-local imports, and fixed test literals.uv run pytest tests/explainabilitypassed with 81 tests../scripts/run_explainability_it.shpassed with 5 tests on the isolated Docker Ray cluster, including native XGBoost binary and multiclass predicted-output coverage.output_selection=predictedis intentionally limited to native XGBoost classification raw/model outputs. Regression, probability, log-loss, reference-data, and model-agnostic combinations fail closed.