card: JEV-compatible API, calibration, and what to do on a low score

README.md

@@ -114,6 +114,96 @@ not a calibrated probability — choose a threshold from your own review budget.
 
 Both read the same input. The curved probe is the one to use when the number matters.
 
+## API — drop-in for an existing JEV integration
+
+The endpoint takes the same request shape and returns the same response shape, so switching an
+existing integration is a URL change.
+
+```bash
+POST /v1/evaluate
+Authorization: Bearer <token>
+
+{"model": "vidraft/ztc",
+ "state": {"question": "...", "answer": "..."},
+ "questions": {"correct": {"type": "boolean",
+                           "instructions": "Is the ANSWER factually correct?"}}}
+```
+
+```json
+{"model": "vidraft/ztc-judge-9b",
+ "answers": {"correct": {
+    "probability": 0.1043,
+    "verdict": "review",
+    "score": -0.72,
+    "position": 0.268,
+
+    "band": "low",
+    "action": "hold_or_escalate",
+    "measured": {
+      "band_accuracy": 0.485,
+      "base_accuracy": 0.748,
+      "if_lowest_20pct_dropped": 0.814,
+      "escalate_gain_at_20pct_budget": 0.0134,
+      "do_not": "resample_same_model",
+      "why_not": "measured: fixes 6.7% of wrong answers, breaks 13.1% of right ones"}}},
+ "usage": {"generated_tokens": 0}}
+```
+
+`type` accepts `boolean` and `noul`. Existing clients read `answers.<key>.probability` and ignore
+the rest; the additional fields are there for clients that want to act on the score rather than
+merely record it. **0.19 s per call, zero generated tokens.**
+
+### What `probability` means
+
+The raw score is unbounded. The shipped calibration maps it to P(answer is correct), fitted
+**leave-one-domain-out** — the mapping never sees the domain it is applied to.
+
+| | Expected calibration error |
+|---|---|
+| **ZTC-Judge-27B (after calibration)** | **0.0245** |
+| JEV, as shipped | 0.0381 |
+| JEV, after the same calibration | 0.0261 |
+| Laya-Multilingual, as shipped | 0.4985 |
+| Laya-Typed-Decisions, as shipped | 0.2641 |
+
+Measured on the same 2,018 items. **ZTC and JEV are effectively tied on calibration; the difference
+of 0.0016 is not meaningful.** Figures published elsewhere for these systems were measured on other
+test sets and do not reproduce here.
+
+🔴 Calibration is uneven across domains: 0.0225 on biology & medicine, but 0.2941 on scientific
+reasoning and 0.2381 on general reasoning. Treat the probability as reliable in the first case and
+as a ranking signal only in the other two.
+
+## What to do when the score is low
+
+The score alone is not actionable, so the response carries the measured consequence of each choice.
+
+| Band | Share | **Actual accuracy of answers in this band** | Recommended |
+|---|---|---|---|
+| `low` | 20% | **48.5%** | hold, or escalate to a stronger model |
+| `mid` | 40% | 73.2% | escalate if budget allows |
+| `high` | 40% | **89.6%** | accept |
+
+**Three things that work, measured on 2,018 items:**
+
+| Action | Effect |
+|---|---|
+| **Drop the lowest-scoring 20%** | accuracy of what remains: **74.8% → 81.4%** |
+| **Escalate the lowest 20% to a stronger model** | **+1.34 pp** end-to-end |
+| **Send the lowest 20% to human review** | catches **47.2%** of all errors — 2.4× random |
+
+**One thing that does not work:**
+
+🔴 **Do not resample the same model.** Measured: re-drawing and taking a 3-way majority fixes
+**6.7%** of wrong answers while breaking **13.1%** of right ones. It is a net loss, and it is the
+first thing most pipelines try.
+
+*Escalation pays for itself through precision, not recall. Re-answering repairs about 38% of wrong
+answers and damages about 30% of right ones, so a gate is only worth its budget if it mostly calls
+answers that are actually wrong.*
+
+---
+
 ## Protocol
 
 | | |