Promote v2.5 augmented + calibrated production checkpoint

Canonical v2.5 with verified NLTK synonym augmentation (780 essays), isotonic calibration, and essay-only inference format. Supersedes no-aug ablation commit.

README.md

@@ -1,18 +1,67 @@
 ---
 license: mit
-tags: [ielts, automated-essay-scoring, deberta-v3, evalguide, ablation]
+library_name: keras-nlp
+tags:
+  - ielts
+  - automated-essay-scoring
+  - deberta-v3
+  - ordinal-regression
+  - evalguide
 ---
 
-# EvalGuide IELTS AES v2.5 — no-aug ablation (superseded)
+# EvalGuide IELTS AES v2.5
 
-This commit preserves the first v2.5 training run where synonym augmentation was **disabled** (NLTK WordNet not loaded).
+DeBERTa-v3-base ordinal regression model for IELTS Writing Task 2 scoring across four criteria:
 
-**Superseded by the augmented + calibrated production checkpoint in the next commit.**
+- Task Response
+- Coherence and Cohesion
+- Lexical Resource
+- Grammatical Range and Accuracy
+
+## Production checkpoint (current)
 
 | Field | Value |
 |-------|-------|
-| Variant | No-aug ablation |
-| Gold harness raw QWK | 0.8595 |
-| Augmentation | Disabled (unintentionally) |
+| Variant | **Augmented + calibrated** |
+| Weights | `ielts_v2.5_base_en_10ep.weights.h5` |
+| Calibration | `ielts_v2.5_base_en_10ep_calibration.pkl` |
+| Backbone | `deberta_v3_base_en` |
+| Input format | Essay body only (`full_text`) — no question prefix |
+| Gold harness QWK | 0.7989 calibrated / 0.8505 raw (1,952-essay holdout) |
+
+### Why this checkpoint is served
+
+1. **Calibrated serving** — Isotonic calibration plus bias correction improves mean-score alignment (SMD −0.07 vs v2.4 +0.08) and lowers RMSE, which matters more for production UX than the higher raw QWK ablation.
+2. **Augmented training** — Synonym augmentation (10% of train essays) is part of the documented v2.5 strategy and was verified active in the final run. The no-aug ablation checkpoint is preserved in repo history (first commit).
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `ielts_v2.5_base_en_10ep.weights.h5` | Model weights (~3.5 GB) |
+| `ielts_v2.5_base_en_10ep_calibration.pkl` | Isotonic calibration layer |
+| `ielts_v2.5_base_en_10ep_config.json` | Training metadata and metrics |
+| `model_config.json` | Production serving config for EvalGuide backend |
+
+## Download
+
+```bash
+hf download koecheup/evalguide-ielts-v2.5 --local-dir backend/model
+```
+
+Place artifacts under `evalguide_client/backend/model/` alongside `model_config.json`.
+
+## Inference notes
+
+- Tokenize **essay content only**. Do not prepend `Question: …` — training and offline eval use essay-only input.
+- Apply the calibration artifact after forward pass when serving the production config.
+- Rollback to v2.4: set `IELTS_MODEL_NAME=ielts_v2.4_base_en_10ep.weights.h5`.
+
+## Training summary
+
+- Real data: 9,760 cleaned essays (`ielts_cleaned.csv`)
+- Synthetic mix: 15% from 284 cleaned Task 2 essays (`koecheup/ielts-synthetic`)
+- Augmentation: 10% synonym replacement (780 train essays)
+- Epochs: 10, batch size 8, variance target 2.0 → 2.7
 
-See repo HEAD for the production model card.
+See `docs/backend/v2.5_upgrade_report.md` in the EvalGuide repo for full evaluation tables.

ielts_v2.5_base_en_10ep.weights.h5

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:3b224be1ff02811af7c7b67d8ab750a0c43506f3060f3b4a081060bd86e85c9e
+oid sha256:e8d34ac1ff8e71b976a26251dabf8670dd1d028c4607317a1bf5ce54ff016a0d
 size 3696208736

ielts_v2.5_base_en_10ep_calibration.pkl

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:f28235d93b1e494db459f98f1f4f194669ef0ad4d5b4afb9c4a339a0b445cc8c
-size 1750
+oid sha256:d8ea0c41fc9f2af98880a467df126c18c4e3b34eacf7c4ba0aa4023e9db03d29
+size 1718

ielts_v2.5_base_en_10ep_config.json

@@ -23,27 +23,27 @@
     "bias_correction_enabled": true
   },
   "bias_correction_offsets": [
-    -4.853433987432378e-17,
-    1.553098875978361e-16,
-    1.9413735949729513e-17,
-    8.736181177378281e-17
+    9.464196275493137e-17,
+    -1.116289817109447e-16,
+    1.6501675557270087e-16,
+    -1.5045645361040372e-16
   ],
   "final_metrics": {
-    "train_loss": 0.26780974864959717,
-    "val_loss": 0.41971996426582336,
-    "binary_acc": 0.12838737666606903,
-    "mae": 2.637578248977661,
+    "train_loss": 0.26518937945365906,
+    "val_loss": 0.42846453189849854,
+    "binary_acc": 0.1284601092338562,
+    "mae": 2.6349937915802,
     "val_binary_acc": 0.0,
-    "val_mae": 2.3622758388519287,
-    "val_qwk": 0.5819463133811951,
-    "val_qwk_Task_Response": 0.5876268148422241,
-    "pred_variance_Task_Response": 6.448593750000001,
-    "val_qwk_Coherence_and_Cohesion": 0.5729712247848511,
-    "pred_variance_Coherence_and_Cohesion": 7.209999999999999,
-    "val_qwk_Lexical_Resource": 0.5792825222015381,
-    "pred_variance_Lexical_Resource": 6.469374999999999,
-    "val_qwk_Grammatical_Range_and_Accuracy": 0.5763903260231018,
-    "pred_variance_Grammatical_Range_and_Accuracy": 6.7435937500000005
+    "val_mae": 2.4425299167633057,
+    "val_qwk": 0.5943281650543213,
+    "val_qwk_Task_Response": 0.6033041477203369,
+    "pred_variance_Task_Response": 7.185,
+    "val_qwk_Coherence_and_Cohesion": 0.5927532911300659,
+    "pred_variance_Coherence_and_Cohesion": 8.375,
+    "val_qwk_Lexical_Resource": 0.5842580795288086,
+    "pred_variance_Lexical_Resource": 7.354843749999999,
+    "val_qwk_Grammatical_Range_and_Accuracy": 0.5854252576828003,
+    "pred_variance_Grammatical_Range_and_Accuracy": 7.602500000000001
   },
   "baseline_reference": {
     "v2_4_overall_qwk": 0.7501,