Skip to main content
KaireonAI computes exact Shapley values for every tree-based and neural-collaborative-filtering model:
  • gradient_boosted — TreeSHAP (Lundberg, Erion, Lee 2018, Algorithm 2, path-dependent variant). Deterministic, O(T·L·D²).
  • neural_cf — KernelSHAP (Lundberg, Lee 2017). Exact over the 2·embDim feature set when ≤ 12 features, deterministically sampled otherwise.
The additivity identity holds in both:

​
When SHAP fires

Enable in Settings → AI Configuration or via the /api/v1/ai/explanations-settings endpoint:

​
On-demand SHAP: POST /decisions/:id/shap

For audit workflows where raw attributes live outside the trace (PII minimization), supply them in the request body:
additivityResidual reports |rawMargin − baseline − Σ shapValues| on every call. Non-zero residual indicates a malformed model and should be treated as a warning.

​
Performance

The TreeSHAP implementation is in-place buffered: each recursion writes into its own non-overlapping window of a pre-allocated structure-of-arrays buffer (Float64Array + Int32Array), and sibling subtrees share scratch space because they execute serially. There is no per-node object allocation along the hot path. Measured on synthetic LightGBM-shaped ensembles (best of 3, locally): These figures are recorded in the tree-shap.ts module header as the before/after of the in-place-buffer optimization (per-node object copy → structure-of-arrays); the table above shows the “after” column.

​
Persisted SHAP (hot-path path)

When opted in, DecisionTrace.scoringResults[i] carries:
The Narrative API automatically includes SHAP in the LLM prompt when present, and the in-app Explain dialog renders a signed bar chart of the top 8 contributions in the Regulator tab.

​
Probability-space approximation

SHAP values are in raw-margin (logit) space — the only space where the additivity identity holds. For probability-space effect size:
Monotone with shap_i but not additive in probability space. UI surfaces both: raw φ for compliance, sigmoid-mapped delta for human-readable display.

​
Neural CF SHAP (KernelSHAP)

For neural_cf models, features are the 2·embDim user+item embedding coordinates:
  • user.emb_0, user.emb_1, …, user.emb_{D−1}
  • item.emb_0, item.emb_1, …, item.emb_{D−1}
Baseline = zero embeddings (uninformative prior). The exact solver runs when 2·embDim ≤ 12 (2^12 = 4096 coalitions); sampled KernelSHAP with 512 default samples runs above that threshold. The PRNG seed is fixed (default 1, Mulberry32), so the same (user, item) pair always yields the same attribution — sampling is deterministic, though the seed itself is not echoed back in the response.

​
Compute SHAP from the Decision UI

neural_cf decisions do not persist SHAP onto the trace (PII minimization — raw user attributes are not retained), so the studio Explain this decision dialog can compute KernelSHAP on demand. When the dialog detects modelType === "neural_cf" and the trace has no shapValues, the SHAP sub-tab swaps the bar chart for a small developer panel that takes the model id (auto-prefilled from the trace’s scoringResults[i].modelId when present) and the attributes JSON used at scoring time. Clicking Run posts to /api/v1/decisions/:id/shap and renders the returned values in the same bar chart, labelled “KernelSHAP contributions (sampled)” with the additivity residual shown alongside. Gradient-boosted decisions skip the panel because TreeSHAP values are already on the trace whenever tenantSettings.aiAnalyzerSettings.llmExplanationsEnabled = true.
See also: LLM Explanations | Fairness + Drift | Decision Traces API