xinxuxin/keystone-bench

Keystone Bench – A Clinical‑Decision Evidence Benchmark for Chat‑based AI Assistants

What it is

• A data set and evaluation framework that measures how well a medical chat assistant reacts when the evidence it relies on changes. Each original HealthBench conversation (a patient‑doctor dialogue) is paired with twins – edited versions that alter exactly one decisive fact (e.g., remove a pregnancy status, add a contradictory lab value, change a demographic attribute). A control version re‑words the original without changing any fact.
• For every twin the benchmark provides a decision frame (what decision is being made, which fact the decision rests on) and an evidence state that lists:
  • the acceptable actions the assistant should take,
  • actions that are forbidden,
  • the decisive question the assistant must ask or answer,
  • the fact it must not assume.
• Human clinicians write rubrics for the original conversation; the benchmark then scores whether the model’s reply respects the rubric after the fact is missing, contradicted, or altered.

Why it matters

• Current medical‑chat benchmarks only check if a model gives a correct answer for the original prompt. They ignore what the model should do when a key piece of evidence is absent or wrong – a situation that happens often in real‑world triage.
• Keystone makes that gap measurable, letting researchers quantify evidence‑sensitivity (does the model change its answer appropriately) and robustness to edits (does it keep answering when it shouldn’t).

Key components

Component	Description
Twins (7,419 total)	Four systematic edit families per source: missing_evidence, conflicting_evidence, demographic_shift, salient_distractor (negative control) plus five optional families such as alternative_evidence and alternative_evidence_hard that tweak a numeric value across a clinical threshold.
Sources	1,260 HealthBench conversations (multi‑turn, byte‑identical to the original).
Layers / splits	core, strict, primary, quick – increasingly stringent subsets; dev/test split (80/20) ensures twins and controls never cross splits.
Reference results	Pre‑computed replies from five commercial assistants (GPT‑4.1 judge) so users can compare new models without paying for API calls.
Grader / judge	A separate LLM (different vendor) that maps a model’s reply to the evidence‑state annotation, producing labels like acceptable, forbidden, escalated, etc.
CLI / Python library	Install via pip install keystone-bench. Commands such as keystone build, keystone run, keystone audit handle data construction, evaluation, and full audit reporting.
Audits & checks	SHA‑256 file hashes, 131 unit tests, shortcut‑audit, and a “degenerate‑policy” check that ensures no fixed policy can cheat the benchmark.

How to use it

1. Install the package and rebuild the benchmark locally (it pulls the open‑source HealthBench data and applies the published edits).
2. Load pairs in Python (load_pairs) or list them with keystone pairs.
3. Run your model on each original/twin/control conversation, providing a separate LLM as the judge (must be a different vendor).
4. Collect records and call summarize or inspect the generated REPORT.md for per‑family scores.
5. Audit the whole run with keystone audit – it checks that the expected effects (twin‑minus‑control differences, equivalence of controls, etc.) hold.

What the published results show

• On the quick set (40 items per family), the best‑performing model (GPT‑5.6‑terra) achieved a 0.74 success rate on missing_evidence (asking the missing question) and 0.96 on demographic_shift (adjusting advice). Negative‑control families stayed near 0.9‑0.95 unchanged, confirming the benchmark’s ability to separate true evidence‑sensitivity from trivial answer‑stability.
• On the held‑out test split, all preregistered hypotheses (perturbation families cause a measurable shift, controls show equivalence, etc.) were confirmed with strong statistical significance.

Who might find it useful

• Researchers building medical chatbots who need a rigorous, clinically‑grounded way to test how a model reacts to missing or contradictory information.
• Evaluation engineers who want a reproducible benchmark with built‑in audits, versioned data, and reference results.
• Regulators or safety teams looking for evidence that a system does not hallucinate or ignore critical gaps in patient data.

Where to start

• Read the Project page and the linked docs (DATA_CARD.md, SCHEMA.md, PROTOCOL.md) for full definitions of families and evidence states.
• Clone the repo, install the dev extras, and run the quickstart script in examples/quickstart.py.
• Use the provided reference runs (results/reference/) to validate your own judge implementation before testing new models.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.