feat(shap): add opt-in fuzzy_aggregation="interpolate" estimator (#229)

[breimanntools]

Summary

Adds an opt-in fuzzy_aggregation="interpolate" estimator to ShapModel.fit ([pro]). It weights a soft label p by exactly p — fitting the model twice (fuzzy sample at 0 → S0, at 1 → S1) and blending p·S1 + (1−p)·S0 — instead of the biased threshold sweep. The default "threshold" path is unchanged and byte-identical.

Closes #229.

Design (settled in the grill)

• Unbiased exact-p blend. The threshold sweep's effective positive-fraction is the grid's biased frac1, not p; the blend fixes that.
• n_rounds semantics (per-round seeds). A fixed int random_state derives a per-round seed random_state + i, so each round refits a genuinely different model — n_rounds is always meaningful and reproducible. With random_state=None each round draws fresh entropy (non-reproducible MC averaging). n_rounds=1 is the 2-fit fast path (the fastest fuzzy estimator). There is no fixed-seed short-circuit and no no-op warning — they're unnecessary under per-round seeds.
• One fuzzy protein at a time. Each fuzzy protein is explained independently against the fixed balanced 0/1 core, with the other fuzzy proteins excluded from its training data. A single fuzzy protein shares the full sample set, so its two blended fits cover every row (no separate baseline → exactly 2 fits); with ≥2 fuzzy proteins, non-fuzzy core rows come from one baseline core fit and each fuzzy row from its own 2-fit blend.
• Opt-in. "threshold" stays the default; promoting "interpolate" is a later-minor decision.

Changes

• Backend (_backend/shap_model/shap_model_fit.py): interpolate_fuzzy_shap_estimation + _seed_model_kwargs (per-round seeding).
• Frontend (_shap_model.py): fuzzy_aggregation param, check_str_options validation, routing, extended numpydoc Notes.
• Tests (test_sm_fit.py): 9 new tests — exact-p golden (atol=1e-10), 2-fit-count spy (n_rounds=1→2, n_rounds=10→20), reproducibility + rounds-differ, MC-variance-shrinks-with-n_rounds, multi-fuzzy fit count, threshold no-regression, invalid-value negative, inert-without-fuzzy.
• Docs: example notebook cell (re-executed with outputs), release-notes entry, CONTEXT.md glossary term.

Acceptance criteria — verified locally

• ✅ Exact-p blend equals p·S1 + (1−p)·S0 (max abs diff 0.0).
• ✅ Exactly 2 model fits per fuzzy sample at n_rounds=1; 20 at n_rounds=10.
• ✅ Fixed random_state reproducible; n_rounds=1 vs 10 differ.
• ✅ random_state=None: variance shrinks with n_rounds.
• ✅ "threshold" default byte-identical (no-regression test).
• ✅ Full local unit suite: 5037 passed, 10 skipped. Docstring/drift/param-coverage/import-hygiene/method-spacing checkers green.

Scope / non-goals

pro only, no new deps. Default estimator unchanged. Joint multi-fuzzy 2^K interactions out of scope (each fuzzy protein is an independent single-sample problem). Distinct from #53 (uncertainty band).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.12%. Comparing base (3bd1c87) to head (c1d8684).
⚠️ Report is 25 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #269      +/-   ##
==========================================
- Coverage   96.17%   96.12%   -0.05%     
==========================================
  Files         175      175              
  Lines       16312    16442     +130     
  Branches     2787     2806      +19     
==========================================
+ Hits        15688    15805     +117     
- Misses        366      369       +3     
- Partials      258      268      +10     

Files with missing lines	Coverage Δ
...nable_ai_pro/_backend/shap_model/shap_model_fit.py	94.07% <100.00%> (+4.30%)	⬆️
aaanalysis/explainable_ai_pro/_shap_model.py	98.37% <100.00%> (+0.02%)	⬆️

... and 2 files with indirect coverage changes

Components	Coverage Δ
cpp_core	94.95% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[breimanntools]

Looks all good. Please make a regression test! How much faster are we with the new implementaion. How strong is the difference to the existing ShapModel method?