Add KOZTAM model card, weights, and figures

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+xai_boundary.png filter=lfs diff=lfs merge=lfs -text
+xai_hard.png filter=lfs diff=lfs merge=lfs -text

KOZTAM.md

@@ -0,0 +1,225 @@
+---
+language:
+- tr
+license: mit
+library_name: pytorch
+pipeline_tag: text-classification
+base_model: dbmdz/bert-base-turkish-cased
+datasets:
+- behAIvNET/KOZTAM
+tags:
+- turkish
+- education
+- special-education
+- K-8
+- reading
+- reading-difficulty
+- reading-texts
+- synthetic-dataset
+- hearing-loss
+- cochlear
+- bert
+- berturk
+- coral
+- ordinal-regression
+- xai 
+- integrated-gradients
+metrics:
+- mae
+- accuracy
+---
+
+# KOZTAM — Koklear Okuma Zorluğu Tahminleme Modeli
+
+**KOZTAM** (*Cochlear Reading-Difficulty Forecasting Model*) grades a Turkish text on an eight-level reading-difficulty scale (grades 1–8) with a frozen BERTurk encoder and a lightweight CORAL ordinal head, reaching **0.33 ordinal MAE**, **0.72 exact-grade accuracy**, and **0.96 within-one-grade accuracy** on held-out test data.
+
+## Data
+
+KOZTAM is trained on the [`behAIvNET/KOZTAM`](https://huggingface.co/datasets/behAIvNET/KOZTAM) dataset — **1,588 synthetic Turkish texts** spanning grades 1–8 in two categories (informative / narrative), generated under strict MEB-aligned readability targets. One exact-duplicate text (present under both a grade-3 and a grade-5 folder) was removed to eliminate a conflicting ordinal label, giving the final 1,588.
+
+The texts are partitioned into **1,110 training / 239 validation / 239 test** by two-stage stratified sampling over the 16 grade × category strata, so both the ordinal grade distribution and the ≈ 50/50 category balance are preserved in every split. Because the BERTurk backbone is frozen, each text's `[CLS]` embedding (768-d) is pre-computed once and cached, and only the head is trained on those cached vectors; the mean `[CLS]` norm is ≈ 25.2 and identical across the three splits, indicating no distributional shift between them.
+
+A structural property worth noting for modelling: realized text length rises from grade 1 through grade 7 but **drops at grade 8** (shorter, in both categories, than grades 5–7). Length is therefore not a monotone proxy for reading grade at the top of the scale, so the model must rely on lexical and syntactic density rather than on length.
+
+## Model
+
+```python
+import torch
+import torch.nn as nn
+from transformers import AutoTokenizer, AutoModel
+
+DEVICE     = "cuda" if torch.cuda.is_available() else "cpu"
+MODEL_NAME = "dbmdz/bert-base-turkish-cased"
+MAX_LEN    = 512
+K          = 8                     
+
+tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
+bert = AutoModel.from_pretrained(MODEL_NAME).to(DEVICE).eval()
+for p in bert.parameters():
+    p.requires_grad_(False)
+
+@torch.no_grad()
+def encode_cls(texts):
+    enc = tokenizer(texts, padding=True, truncation=True,
+                    max_length=MAX_LEN, return_tensors="pt").to(DEVICE)
+    return bert(**enc).last_hidden_state[:, 0, :]
+
+class CoralHead(nn.Module):
+    def __init__(self, in_dim, num_classes):
+        super().__init__()
+        self.fc   = nn.Linear(in_dim, 1, bias=False)
+        self.bias = nn.Parameter(torch.zeros(num_classes - 1))
+    def forward(self, x):
+        return self.fc(x) + self.bias
+
+class KOZTAMNet(nn.Module):
+    def __init__(self, in_dim=768, p=0.2):
+        super().__init__()
+        self.proj = nn.Sequential(
+            nn.Linear(in_dim, 256), nn.LayerNorm(256), nn.GELU(), nn.Dropout(p),
+            nn.Linear(256, 64))
+        self.ordinal  = CoralHead(64, K)    
+        self.category = nn.Linear(64, 1)    
+    def forward(self, x):
+        z = self.proj(x)
+        return z, self.ordinal(z), self.category(z).squeeze(-1)
+
+ckpt = torch.load("KOZTAM.pt", map_location=DEVICE)
+head = KOZTAMNet().to(DEVICE)
+head.load_state_dict(ckpt["state_dict"])
+head.eval()
+thresholds = torch.tensor(ckpt["coral_thresholds"], device=DEVICE)   
+
+CATEGORY = {0: "bilgilendirici (informative)", 1: "öyküleyici (narrative)"}
+
+@torch.no_grad()
+def predict(texts):
+    single = isinstance(texts, str)
+    cls   = encode_cls([texts] if single else list(texts))
+    z     = head.proj(cls)
+    score = head.ordinal.fc(z).squeeze(-1)                       
+    grade = (score[:, None] > thresholds[None, :]).sum(1) + 1     
+    cat   = (torch.sigmoid(head.category(z).squeeze(-1)) > 0.5).long()
+    out = [{"grade": int(g), "score": round(float(s), 4), "category": CATEGORY[int(c)]}
+           for g, s, c in zip(grade, score, cat)]
+    return out[0] if single else out
+
+print(predict("Sample text."))
+```
+
+## Performance
+
+Evaluated on the held-out **test set (239 texts)** the model never saw during training.
+
+**Headline metrics (calibrated).**
+
+| Metric | Value |
+|---|---|
+| Ordinal MAE | **0.326** |
+| Exact-grade accuracy | **0.715** |
+| ±1-grade accuracy | **0.958** |
+| Spearman ρ (predicted vs. true grade) | **0.965** |
+| Text-category accuracy | **1.000** |
+
+**Threshold calibration.** KOZTAM has two parts: the trained network, which outputs a continuous *difficulty score*, and seven **calibrated thresholds** that cut that score into discrete grades (stored in the checkpoint, applied at inference). The raw network already ranks texts near-perfectly — continuous-score Spearman ρ = **0.966** — but the default 0.5-thresholds mis-placed the cut points and collapsed predictions toward the extreme grades. Re-placing the thresholds on the validation split (coordinate descent on MAE, **no re-training**) produced the final metrics:
+
+| Metric (test) | Raw (0.5-threshold) | Calibrated |
+|---|---|---|
+| Ordinal MAE | 0.837 | 0.326 |
+| Exact accuracy | 0.423 | 0.715 |
+| ±1 accuracy | 0.782 | 0.958 |
+| Spearman ρ | 0.924 | 0.965 |
+
+On the validation split the same procedure moved MAE from 0.837 to 0.285, confirming the calibration generalizes rather than overfitting the test set.
+
+**Continuous difficulty score by grade (test).** The mean score increases monotonically across all eight grades with no inversion, which is the direct evidence that the encoder learned the reading-difficulty ordering:
+
+| Grade | Mean score ± SD |
+|---|---|
+| 1 | −6.91 ± 1.18 |
+| 2 | −2.24 ± 1.52 |
+| 3 | −0.99 ± 0.48 |
+| 4 | −0.33 ± 0.45 |
+| 5 | 0.15 ± 0.29 |
+| 6 | 0.73 ± 0.50 |
+| 7 | 1.43 ± 0.63 |
+| 8 | 4.07 ± 1.49 |
+
+**Per-grade MAE (calibrated, test).**
+
+| Grade | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
+|---|---|---|---|---|---|---|---|---|
+| MAE | 0.033 | 0.133 | 0.333 | 0.690 | 0.400 | 0.367 | 0.567 | 0.100 |
+
+The model is sharpest at the extremes (grades 1, 8) and at distinct mid-levels; its largest residual errors sit at the **3–4 and 6–7 boundaries**, where texts are genuinely close in readability. On the raw predictions the two categories were balanced (informative 0.832 / narrative 0.842) and truncated texts (>512 tokens, n = 12) were only marginally harder (1.000 vs. 0.828), so neither category nor truncation is a source of systematic error.
+
+**Confusion matrix (calibrated, test).** Rows = true grade, columns = predicted grade.
+
+| true \ pred | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
+|---|---|---|---|---|---|---|---|---|
+| **1** | 29 | 1 | 0 | 0 | 0 | 0 | 0 | 0 |
+| **2** | 3 | 26 | 1 | 0 | 0 | 0 | 0 | 0 |
+| **3** | 0 | 9 | 20 | 1 | 0 | 0 | 0 | 0 |
+| **4** | 0 | 1 | 11 | 12 | 3 | 2 | 0 | 0 |
+| **5** | 0 | 0 | 1 | 5 | 19 | 5 | 0 | 0 |
+| **6** | 0 | 0 | 0 | 2 | 4 | 22 | 1 | 1 |
+| **7** | 0 | 0 | 0 | 0 | 2 | 8 | 15 | 5 |
+| **8** | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 28 |
+
+![Training dynamics — loss and validation MAE/accuracy over epochs](training_curves.png)
+
+![Confusion matrix — test set](confusion_matrix.png)
+
+**Ablation (test).** Each loss component was removed in turn, with everything else — seed, initialization, batch order, scheduler, early stopping, and the same post-hoc threshold calibration — held identical.
+
+| Variant | Pure ρ | MAE | Exact acc | ±1 acc |
+|---|---|---|---|---|
+| Full (ordinal + triplet + category) | 0.966 | 0.326 | 0.715 | 0.958 |
+| − triplet | 0.963 | 0.402 | 0.636 | 0.962 |
+| − category | 0.964 | 0.410 | 0.636 | 0.954 |
+| Ordinal only | 0.962 | 0.410 | 0.628 | 0.962 |
+
+Removing the ordinal-aware triplet loss raises MAE by 0.075 while pure ranking ρ is essentially unchanged, showing the triplet term improves the *even spacing* of the embedding axis (its calibratability) rather than the ranking itself.
+
+## Explainability (XAI)
+
+Reading-difficulty attributions are produced with **Integrated Gradients (IG)** on an end-to-end version of the model (frozen BERTurk → continuous difficulty score), with token attributions merged back to whole words. Before attribution, the end-to-end score is verified against the cached score of the same text — they match to within **1.1 × 10⁻⁵**, confirming IG explains the exact deployed model. IG is run with `n_steps = 50`, and the convergence delta is 0.056 (negligible relative to the score magnitude), so the completeness axiom holds.
+
+Positive attribution means a word pushes the difficulty score **up** (harder); negative means it pushes **down** (easier). Three representative test cases are shown below. Because IG distributes each text's total score relative to an empty-content baseline, the absolute magnitude of the attributions scales with how far a text's score sits from that baseline — so magnitudes are comparable *within* a text, not across texts.
+
+**Case 1 — clear-easy (true grade 1, predicted 1).**
+
+| Increases difficulty | value | | Decreases difficulty | value |
+|---|---|---|---|---|
+| elmanın | +0.54 | | neşeyle | −0.27 |
+| o | +0.33 | | güzelce | −0.26 |
+| kuralımızdır | +0.27 | | denizi | −0.22 |
+| Dünyadaki | +0.24 | | yapıp | −0.20 |
+| yansıtır | +0.23 | | üç | −0.16 |
+
+![XAI word heatmap — clear-easy case](xai_easy.png)
+
+**Case 2 — clear-hard (true grade 7, predicted 7).**
+
+| Increases difficulty | value | | Decreases difficulty | value |
+|---|---|---|---|---|
+| ilerlerler | +0.26 | | kıyafetlerin | −0.06 |
+| abartıya | +0.13 | | hızlı | −0.05 |
+| ufkunu | +0.07 | | Kendi | −0.05 |
+| koruyanlar | +0.06 | | Kendi | −0.04 |
+| sadeliği | +0.06 | | | |
+
+![XAI word heatmap — clear-hard case](xai_hard.png)
+
+**Case 3 — boundary error (true grade 6, predicted 7).**
+
+| Increases difficulty | value | | Decreases difficulty | value |
+|---|---|---|---|---|
+| alışkanlıklarımızda | +0.69 | | temizliğimizi | −0.66 |
+| yaşamımızdaki | +0.60 | | ve | −0.31 |
+| cildimizin | +0.51 | | seçmesi | −0.28 |
+| kolaylaştırır | +0.23 | | temelidir | −0.28 |
+
+![XAI word heatmap — boundary-error case](xai_boundary.png)
+
+The boundary case is the most informative: the words that pushed a grade-6 text up into grade 7 are long, morphologically heavy Turkish words (*alışkanlıklarımızda*, *yaşamımızdaki*, *cildimizin*). This is direct evidence that the model reads morphological and lexical density as a difficulty signal, and that its single-grade error falls exactly on the kind of neighbouring boundary where the difficulty distinction is genuinely soft.

KOZTAM.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1a3a783353881bb5c69961e3cecd8e9c60785db6e0886958bf826a172cb79853
+size 860437

README.md

@@ -0,0 +1,225 @@
+---
+language:
+- tr
+license: mit
+library_name: pytorch
+pipeline_tag: text-classification
+base_model: dbmdz/bert-base-turkish-cased
+datasets:
+- behAIvNET/KOZTAM
+tags:
+- turkish
+- education
+- special-education
+- K-8
+- reading
+- reading-difficulty
+- reading-texts
+- synthetic-dataset
+- hearing-loss
+- cochlear
+- bert
+- berturk
+- coral
+- ordinal-regression
+- xai 
+- integrated-gradients
+metrics:
+- mae
+- accuracy
+---
+
+# KOZTAM — Koklear Okuma Zorluğu Tahminleme Modeli
+
+**KOZTAM** (*Cochlear Reading-Difficulty Forecasting Model*) grades a Turkish text on an eight-level reading-difficulty scale (grades 1–8) with a frozen BERTurk encoder and a lightweight CORAL ordinal head, reaching **0.33 ordinal MAE**, **0.72 exact-grade accuracy**, and **0.96 within-one-grade accuracy** on held-out test data.
+
+## Data
+
+KOZTAM is trained on the [`behAIvNET/KOZTAM`](https://huggingface.co/datasets/behAIvNET/KOZTAM) dataset — **1,588 synthetic Turkish texts** spanning grades 1–8 in two categories (informative / narrative), generated under strict MEB-aligned readability targets. One exact-duplicate text (present under both a grade-3 and a grade-5 folder) was removed to eliminate a conflicting ordinal label, giving the final 1,588.
+
+The texts are partitioned into **1,110 training / 239 validation / 239 test** by two-stage stratified sampling over the 16 grade × category strata, so both the ordinal grade distribution and the ≈ 50/50 category balance are preserved in every split. Because the BERTurk backbone is frozen, each text's `[CLS]` embedding (768-d) is pre-computed once and cached, and only the head is trained on those cached vectors; the mean `[CLS]` norm is ≈ 25.2 and identical across the three splits, indicating no distributional shift between them.
+
+A structural property worth noting for modelling: realized text length rises from grade 1 through grade 7 but **drops at grade 8** (shorter, in both categories, than grades 5–7). Length is therefore not a monotone proxy for reading grade at the top of the scale, so the model must rely on lexical and syntactic density rather than on length.
+
+## Model
+
+```python
+import torch
+import torch.nn as nn
+from transformers import AutoTokenizer, AutoModel
+
+DEVICE     = "cuda" if torch.cuda.is_available() else "cpu"
+MODEL_NAME = "dbmdz/bert-base-turkish-cased"
+MAX_LEN    = 512
+K          = 8                     
+
+tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
+bert = AutoModel.from_pretrained(MODEL_NAME).to(DEVICE).eval()
+for p in bert.parameters():
+    p.requires_grad_(False)
+
+@torch.no_grad()
+def encode_cls(texts):
+    enc = tokenizer(texts, padding=True, truncation=True,
+                    max_length=MAX_LEN, return_tensors="pt").to(DEVICE)
+    return bert(**enc).last_hidden_state[:, 0, :]
+
+class CoralHead(nn.Module):
+    def __init__(self, in_dim, num_classes):
+        super().__init__()
+        self.fc   = nn.Linear(in_dim, 1, bias=False)
+        self.bias = nn.Parameter(torch.zeros(num_classes - 1))
+    def forward(self, x):
+        return self.fc(x) + self.bias
+
+class KOZTAMNet(nn.Module):
+    def __init__(self, in_dim=768, p=0.2):
+        super().__init__()
+        self.proj = nn.Sequential(
+            nn.Linear(in_dim, 256), nn.LayerNorm(256), nn.GELU(), nn.Dropout(p),
+            nn.Linear(256, 64))
+        self.ordinal  = CoralHead(64, K)    
+        self.category = nn.Linear(64, 1)    
+    def forward(self, x):
+        z = self.proj(x)
+        return z, self.ordinal(z), self.category(z).squeeze(-1)
+
+ckpt = torch.load("KOZTAM.pt", map_location=DEVICE)
+head = KOZTAMNet().to(DEVICE)
+head.load_state_dict(ckpt["state_dict"])
+head.eval()
+thresholds = torch.tensor(ckpt["coral_thresholds"], device=DEVICE)   
+
+CATEGORY = {0: "bilgilendirici (informative)", 1: "öyküleyici (narrative)"}
+
+@torch.no_grad()
+def predict(texts):
+    single = isinstance(texts, str)
+    cls   = encode_cls([texts] if single else list(texts))
+    z     = head.proj(cls)
+    score = head.ordinal.fc(z).squeeze(-1)                       
+    grade = (score[:, None] > thresholds[None, :]).sum(1) + 1     
+    cat   = (torch.sigmoid(head.category(z).squeeze(-1)) > 0.5).long()
+    out = [{"grade": int(g), "score": round(float(s), 4), "category": CATEGORY[int(c)]}
+           for g, s, c in zip(grade, score, cat)]
+    return out[0] if single else out
+
+print(predict("Sample text."))
+```
+
+## Performance
+
+Evaluated on the held-out **test set (239 texts)** the model never saw during training.
+
+**Headline metrics (calibrated).**
+
+| Metric | Value |
+|---|---|
+| Ordinal MAE | **0.326** |
+| Exact-grade accuracy | **0.715** |
+| ±1-grade accuracy | **0.958** |
+| Spearman ρ (predicted vs. true grade) | **0.965** |
+| Text-category accuracy | **1.000** |
+
+**Threshold calibration.** KOZTAM has two parts: the trained network, which outputs a continuous *difficulty score*, and seven **calibrated thresholds** that cut that score into discrete grades (stored in the checkpoint, applied at inference). The raw network already ranks texts near-perfectly — continuous-score Spearman ρ = **0.966** — but the default 0.5-thresholds mis-placed the cut points and collapsed predictions toward the extreme grades. Re-placing the thresholds on the validation split (coordinate descent on MAE, **no re-training**) produced the final metrics:
+
+| Metric (test) | Raw (0.5-threshold) | Calibrated |
+|---|---|---|
+| Ordinal MAE | 0.837 | 0.326 |
+| Exact accuracy | 0.423 | 0.715 |
+| ±1 accuracy | 0.782 | 0.958 |
+| Spearman ρ | 0.924 | 0.965 |
+
+On the validation split the same procedure moved MAE from 0.837 to 0.285, confirming the calibration generalizes rather than overfitting the test set.
+
+**Continuous difficulty score by grade (test).** The mean score increases monotonically across all eight grades with no inversion, which is the direct evidence that the encoder learned the reading-difficulty ordering:
+
+| Grade | Mean score ± SD |
+|---|---|
+| 1 | −6.91 ± 1.18 |
+| 2 | −2.24 ± 1.52 |
+| 3 | −0.99 ± 0.48 |
+| 4 | −0.33 ± 0.45 |
+| 5 | 0.15 ± 0.29 |
+| 6 | 0.73 ± 0.50 |
+| 7 | 1.43 ± 0.63 |
+| 8 | 4.07 ± 1.49 |
+
+**Per-grade MAE (calibrated, test).**
+
+| Grade | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
+|---|---|---|---|---|---|---|---|---|
+| MAE | 0.033 | 0.133 | 0.333 | 0.690 | 0.400 | 0.367 | 0.567 | 0.100 |
+
+The model is sharpest at the extremes (grades 1, 8) and at distinct mid-levels; its largest residual errors sit at the **3–4 and 6–7 boundaries**, where texts are genuinely close in readability. On the raw predictions the two categories were balanced (informative 0.832 / narrative 0.842) and truncated texts (>512 tokens, n = 12) were only marginally harder (1.000 vs. 0.828), so neither category nor truncation is a source of systematic error.
+
+**Confusion matrix (calibrated, test).** Rows = true grade, columns = predicted grade.
+
+| true \ pred | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
+|---|---|---|---|---|---|---|---|---|
+| **1** | 29 | 1 | 0 | 0 | 0 | 0 | 0 | 0 |
+| **2** | 3 | 26 | 1 | 0 | 0 | 0 | 0 | 0 |
+| **3** | 0 | 9 | 20 | 1 | 0 | 0 | 0 | 0 |
+| **4** | 0 | 1 | 11 | 12 | 3 | 2 | 0 | 0 |
+| **5** | 0 | 0 | 1 | 5 | 19 | 5 | 0 | 0 |
+| **6** | 0 | 0 | 0 | 2 | 4 | 22 | 1 | 1 |
+| **7** | 0 | 0 | 0 | 0 | 2 | 8 | 15 | 5 |
+| **8** | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 28 |
+
+![Training dynamics — loss and validation MAE/accuracy over epochs](training_curves.png)
+
+![Confusion matrix — test set](confusion_matrix.png)
+
+**Ablation (test).** Each loss component was removed in turn, with everything else — seed, initialization, batch order, scheduler, early stopping, and the same post-hoc threshold calibration — held identical.
+
+| Variant | Pure ρ | MAE | Exact acc | ±1 acc |
+|---|---|---|---|---|
+| Full (ordinal + triplet + category) | 0.966 | 0.326 | 0.715 | 0.958 |
+| − triplet | 0.963 | 0.402 | 0.636 | 0.962 |
+| − category | 0.964 | 0.410 | 0.636 | 0.954 |
+| Ordinal only | 0.962 | 0.410 | 0.628 | 0.962 |
+
+Removing the ordinal-aware triplet loss raises MAE by 0.075 while pure ranking ρ is essentially unchanged, showing the triplet term improves the *even spacing* of the embedding axis (its calibratability) rather than the ranking itself.
+
+## Explainability (XAI)
+
+Reading-difficulty attributions are produced with **Integrated Gradients (IG)** on an end-to-end version of the model (frozen BERTurk → continuous difficulty score), with token attributions merged back to whole words. Before attribution, the end-to-end score is verified against the cached score of the same text — they match to within **1.1 × 10⁻⁵**, confirming IG explains the exact deployed model. IG is run with `n_steps = 50`, and the convergence delta is 0.056 (negligible relative to the score magnitude), so the completeness axiom holds.
+
+Positive attribution means a word pushes the difficulty score **up** (harder); negative means it pushes **down** (easier). Three representative test cases are shown below. Because IG distributes each text's total score relative to an empty-content baseline, the absolute magnitude of the attributions scales with how far a text's score sits from that baseline — so magnitudes are comparable *within* a text, not across texts.
+
+**Case 1 — clear-easy (true grade 1, predicted 1).**
+
+| Increases difficulty | value | | Decreases difficulty | value |
+|---|---|---|---|---|
+| elmanın | +0.54 | | neşeyle | −0.27 |
+| o | +0.33 | | güzelce | −0.26 |
+| kuralımızdır | +0.27 | | denizi | −0.22 |
+| Dünyadaki | +0.24 | | yapıp | −0.20 |
+| yansıtır | +0.23 | | üç | −0.16 |
+
+![XAI word heatmap — clear-easy case](xai_easy.png)
+
+**Case 2 — clear-hard (true grade 7, predicted 7).**
+
+| Increases difficulty | value | | Decreases difficulty | value |
+|---|---|---|---|---|
+| ilerlerler | +0.26 | | kıyafetlerin | −0.06 |
+| abartıya | +0.13 | | hızlı | −0.05 |
+| ufkunu | +0.07 | | Kendi | −0.05 |
+| koruyanlar | +0.06 | | Kendi | −0.04 |
+| sadeliği | +0.06 | | | |
+
+![XAI word heatmap — clear-hard case](xai_hard.png)
+
+**Case 3 — boundary error (true grade 6, predicted 7).**
+
+| Increases difficulty | value | | Decreases difficulty | value |
+|---|---|---|---|---|
+| alışkanlıklarımızda | +0.69 | | temizliğimizi | −0.66 |
+| yaşamımızdaki | +0.60 | | ve | −0.31 |
+| cildimizin | +0.51 | | seçmesi | −0.28 |
+| kolaylaştırır | +0.23 | | temelidir | −0.28 |
+
+![XAI word heatmap — boundary-error case](xai_boundary.png)
+
+The boundary case is the most informative: the words that pushed a grade-6 text up into grade 7 are long, morphologically heavy Turkish words (*alışkanlıklarımızda*, *yaşamımızdaki*, *cildimizin*). This is direct evidence that the model reads morphological and lexical density as a difficulty signal, and that its single-grade error falls exactly on the kind of neighbouring boundary where the difficulty distinction is genuinely soft.