Skip to content

feat(explainability): add native XGBoost TreeSHAP - #68

Merged
jiangxt2 merged 1 commit into
masterfrom
feat/xgboost-native-tree-shap
Aug 20, 2026
Merged

feat(explainability): add native XGBoost TreeSHAP#68
jiangxt2 merged 1 commit into
masterfrom
feat/xgboost-native-tree-shap

Conversation

@jiangxt2

Copy link
Copy Markdown
Owner

Description

This PR adds an exact native TreeSHAP path for XGBoost gbtree and dart models when explaining model_output, raw, or raw_margin. The adapter uses XGBoost's contribution API without importing SHAP, enforces the XGBoost 2.1+ strict shape contract, maps the bias term to base_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, with all as the backward-compatible default. For multiclass native XGBoost explanations, predicted selects 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.py passed. 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/explainability passed with 81 tests.
  • ./scripts/run_explainability_it.sh passed with 5 tests on the isolated Docker Ray cluster, including native XGBoost binary and multiclass predicted-output coverage.
  • output_selection=predicted is intentionally limited to native XGBoost classification raw/model outputs. Regression, probability, log-loss, reference-data, and model-agnostic combinations fail closed.

Signed-off-by: jiangxt2 <jiangxt2@vip.qq.com>
@jiangxt2
jiangxt2 marked this pull request as ready for review August 20, 2026 07:06
@jiangxt2
jiangxt2 merged commit bc40056 into master Aug 20, 2026
14 checks passed
@jiangxt2
jiangxt2 deleted the feat/xgboost-native-tree-shap branch August 20, 2026 07:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant