stroke-copilot / pkg /src /strokecopilot /analysis /surrogate_flags.py
parsa-hke's picture
Redesign: the story (Two hours, thirty minutes), a live-run page and the record page (part 2)
98b213b verified
Raw History Blame Contribute Delete
7.56 kB
"""SHAP survey row 11 (DEC-35): a SURROGATE model of which claims the verifier flags, explained with SHAP.
This explains a small gradient-boosted model fitted to the verifier's decisions, not the verifier itself. It asks which
claim features, all known before verification, go with being flagged.
- **Claims:** every claim of the rulebook arms with predicted vision (fixtures, 150 scenarios, 20 development real
cases) for the six models, from the saved traces (rescored, metric points 1-20).
- **Features, before verification only:** model; case type; the field the claim sits in; the claim kind the verifier
routed it to; the number of declared sources and whether they include a passage, an imaging field or a note quote; the
`derived` flag; the claim's length in words and how many numbers it holds. Nothing from the verdict (subtype,
supported passages, reason) is used.
- **Target:** flagged (any sub-type 1-7).
- **Validity first:** 5-fold cross-validation grouped by case (a case's claims never straddle folds), out-of-fold AUC
with a 95% case-bootstrap interval. If the interval includes 0.5 the SHAP result is not reported, as the survey says.
- **Explained:** the model refitted on all claims, `shap.TreeExplainer`; one-hot columns summed back to their feature.
"""
import json
import re
from pathlib import Path
import numpy as np
from strokecopilot.pipeline import compare as cp
MODELS = ("claude-sonnet-5-5", "qwen3.5-27b", "gemma-3-27b", "medgemma-27b-text", "gemma-3-4b", "gemma-3-4b-tuned")
ARMS = {"fixtures_rulebook": "fixture", "scenarios_rulebook": "scenario", "real_predicted": "real case"}
NUMBER = re.compile(r"\d+(?:\.\d+)?")
CATEGORICAL = ("model", "case type", "field", "kind")
NUMERIC = ("sources", "cites a passage", "cites imaging", "cites the note", "derived", "words", "numbers")
SEED = 20261120
def cell(model, arm):
root = Path("runs/EXP-47_small_reasoner" if model.startswith("gemma-3-4b") else "runs/EXP-37_paid_runs")
return root / model / arm
def claim_rows(models=MODELS):
"""One row per claim: features, the target and the case it belongs to (case IDs stay in memory, never saved)."""
rows = []
for m in models:
for arm, kind in ARMS.items():
folder = cell(m, arm)
metrics_file = cp._metrics_file(folder)
traces_dir = folder / cp._traces_dir_for(metrics_file.name)
if not traces_dir.exists():
traces_dir = folder / "traces"
for f in sorted(traces_dir.glob("*.json")):
saved = json.loads(f.read_text())
claims = {c.get("id") or c.get("claim_id"): c for c in saved.get("claims", [])}
for t in saved["traces"]:
c = claims.get(t["claim_id"], {})
sources = c.get("declared_sources") or c.get("sources") or []
types = {s.get("type") for s in sources}
text = c.get("text") or ""
rows.append({"group": f"{arm}:{f.stem}", "model": m, "case type": kind, "field": t["field"],
"kind": t.get("kind") or "other", "sources": len(sources),
"cites a passage": int("passage" in types), "cites imaging": int("vision" in types),
"cites the note": int("note" in types), "derived": int(bool(c.get("derived"))),
"words": len(text.split()), "numbers": len(NUMBER.findall(text)),
"flagged": int(t.get("subtype") is not None)})
return rows
def design(rows):
"""(X, y, groups, column names, column -> feature)."""
cols, owner = [], {}
for f in CATEGORICAL:
for v in sorted({r[f] for r in rows}):
cols.append(f"{f}={v}")
owner[cols[-1]] = f
for f in NUMERIC:
cols.append(f)
owner[f] = f
X = np.zeros((len(rows), len(cols)))
index = {c: i for i, c in enumerate(cols)}
for i, r in enumerate(rows):
for f in CATEGORICAL:
X[i, index[f"{f}={r[f]}"]] = 1
for f in NUMERIC:
X[i, index[f]] = r[f]
y = np.array([r["flagged"] for r in rows])
groups = np.array([r["group"] for r in rows])
return X, y, groups, cols, owner
def _model():
from sklearn.ensemble import GradientBoostingClassifier
return GradientBoostingClassifier(n_estimators=200, max_depth=3, learning_rate=0.05, subsample=0.8,
random_state=SEED)
def validate(X, y, groups, n_boot=2000):
"""Out-of-fold AUC (5 folds grouped by case) with a 95% case-bootstrap interval."""
from sklearn.metrics import roc_auc_score
from sklearn.model_selection import GroupKFold
oof = np.zeros(len(y))
for train, test in GroupKFold(n_splits=5).split(X, y, groups):
oof[test] = _model().fit(X[train], y[train]).predict_proba(X[test])[:, 1]
auc = float(roc_auc_score(y, oof))
uniq = np.unique(groups)
members = {g: np.flatnonzero(groups == g) for g in uniq}
rng = np.random.default_rng(SEED)
boots = []
for _ in range(n_boot):
idx = np.concatenate([members[g] for g in rng.choice(uniq, len(uniq))])
if len(np.unique(y[idx])) == 2:
boots.append(roc_auc_score(y[idx], oof[idx]))
return {"auc": auc, "ci95": [float(np.percentile(boots, 2.5)), float(np.percentile(boots, 97.5))],
"claims": int(len(y)), "flagged": int(y.sum()), "cases": int(len(uniq))}
def explain(X, y, cols, owner):
import shap
fitted = _model().fit(X, y)
sv = np.asarray(shap.TreeExplainer(fitted).shap_values(X))
features = list(dict.fromkeys(owner.values()))
grouped = {f: np.abs(sv[:, [i for i, c in enumerate(cols) if owner[c] == f]].sum(axis=1)).mean() for f in features}
total = sum(grouped.values())
per_level = {}
for i, c in enumerate(cols):
if "=" in c:
on = X[:, i] == 1
per_level[c] = {"claims": int(on.sum()), "mean_shap_when_present": float(sv[on, i].mean()) if on.any() else None,
"flag_rate": float(y[on].mean()) if on.any() else None}
return {"share_of_attribution": {f: float(v / total) for f, v in sorted(grouped.items(), key=lambda kv: -kv[1])},
"levels": per_level, "scale": "log-odds of being flagged"}
def main(argv=None):
import argparse
ap = argparse.ArgumentParser(description="SHAP row 11: surrogate of the verifier's flags")
ap.add_argument("--out", default="runs/EXP-73_surrogate_flags")
args = ap.parse_args(argv)
out = Path(args.out)
if not (out / "config.json").exists():
raise SystemExit("write the run's config.json first (plan §11)")
rows = claim_rows()
X, y, groups, cols, owner = design(rows)
result = {"experiment": "EXP-73", "label": "SURROGATE MODEL of the verifier's flags", "validity": validate(X, y, groups)}
lo = result["validity"]["ci95"][0]
result["explained"] = explain(X, y, cols, owner) if lo > 0.5 else None
result["note"] = ("SHAP shown: the surrogate's AUC interval excludes 0.5" if lo > 0.5 else
"Not explained: the surrogate's AUC interval includes 0.5, so its SHAP values would mean nothing")
(out / "metrics.json").write_text(json.dumps(result, indent=1))
print(json.dumps({k: result[k] for k in ("validity", "note")}, indent=1))
if result["explained"]:
print(json.dumps(result["explained"]["share_of_attribution"], indent=1))
if __name__ == "__main__":
main()