Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,4 @@ 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
+Sample/sample_paragraph.tif filter=lfs diff=lfs merge=lfs -text

DASNUS-Kurdish-ParagraphHTR/README.md

@@ -0,0 +1,80 @@
+---
+language:
+  - ckb
+license: cc-by-nc-4.0
+tags:
+  - handwritten-text-recognition
+  - paragraph-recognition
+  - ckb
+  - densenet
+  - transformer
+  - pytorch
+  - safetensors
+datasets:
+  - DASNUS
+metrics:
+  - cer
+  - wer
+pipeline_tag: image-to-text
+---
+
+# DASNUS-Kurdish: DenseNet121-Transformer Paragraph HTR
+
+## Model Description
+Kurdish handwritten paragraph recognition model fine-tuned on the external DASNUS dataset accessed through: https://data.mendeley.com/datasets/xdj9f55rkm/1. Pre-trained on 12,000 synthetic Kurdish paragraphs from DASTNUS, then fine-tuned on 1,843 reconstructed DASNUS paragraphs. Demonstrates cross-dataset transfer capability.
+
+## Architecture
+- **CNN Backbone:** DenseNet-121 (pretrained on ImageNet)
+- **Horizontal Upsample:** Yes
+- **Encoder:** 3 Transformer encoder layers
+- **Decoder:** 6 Transformer decoder layers
+- **Attention Heads:** 8
+- **Hidden Size:** 256
+- **Feed-Forward Dim:** 2048
+- **Vocabulary Size:** 116
+- **Parameters:** 22,746,927
+
+## Performance on DASNUS
+| Metric | Value |
+|--------|-------|
+| CER (greedy) | 0.0856 |
+| WER (greedy) | 0.3148 |
+
+## Input Format
+- **Image size:** 600 x 1235 pixels
+- **Preprocessing:** Aspect-ratio-preserving resize, right-aligned on white canvas (RTL)
+- **Normalization:** ImageNet mean/std
+
+## Training
+- **Pre-training:** 12,000 synthetic paragraph images with curriculum learning
+- **Fine-tuning:** Real handwritten paragraphs from DASNUS
+- **Two-stage strategy:** Encoder frozen for first 10 epochs during fine-tuning
+
+## Usage
+```python
+from safetensors.torch import load_file
+import json
+
+# Load model weights
+state_dict = load_file("model.safetensors")
+
+# Load config
+with open("config.json", "r") as f:
+    config = json.load(f)
+
+# Load vocabulary
+with open("vocab.json", "r") as f:
+    vocab = json.load(f)
+
+# Load reverse mapping
+with open("idx_to_char.json", "r") as f:
+    idx_to_char = json.load(f)
+```
+
+## Citation
+```
+[Citation to be added upon publication]
+```
+
+## License
+This model is released under CC-BY-NC-4.0 for non-commercial research purposes only.

DASNUS-Kurdish-ParagraphHTR/config.json

@@ -0,0 +1,48 @@
+{
+  "architecture": "DenseNet121-Transformer",
+  "model_type": "custom",
+  "task": "handwritten-text-recognition",
+  "language": "Kurdish (Central / Sorani)",
+  "language_code": "ckb",
+  "script": "Kurdish",
+  "dataset": "DASNUS",
+  "cnn_backbone": "densenet121",
+  "use_upsample": true,
+  "hidden_size": 256,
+  "num_encoder_layers": 3,
+  "num_decoder_layers": 6,
+  "num_attention_heads": 8,
+  "feed_forward_dim": 2048,
+  "dropout_pretrain": 0.3,
+  "dropout_finetune": 0.2,
+  "vocab_size": 116,
+  "max_sequence_length": 555,
+  "image_height": 600,
+  "image_width": 1235,
+  "total_parameters": 22746927,
+  "training": {
+    "best_epoch": 76,
+    "best_val_cer": 0.08455350686912509,
+    "best_val_loss": null,
+    "pretrain_optimizer": "AdamW",
+    "pretrain_lr": 0.0001,
+    "finetune_optimizer": "AdamW",
+    "finetune_lr": 5e-05,
+    "pretrain_scheduler": "StepLR (step=15, gamma=0.5)",
+    "finetune_scheduler": "ReduceLROnPlateau (patience=5, factor=0.5)",
+    "pretrain_batch_size": 16,
+    "finetune_batch_size": 16,
+    "pretrain_epochs": 80,
+    "finetune_epochs": 80,
+    "curriculum_learning": true,
+    "teacher_forcing_noise_pretrain": 0.15,
+    "teacher_forcing_noise_finetune": 0.05,
+    "encoder_freeze_epochs": 10,
+    "encoder_lr_multiplier": 0.1
+  },
+  "performance": {
+    "test_cer": 0.0856,
+    "test_wer": 0.3148,
+    "test_cer_with_lm": null
+  }
+}

DASNUS-Kurdish-ParagraphHTR/idx_to_char.json

@@ -0,0 +1,118 @@
+{
+  "0": "<PAD>",
+  "1": "<SOS>",
+  "2": "<EOS>",
+  "3": "\n",
+  "4": " ",
+  "5": "!",
+  "6": "\"",
+  "7": "#",
+  "8": "%",
+  "9": "&",
+  "10": "'",
+  "11": "(",
+  "12": ")",
+  "13": "*",
+  "14": "+",
+  "15": "-",
+  "16": ".",
+  "17": "/",
+  "18": "0",
+  "19": "1",
+  "20": "2",
+  "21": "4",
+  "22": ":",
+  "23": ";",
+  "24": "=",
+  "25": "@",
+  "26": "C",
+  "27": "D",
+  "28": "F",
+  "29": "H",
+  "30": "P",
+  "31": "[",
+  "32": "]",
+  "33": "_",
+  "34": "a",
+  "35": "c",
+  "36": "d",
+  "37": "e",
+  "38": "h",
+  "39": "m",
+  "40": "o",
+  "41": "p",
+  "42": "s",
+  "43": "t",
+  "44": "x",
+  "45": "{",
+  "46": "|",
+  "47": "}",
+  "48": "×",
+  "49": "÷",
+  "50": "،",
+  "51": "؛",
+  "52": "؟",
+  "53": "ء",
+  "54": "أ",
+  "55": "ؤ",
+  "56": "ئ",
+  "57": "ا",
+  "58": "ب",
+  "59": "ة",
+  "60": "ت",
+  "61": "ث",
+  "62": "ج",
+  "63": "ح",
+  "64": "خ",
+  "65": "د",
+  "66": "ذ",
+  "67": "ر",
+  "68": "ز",
+  "69": "س",
+  "70": "ش",
+  "71": "ص",
+  "72": "ط",
+  "73": "ع",
+  "74": "غ",
+  "75": "ـ",
+  "76": "ف",
+  "77": "ق",
+  "78": "ك",
+  "79": "ل",
+  "80": "م",
+  "81": "ن",
+  "82": "ه",
+  "83": "و",
+  "84": "وو",
+  "85": "ى",
+  "86": "ي",
+  "87": "٠",
+  "88": "١",
+  "89": "٢",
+  "90": "٣",
+  "91": "٤",
+  "92": "٥",
+  "93": "٦",
+  "94": "٧",
+  "95": "٨",
+  "96": "٩",
+  "97": "٪",
+  "98": "پ",
+  "99": "چ",
+  "100": "ڕ",
+  "101": "ژ",
+  "102": "ڤ",
+  "103": "ک",
+  "104": "گ",
+  "105": "ڵ",
+  "106": "ھ",
+  "107": "ۆ",
+  "108": "ی",
+  "109": "ێ",
+  "110": "۔",
+  "111": "ە",
+  "112": "‌",
+  "113": "‎",
+  "114": "‏",
+  "115": "–"
+}

DASNUS-Kurdish-ParagraphHTR/model.safetensors

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

DASNUS-Kurdish-ParagraphHTR/vocab.json

@@ -0,0 +1,118 @@
+{
+  "<PAD>": 0,
+  "<SOS>": 1,
+  "<EOS>": 2,
+  "\n": 3,
+  " ": 4,
+  "!": 5,
+  "\"": 6,
+  "#": 7,
+  "%": 8,
+  "&": 9,
+  "'": 10,
+  "(": 11,
+  ")": 12,
+  "*": 13,
+  "+": 14,
+  "-": 15,
+  ".": 16,
+  "/": 17,
+  "0": 18,
+  "1": 19,
+  "2": 20,
+  "4": 21,
+  ":": 22,
+  ";": 23,
+  "=": 24,
+  "@": 25,
+  "C": 26,
+  "D": 27,
+  "F": 28,
+  "H": 29,
+  "P": 30,
+  "[": 31,
+  "]": 32,
+  "_": 33,
+  "a": 34,
+  "c": 35,
+  "d": 36,
+  "e": 37,
+  "h": 38,
+  "m": 39,
+  "o": 40,
+  "p": 41,
+  "s": 42,
+  "t": 43,
+  "x": 44,
+  "{": 45,
+  "|": 46,
+  "}": 47,
+  "×": 48,
+  "÷": 49,
+  "،": 50,
+  "؛": 51,
+  "؟": 52,
+  "ء": 53,
+  "أ": 54,
+  "ؤ": 55,
+  "ئ": 56,
+  "ا": 57,
+  "ب": 58,
+  "ة": 59,
+  "ت": 60,
+  "ث": 61,
+  "ج": 62,
+  "ح": 63,
+  "خ": 64,
+  "د": 65,
+  "ذ": 66,
+  "ر": 67,
+  "ز": 68,
+  "س": 69,
+  "ش": 70,
+  "ص": 71,
+  "ط": 72,
+  "ع": 73,
+  "غ": 74,
+  "ـ": 75,
+  "ف": 76,
+  "ق": 77,
+  "ك": 78,
+  "ل": 79,
+  "م": 80,
+  "ن": 81,
+  "ه": 82,
+  "و": 83,
+  "وو": 84,
+  "ى": 85,
+  "ي": 86,
+  "٠": 87,
+  "١": 88,
+  "٢": 89,
+  "٣": 90,
+  "٤": 91,
+  "٥": 92,
+  "٦": 93,
+  "٧": 94,
+  "٨": 95,
+  "٩": 96,
+  "٪": 97,
+  "پ": 98,
+  "چ": 99,
+  "ڕ": 100,
+  "ژ": 101,
+  "ڤ": 102,
+  "ک": 103,
+  "گ": 104,
+  "ڵ": 105,
+  "ھ": 106,
+  "ۆ": 107,
+  "ی": 108,
+  "ێ": 109,
+  "۔": 110,
+  "ە": 111,
+  "‌": 112,
+  "‎": 113,
+  "‏": 114,
+  "–": 115
+}

DASTNUS-Kurdish-ParagraphHTR/README.md

@@ -0,0 +1,81 @@
+---
+language:
+  - ckb
+license: cc-by-nc-4.0
+tags:
+  - handwritten-text-recognition
+  - paragraph-recognition
+  - ckb
+  - densenet
+  - transformer
+  - pytorch
+  - safetensors
+datasets:
+  - DASTNUS
+metrics:
+  - cer
+  - wer
+pipeline_tag: image-to-text
+---
+
+# DASTNUS-Kurdish: DenseNet121-Transformer Paragraph HTR
+
+## Model Description
+End-to-end Kurdish handwritten paragraph recognition model. Pre-trained on 12,000 synthetic paragraph images generated from the DASTNUS dataset, then fine-tuned on 710 real unique handwritten paragraphs. Achieves CER of 0.0721 with greedy decoding and 0.0676 with 8-gram language model rescoring.
+
+## Architecture
+- **CNN Backbone:** DenseNet-121 (pretrained on ImageNet)
+- **Horizontal Upsample:** Yes
+- **Encoder:** 3 Transformer encoder layers
+- **Decoder:** 6 Transformer decoder layers
+- **Attention Heads:** 8
+- **Hidden Size:** 256
+- **Feed-Forward Dim:** 2048
+- **Vocabulary Size:** 116
+- **Parameters:** 22,746,927
+
+## Performance on DASTNUS
+| Metric | Value |
+|--------|-------|
+| CER (greedy) | 0.0721 |
+| WER (greedy) | 0.3624 |
+| CER (with 8-gram LM) | 0.0676 |
+
+## Input Format
+- **Image size:** 600 x 1235 pixels
+- **Preprocessing:** Aspect-ratio-preserving resize, right-aligned on white canvas (RTL)
+- **Normalization:** ImageNet mean/std
+
+## Training
+- **Pre-training:** 12,000 synthetic paragraph images with curriculum learning
+- **Fine-tuning:** Real handwritten paragraphs from DASTNUS
+- **Two-stage strategy:** Encoder frozen for first 10 epochs during fine-tuning
+
+## Usage
+```python
+from safetensors.torch import load_file
+import json
+
+# Load model weights
+state_dict = load_file("model.safetensors")
+
+# Load config
+with open("config.json", "r") as f:
+    config = json.load(f)
+
+# Load vocabulary
+with open("vocab.json", "r") as f:
+    vocab = json.load(f)
+
+# Load reverse mapping
+with open("idx_to_char.json", "r") as f:
+    idx_to_char = json.load(f)
+```
+
+## Citation
+```
+[Citation to be added upon publication]
+```
+
+## License
+This model is released under CC-BY-NC-4.0 for non-commercial research purposes only.

DASTNUS-Kurdish-ParagraphHTR/config.json

@@ -0,0 +1,48 @@
+{
+  "architecture": "DenseNet121-Transformer",
+  "model_type": "custom",
+  "task": "handwritten-text-recognition",
+  "language": "Kurdish (Central / Sorani)",
+  "language_code": "ckb",
+  "script": "Kurdish",
+  "dataset": "DASTNUS",
+  "cnn_backbone": "densenet121",
+  "use_upsample": true,
+  "hidden_size": 256,
+  "num_encoder_layers": 3,
+  "num_decoder_layers": 6,
+  "num_attention_heads": 8,
+  "feed_forward_dim": 2048,
+  "dropout_pretrain": 0.3,
+  "dropout_finetune": 0.2,
+  "vocab_size": 116,
+  "max_sequence_length": 555,
+  "image_height": 600,
+  "image_width": 1235,
+  "total_parameters": 22746927,
+  "training": {
+    "best_epoch": 33,
+    "best_val_cer": 0.07456984543598717,
+    "best_val_loss": null,
+    "pretrain_optimizer": "AdamW",
+    "pretrain_lr": 0.0001,
+    "finetune_optimizer": "AdamW",
+    "finetune_lr": 5e-05,
+    "pretrain_scheduler": "StepLR (step=15, gamma=0.5)",
+    "finetune_scheduler": "ReduceLROnPlateau (patience=5, factor=0.5)",
+    "pretrain_batch_size": 16,
+    "finetune_batch_size": 16,
+    "pretrain_epochs": 80,
+    "finetune_epochs": 80,
+    "curriculum_learning": true,
+    "teacher_forcing_noise_pretrain": 0.15,
+    "teacher_forcing_noise_finetune": 0.05,
+    "encoder_freeze_epochs": 10,
+    "encoder_lr_multiplier": 0.1
+  },
+  "performance": {
+    "test_cer": 0.0721,
+    "test_wer": 0.3624,
+    "test_cer_with_lm": 0.0676
+  }
+}

DASTNUS-Kurdish-ParagraphHTR/idx_to_char.json

@@ -0,0 +1,118 @@
+{
+  "0": "<PAD>",
+  "1": "<SOS>",
+  "2": "<EOS>",
+  "3": "\n",
+  "4": " ",
+  "5": "!",
+  "6": "\"",
+  "7": "#",
+  "8": "%",
+  "9": "&",
+  "10": "'",
+  "11": "(",
+  "12": ")",
+  "13": "*",
+  "14": "+",
+  "15": "-",
+  "16": ".",
+  "17": "/",
+  "18": "0",
+  "19": "1",
+  "20": "2",
+  "21": "4",
+  "22": ":",
+  "23": ";",
+  "24": "=",
+  "25": "@",
+  "26": "C",
+  "27": "D",
+  "28": "F",
+  "29": "H",
+  "30": "P",
+  "31": "[",
+  "32": "]",
+  "33": "_",
+  "34": "a",
+  "35": "c",
+  "36": "d",
+  "37": "e",
+  "38": "h",
+  "39": "m",
+  "40": "o",
+  "41": "p",
+  "42": "s",
+  "43": "t",
+  "44": "x",
+  "45": "{",
+  "46": "|",
+  "47": "}",
+  "48": "×",
+  "49": "÷",
+  "50": "،",
+  "51": "؛",
+  "52": "؟",
+  "53": "ء",
+  "54": "أ",
+  "55": "ؤ",
+  "56": "ئ",
+  "57": "ا",
+  "58": "ب",
+  "59": "ة",
+  "60": "ت",
+  "61": "ث",
+  "62": "ج",
+  "63": "ح",
+  "64": "خ",
+  "65": "د",
+  "66": "ذ",
+  "67": "ر",
+  "68": "ز",
+  "69": "س",
+  "70": "ش",
+  "71": "ص",
+  "72": "ط",
+  "73": "ع",
+  "74": "غ",
+  "75": "ـ",
+  "76": "ف",
+  "77": "ق",
+  "78": "ك",
+  "79": "ل",
+  "80": "م",
+  "81": "ن",
+  "82": "ه",
+  "83": "و",
+  "84": "وو",
+  "85": "ى",
+  "86": "ي",
+  "87": "٠",
+  "88": "١",
+  "89": "٢",
+  "90": "٣",
+  "91": "٤",
+  "92": "٥",
+  "93": "٦",
+  "94": "٧",
+  "95": "٨",
+  "96": "٩",
+  "97": "٪",
+  "98": "پ",
+  "99": "چ",
+  "100": "ڕ",
+  "101": "ژ",
+  "102": "ڤ",
+  "103": "ک",
+  "104": "گ",
+  "105": "ڵ",
+  "106": "ھ",
+  "107": "ۆ",
+  "108": "ی",
+  "109": "ێ",
+  "110": "۔",
+  "111": "ە",
+  "112": "‌",
+  "113": "‎",
+  "114": "‏",
+  "115": "–"
+}

DASTNUS-Kurdish-ParagraphHTR/model.safetensors

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

DASTNUS-Kurdish-ParagraphHTR/vocab.json

@@ -0,0 +1,118 @@
+{
+  "<PAD>": 0,
+  "<SOS>": 1,
+  "<EOS>": 2,
+  "\n": 3,
+  " ": 4,
+  "!": 5,
+  "\"": 6,
+  "#": 7,
+  "%": 8,
+  "&": 9,
+  "'": 10,
+  "(": 11,
+  ")": 12,
+  "*": 13,
+  "+": 14,
+  "-": 15,
+  ".": 16,
+  "/": 17,
+  "0": 18,
+  "1": 19,
+  "2": 20,
+  "4": 21,
+  ":": 22,
+  ";": 23,
+  "=": 24,
+  "@": 25,
+  "C": 26,
+  "D": 27,
+  "F": 28,
+  "H": 29,
+  "P": 30,
+  "[": 31,
+  "]": 32,
+  "_": 33,
+  "a": 34,
+  "c": 35,
+  "d": 36,
+  "e": 37,
+  "h": 38,
+  "m": 39,
+  "o": 40,
+  "p": 41,
+  "s": 42,
+  "t": 43,
+  "x": 44,
+  "{": 45,
+  "|": 46,
+  "}": 47,
+  "×": 48,
+  "÷": 49,
+  "،": 50,
+  "؛": 51,
+  "؟": 52,
+  "ء": 53,
+  "أ": 54,
+  "ؤ": 55,
+  "ئ": 56,
+  "ا": 57,
+  "ب": 58,
+  "ة": 59,
+  "ت": 60,
+  "ث": 61,
+  "ج": 62,
+  "ح": 63,
+  "خ": 64,
+  "د": 65,
+  "ذ": 66,
+  "ر": 67,
+  "ز": 68,
+  "س": 69,
+  "ش": 70,
+  "ص": 71,
+  "ط": 72,
+  "ع": 73,
+  "غ": 74,
+  "ـ": 75,
+  "ف": 76,
+  "ق": 77,
+  "ك": 78,
+  "ل": 79,
+  "م": 80,
+  "ن": 81,
+  "ه": 82,
+  "و": 83,
+  "وو": 84,
+  "ى": 85,
+  "ي": 86,
+  "٠": 87,
+  "١": 88,
+  "٢": 89,
+  "٣": 90,
+  "٤": 91,
+  "٥": 92,
+  "٦": 93,
+  "٧": 94,
+  "٨": 95,
+  "٩": 96,
+  "٪": 97,
+  "پ": 98,
+  "چ": 99,
+  "ڕ": 100,
+  "ژ": 101,
+  "ڤ": 102,
+  "ک": 103,
+  "گ": 104,
+  "ڵ": 105,
+  "ھ": 106,
+  "ۆ": 107,
+  "ی": 108,
+  "ێ": 109,
+  "۔": 110,
+  "ە": 111,
+  "‌": 112,
+  "‎": 113,
+  "‏": 114,
+  "–": 115
+}

KHATT-Arabic-ParagraphHTR/README.md

@@ -0,0 +1,80 @@
+---
+language:
+  - ar
+license: cc-by-nc-4.0
+tags:
+  - handwritten-text-recognition
+  - paragraph-recognition
+  - ar
+  - densenet
+  - transformer
+  - pytorch
+  - safetensors
+datasets:
+  - KHATT
+metrics:
+  - cer
+  - wer
+pipeline_tag: image-to-text
+---
+
+# KHATT-Arabic: DenseNet121-Transformer Paragraph HTR
+
+## Model Description
+Arabic handwritten paragraph recognition model evaluated on the KHATT dataset for cross-script generalisation accessed through: https://www.kaggle.com/datasets/iraqyomar/khatt-arabic-hand-written-lines/code. Pre-trained on 12,000 synthetic paragraphs combining KHATT Arabic lines with Kurdish lines from DASTNUS, then fine-tuned on 1,193 reconstructed KHATT paragraphs. Achieves CER of 0.1394, surpassing a reimplemented state-of-the-art baseline under identical conditions.
+
+## Architecture
+- **CNN Backbone:** DenseNet-121 (pretrained on ImageNet)
+- **Horizontal Upsample:** Yes
+- **Encoder:** 3 Transformer encoder layers
+- **Decoder:** 6 Transformer decoder layers
+- **Attention Heads:** 8
+- **Hidden Size:** 256
+- **Feed-Forward Dim:** 2048
+- **Vocabulary Size:** 143
+- **Parameters:** 22,760,778
+
+## Performance on KHATT
+| Metric | Value |
+|--------|-------|
+| CER (greedy) | 0.1394 |
+| WER (greedy) | 0.5075 |
+
+## Input Format
+- **Image size:** 600 x 1235 pixels
+- **Preprocessing:** Aspect-ratio-preserving resize, right-aligned on white canvas (RTL)
+- **Normalization:** ImageNet mean/std
+
+## Training
+- **Pre-training:** 12,000 synthetic paragraph images with curriculum learning
+- **Fine-tuning:** Real handwritten paragraphs from KHATT
+- **Two-stage strategy:** Encoder frozen for first 10 epochs during fine-tuning
+
+## Usage
+```python
+from safetensors.torch import load_file
+import json
+
+# Load model weights
+state_dict = load_file("model.safetensors")
+
+# Load config
+with open("config.json", "r") as f:
+    config = json.load(f)
+
+# Load vocabulary
+with open("vocab.json", "r") as f:
+    vocab = json.load(f)
+
+# Load reverse mapping
+with open("idx_to_char.json", "r") as f:
+    idx_to_char = json.load(f)
+```
+
+## Citation
+```
+[Citation to be added upon publication]
+```
+
+## License
+This model is released under CC-BY-NC-4.0 for non-commercial research purposes only.

KHATT-Arabic-ParagraphHTR/config.json

@@ -0,0 +1,48 @@
+{
+  "architecture": "DenseNet121-Transformer",
+  "model_type": "custom",
+  "task": "handwritten-text-recognition",
+  "language": "Arabic",
+  "language_code": "ar",
+  "script": "Arabic",
+  "dataset": "KHATT",
+  "cnn_backbone": "densenet121",
+  "use_upsample": true,
+  "hidden_size": 256,
+  "num_encoder_layers": 3,
+  "num_decoder_layers": 6,
+  "num_attention_heads": 8,
+  "feed_forward_dim": 2048,
+  "dropout_pretrain": 0.3,
+  "dropout_finetune": 0.2,
+  "vocab_size": 143,
+  "max_sequence_length": 555,
+  "image_height": 600,
+  "image_width": 1235,
+  "total_parameters": 22760778,
+  "training": {
+    "best_epoch": 65,
+    "best_val_cer": 0.11814673883916608,
+    "best_val_loss": null,
+    "pretrain_optimizer": "AdamW",
+    "pretrain_lr": 0.0001,
+    "finetune_optimizer": "AdamW",
+    "finetune_lr": 5e-05,
+    "pretrain_scheduler": "StepLR (step=15, gamma=0.5)",
+    "finetune_scheduler": "ReduceLROnPlateau (patience=5, factor=0.5)",
+    "pretrain_batch_size": 16,
+    "finetune_batch_size": 16,
+    "pretrain_epochs": 80,
+    "finetune_epochs": 80,
+    "curriculum_learning": true,
+    "teacher_forcing_noise_pretrain": 0.15,
+    "teacher_forcing_noise_finetune": 0.05,
+    "encoder_freeze_epochs": 10,
+    "encoder_lr_multiplier": 0.1
+  },
+  "performance": {
+    "test_cer": 0.1394,
+    "test_wer": 0.5075,
+    "test_cer_with_lm": null
+  }
+}

KHATT-Arabic-ParagraphHTR/idx_to_char.json

@@ -0,0 +1,145 @@
+{
+  "0": "<PAD>",
+  "1": "<SOS>",
+  "2": "<EOS>",
+  "3": "\n",
+  "4": " ",
+  "5": "!",
+  "6": "\"",
+  "7": "#",
+  "8": "$",
+  "9": "%",
+  "10": "&",
+  "11": "'",
+  "12": "(",
+  "13": ")",
+  "14": "*",
+  "15": "+",
+  "16": ",",
+  "17": "-",
+  "18": ".",
+  "19": "/",
+  "20": "0",
+  "21": "1",
+  "22": "2",
+  "23": "3",
+  "24": "4",
+  "25": "5",
+  "26": "6",
+  "27": "7",
+  "28": "8",
+  "29": "9",
+  "30": ":",
+  "31": ";",
+  "32": "=",
+  "33": ">",
+  "34": "?",
+  "35": "@",
+  "36": "A",
+  "37": "C",
+  "38": "D",
+  "39": "F",
+  "40": "H",
+  "41": "I",
+  "42": "M",
+  "43": "P",
+  "44": "X",
+  "45": "[",
+  "46": "\\",
+  "47": "]",
+  "48": "_",
+  "49": "a",
+  "50": "c",
+  "51": "d",
+  "52": "e",
+  "53": "h",
+  "54": "m",
+  "55": "n",
+  "56": "o",
+  "57": "p",
+  "58": "s",
+  "59": "t",
+  "60": "x",
+  "61": "}",
+  "62": " ",
+  "63": "×",
+  "64": "÷",
+  "65": "،",
+  "66": "؛",
+  "67": "؟",
+  "68": "ء",
+  "69": "آ",
+  "70": "أ",
+  "71": "ؤ",
+  "72": "إ",
+  "73": "ئ",
+  "74": "ا",
+  "75": "ب",
+  "76": "ة",
+  "77": "ت",
+  "78": "ث",
+  "79": "ج",
+  "80": "ح",
+  "81": "خ",
+  "82": "د",
+  "83": "ذ",
+  "84": "ر",
+  "85": "ز",
+  "86": "س",
+  "87": "ش",
+  "88": "ص",
+  "89": "ض",
+  "90": "ط",
+  "91": "ظ",
+  "92": "ع",
+  "93": "غ",
+  "94": "ـ",
+  "95": "ف",
+  "96": "ق",
+  "97": "ك",
+  "98": "ل",
+  "99": "م",
+  "100": "ن",
+  "101": "ه",
+  "102": "و",
+  "103": "ى",
+  "104": "ي",
+  "105": "ً",
+  "106": "ٌ",
+  "107": "ٍ",
+  "108": "َ",
+  "109": "ُ",
+  "110": "ِ",
+  "111": "ّ",
+  "112": "ْ",
+  "113": "٠",
+  "114": "١",
+  "115": "٢",
+  "116": "٣",
+  "117": "٤",
+  "118": "٥",
+  "119": "٦",
+  "120": "٧",
+  "121": "٨",
+  "122": "٩",
+  "123": "٪",
+  "124": "پ",
+  "125": "چ",
+  "126": "ڕ",
+  "127": "ژ",
+  "128": "ڤ",
+  "129": "ک",
+  "130": "گ",
+  "131": "ڵ",
+  "132": "ھ",
+  "133": "ۆ",
+  "134": "ی",
+  "135": "ێ",
+  "136": "۔",
+  "137": "ە",
+  "138": "‌",
+  "139": "‎",
+  "140": "‏",
+  "141": "–",
+  "142": "‘"
+}

KHATT-Arabic-ParagraphHTR/model.safetensors

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

KHATT-Arabic-ParagraphHTR/vocab.json

@@ -0,0 +1,145 @@
+{
+  "<PAD>": 0,
+  "<SOS>": 1,
+  "<EOS>": 2,
+  "\n": 3,
+  " ": 4,
+  "!": 5,
+  "\"": 6,
+  "#": 7,
+  "$": 8,
+  "%": 9,
+  "&": 10,
+  "'": 11,
+  "(": 12,
+  ")": 13,
+  "*": 14,
+  "+": 15,
+  ",": 16,
+  "-": 17,
+  ".": 18,
+  "/": 19,
+  "0": 20,
+  "1": 21,
+  "2": 22,
+  "3": 23,
+  "4": 24,
+  "5": 25,
+  "6": 26,
+  "7": 27,
+  "8": 28,
+  "9": 29,
+  ":": 30,
+  ";": 31,
+  "=": 32,
+  ">": 33,
+  "?": 34,
+  "@": 35,
+  "A": 36,
+  "C": 37,
+  "D": 38,
+  "F": 39,
+  "H": 40,
+  "I": 41,
+  "M": 42,
+  "P": 43,
+  "X": 44,
+  "[": 45,
+  "\\": 46,
+  "]": 47,
+  "_": 48,
+  "a": 49,
+  "c": 50,
+  "d": 51,
+  "e": 52,
+  "h": 53,
+  "m": 54,
+  "n": 55,
+  "o": 56,
+  "p": 57,
+  "s": 58,
+  "t": 59,
+  "x": 60,
+  "}": 61,
+  " ": 62,
+  "×": 63,
+  "÷": 64,
+  "،": 65,
+  "؛": 66,
+  "؟": 67,
+  "ء": 68,
+  "آ": 69,
+  "أ": 70,
+  "ؤ": 71,
+  "إ": 72,
+  "ئ": 73,
+  "ا": 74,
+  "ب": 75,
+  "ة": 76,
+  "ت": 77,
+  "ث": 78,
+  "ج": 79,
+  "ح": 80,
+  "خ": 81,
+  "د": 82,
+  "ذ": 83,
+  "ر": 84,
+  "ز": 85,
+  "س": 86,
+  "ش": 87,
+  "ص": 88,
+  "ض": 89,
+  "ط": 90,
+  "ظ": 91,
+  "ع": 92,
+  "غ": 93,
+  "ـ": 94,
+  "ف": 95,
+  "ق": 96,
+  "ك": 97,
+  "ل": 98,
+  "م": 99,
+  "ن": 100,
+  "ه": 101,
+  "و": 102,
+  "ى": 103,
+  "ي": 104,
+  "ً": 105,
+  "ٌ": 106,
+  "ٍ": 107,
+  "َ": 108,
+  "ُ": 109,
+  "ِ": 110,
+  "ّ": 111,
+  "ْ": 112,
+  "٠": 113,
+  "١": 114,
+  "٢": 115,
+  "٣": 116,
+  "٤": 117,
+  "٥": 118,
+  "٦": 119,
+  "٧": 120,
+  "٨": 121,
+  "٩": 122,
+  "٪": 123,
+  "پ": 124,
+  "چ": 125,
+  "ڕ": 126,
+  "ژ": 127,
+  "ڤ": 128,
+  "ک": 129,
+  "گ": 130,
+  "ڵ": 131,
+  "ھ": 132,
+  "ۆ": 133,
+  "ی": 134,
+  "ێ": 135,
+  "۔": 136,
+  "ە": 137,
+  "‌": 138,
+  "‎": 139,
+  "‏": 140,
+  "–": 141,
+  "‘": 142
+}

README.md

@@ -0,0 +1,249 @@
+---
+license: cc-by-nc-4.0
+language:
+  - ckb
+  - ar
+tags:
+  - handwritten-text-recognition
+  - paragraph-recognition
+  - kurdish
+  - arabic
+  - densenet
+  - transformer
+  - pytorch
+  - safetensors
+pipeline_tag: image-to-text
+---
+# ETE-KHPR: End-to-End Kurdish Handwritten Paragraph Recognition
+### A DenseNet121-Transformer Architecture with Synthetic Paragraph Generation
+
+This repository contains the source code, trained models, and vocabularies for end-to-end Kurdish handwritten paragraph recognition without explicit line segmentation, with cross-script evaluation on Arabic (KHATT) and cross-dataset transfer to an external Kurdish dataset (DASNUS).
+
+---
+
+## Repository Structure
+
+```
+KHPR/
+├── DASTNUS-Kurdish-ParagraphHTR/   # Best Kurdish paragraph model
+│   ├── model.safetensors           # Model weights
+│   ├── config.json                 # Architecture configuration
+│   ├── vocab.json                  # Character vocabulary (char → index)
+│   ├── idx_to_char.json            # Reverse vocabulary (index → char)
+│   └── README.md                   # Model card
+│
+├── DASNUS-Kurdish-ParagraphHTR/    # Model fine-tuned on external Kurdish dataset
+│   ├── model.safetensors
+│   ├── config.json
+│   ├── vocab.json
+│   ├── idx_to_char.json
+│   └── README.md
+│
+├── KHATT-Arabic-ParagraphHTR/      # Model fine-tuned on KHATT Arabic dataset
+│   ├── model.safetensors
+│   ├── config.json
+│   ├── vocab.json                  # KHATT Arabic vocabulary (143 tokens)
+│   ├── idx_to_char.json
+│   └── README.md
+│
+├── Scripts/
+│   ├── pretrain.py                 # Pre-training on synthetic paragraphs
+│   ├── finetune.py                 # Fine-tuning on real handwritten paragraphs
+│   ├── inference.py                # Single image and batch inference
+│   └── generate_paragraphs.py     # Synthetic paragraph generation
+│
+├── Sample/
+│   ├── sample_paragraph.tif        # Example Kurdish handwritten paragraph
+│   └── sample_paragraph.txt        # Corresponding ground truth
+│
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## Architecture
+
+| Component | Details |
+|-----------|---------|
+| CNN Backbone | DenseNet-121 (ImageNet pre-trained) |
+| Encoder | 3 Transformer encoder layers |
+| Decoder | 6 Transformer decoder layers |
+| Attention Heads | 8 |
+| Hidden Size | 256 |
+| Feed-Forward Dim | 2048 |
+| Positional Encoding | 2D sinusoidal (encoder) + 1D sinusoidal (decoder) |
+| Total Parameters | 22.7M |
+
+The model processes full paragraph images end-to-end and outputs the complete multi-line text, including line break positions, without any explicit line segmentation.
+
+---
+
+## Performance
+
+### Kurdish — DASTNUS Unique Handwritten Paragraphs
+
+| Decoding Strategy | CER | WER | CRR (%) | WRR (%) |
+|---|---|---|---|---|
+| Greedy | 0.0721 | 0.3624 | 92.79 | 63.76 |
+| Beam-10 | 0.0706 | 0.3580 | 92.94 | 64.20 |
+| Beam-10 + 8-gram LM (w=0.6) | 0.0676 | 0.3422 | 93.24 | 65.78 |
+| Beam-10 + RoBERTa (w=0.1) | 0.0680 | 0.3484 | 93.20 | 65.16 |
+
+### Cross-Script Evaluation — KHATT Arabic Handwritten Paragraphs
+
+| Model | CER | WER | CRR (%) |
+|---|---|---|---|
+| Proposed | 0.1394 | 0.5075 | 86.06 |
+| MSdocTr-Lite (reimplemented, same conditions) | 0.1622 | 0.5227 | 83.78 |
+
+### Cross-Dataset Transfer — DASNUS External Kurdish Dataset
+
+| Setting | Training Samples | CER | WER | CRR (%) |
+|---|---|---|---|---|
+| Zero-shot | 0 | 0.2257 | 0.6206 | 77.43 |
+| Few-shot 10% | 184 | 0.1535 | 0.4757 | 84.65 |
+| Few-shot 50% | 922 | 0.1034 | 0.3609 | 89.66 |
+| Full fine-tune | 1,843 | 0.0856 | 0.3148 | 91.44 |
+
+---
+
+## Installation
+
+```bash
+git clone https://huggingface.co/karez/KHPR
+cd KHPR
+pip install -r requirements.txt
+```
+
+---
+
+## Quick Start
+
+### Inference
+
+```bash
+# Single paragraph image (with config auto-load)
+python Scripts/inference.py \
+    --image Sample/sample_paragraph.tif \
+    --model_path DASTNUS-Kurdish-ParagraphHTR/model.safetensors \
+    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
+    --config_path DASTNUS-Kurdish-ParagraphHTR/config.json
+
+# Directory of images with timing
+python Scripts/inference.py \
+    --image_dir ./test_paragraphs \
+    --model_path DASTNUS-Kurdish-ParagraphHTR/model.safetensors \
+    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
+    --config_path DASTNUS-Kurdish-ParagraphHTR/config.json \
+    --show_timing \
+    --output_file predictions.txt
+
+# Arabic model (KHATT)
+python Scripts/inference.py \
+    --image Sample/arabic_paragraph.tif \
+    --model_path KHATT-Arabic-ParagraphHTR/model.safetensors \
+    --vocab_path KHATT-Arabic-ParagraphHTR/vocab.json \
+    --config_path KHATT-Arabic-ParagraphHTR/config.json
+```
+
+### Synthetic Paragraph Generation
+
+```bash
+# Full three-source generation (best configuration)
+python Scripts/generate_paragraphs.py \
+    --unique_train_dir ./data/UniqueLines/Training \
+    --fixed_train_dir ./data/FixedLines/Training \
+    --synthetic_train_dir ./data/SyntheticLines/Training \
+    --unique_val_dir ./data/UniqueLines/Validation \
+    --fixed_val_dir ./data/FixedLines/Validation \
+    --synthetic_val_dir ./data/SyntheticLines/Validation \
+    --output_dir ./SyntheticParagraphs_12000 \
+    --dataset_size 12000
+```
+
+### Pre-training
+
+```bash
+# Pre-train on synthetic paragraphs (Kurdish, default settings)
+python Scripts/pretrain.py \
+    --data_dir ./SyntheticParagraphs_12000 \
+    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
+    --output_dir ./output \
+    --model_name pretrained_kurdish
+
+# Pre-train without curriculum learning
+python Scripts/pretrain.py \
+    --data_dir ./SyntheticParagraphs_12000 \
+    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
+    --no_curriculum
+```
+
+### Fine-tuning
+
+```bash
+# Fine-tune on DASTNUS unique handwritten paragraphs
+python Scripts/finetune.py \
+    --data_dir ./data/UniqueHandwrittenParagraphs \
+    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
+    --pretrained_path ./output/pretrained_kurdish.pth \
+    --output_dir ./output \
+    --model_name finetuned_dastnus
+
+# Fine-tune on DASNUS external Kurdish dataset
+python Scripts/finetune.py \
+    --data_dir ./data/DASNUS-Paragraphs \
+    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
+    --pretrained_path ./output/pretrained_kurdish.pth \
+    --output_dir ./output \
+    --model_name finetuned_dasnus
+
+# Fine-tune on KHATT Arabic dataset
+python Scripts/finetune.py \
+    --data_dir ./data/KHATT-Paragraphs \
+    --vocab_path KHATT-Arabic-ParagraphHTR/vocab.json \
+    --pretrained_path ./output/pretrained_khatt.pth \
+    --output_dir ./output \
+    --model_name finetuned_khatt
+```
+---
+
+## Training Data
+
+### DASTNUS and DASNUS Models
+
+| Data Source | Training | Validation | Testing |
+|---|---|---|---|
+| Unique handwritten paragraphs | 710 | 144 | 144 |
+| Synthetic paragraphs (pre-training) | 10,200 | 1,800 | — |
+
+Synthetic paragraphs were generated from DASTNUS line sources using the `generate_paragraphs.py` script, combining unique handwritten lines, Fixed handwrwritten lines and recipe-based synthetic handwritten lines with single-writer consistency, zero duplicate text orderings, and source-level isolation between splits.
+
+### KHATT Model
+
+| Data Source | Training | Validation | Testing |
+|---|---|---|---|
+| Reconstructed KHATT paragraphs | 1,193 | 144 | 150 |
+| Synthetic paragraphs (pre-training) | 10,201 | 1,199 | — |
+
+Synthetic paragraphs for KHATT pre-training were generated by combining KHATT handwritten lines with Kurdish line sources from DASTNUS to provide richer visual diversity across handwriting styles within the same Arabic script family.
+
+---
+
+## Hardware
+
+Experiments were conducted on a workstation equipped with an Intel Core i9-14900K processor, 128 GB RAM, and an NVIDIA GeForce RTX 5090 GPU with 32 GB VRAM.
+
+---
+
+## Citation
+
+```bibtex
+[]
+```
+
+---
+
+## License
+
+This repository is released for non-commercial scientific research purposes only under the CC-BY-NC-4.0 license. The data used in this research is available upon request for non-commercial scientific research purposes only.

Sample/sample_paragraph.txt

@@ -0,0 +1,4 @@
+قالبى ئامادەكراو :. بریتییە لە كۆمەلە ڤالبێكى ئامادەكراو كە كۆمپانیاى مایكرۆسۆفت 
+ئاماد.ى كردوو. ، بر كارئاسانى بو بەكارهێنەر بەكاردێت بۆ كردارى ژمیریارى 
+ئامار و چارت هەرو.ها بۆ كۆمەڵێك كارى بازرگانى بەمەبەستی دابەزاندز 
+قالبى تر دەبێت . كۆمپیوتەرەكە بەسترابێت بەهێلى ئەنترزێتەوە . .

Scripts/finetune.py

@@ -0,0 +1,1022 @@
+"""
+Kurdish Handwritten Paragraph Recognition - Fine-tuning Script
+DenseNet121-Transformer Architecture
+
+Fine-tunes a pre-trained model on real handwritten paragraph images.
+Loads weights from pretrain.py output checkpoint.
+
+Usage:
+    python finetune.py --data_dir ./data/UniqueHandwrittenParagraphs \
+                       --vocab_path ./vocab.json \
+                       --pretrained_path ./output/pretrained_model.pth
+
+    python finetune.py --data_dir ./data/DASNUS-Paragraphs \
+                       --vocab_path ./vocab.json \
+                       --pretrained_path ./output/pretrained_model.pth \
+                       --freeze_epochs 10
+"""
+
+import os
+import glob
+import time
+import argparse
+import json
+import math
+import random
+import re
+import numpy as np
+from PIL import Image
+from datetime import datetime
+
+import torch
+import torch.nn as nn
+import torch.optim as optim
+import torch.utils.data as data
+import torchvision.transforms as transforms
+import torchvision.models as models
+from torchvision.transforms import InterpolationMode
+from torch.nn import functional as F
+from torch.amp import autocast, GradScaler
+from tqdm import tqdm
+import gc
+
+
+# ===============================
+# Argument Parser
+# ===============================
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Kurdish Handwritten Paragraph Recognition - Fine-tuning")
+
+    # Data paths
+    parser.add_argument("--data_dir", type=str, required=True,
+                        help="Root directory with Training/, Validation/, Testing/ subfolders")
+    parser.add_argument("--vocab_path", type=str, required=True,
+                        help="Path to vocabulary JSON file (vocab.json)")
+    parser.add_argument("--pretrained_path", type=str, required=True,
+                        help="Path to pre-trained model checkpoint (.pth)")
+
+    # Image dimensions
+    parser.add_argument("--img_height", type=int, default=600)
+    parser.add_argument("--img_width", type=int, default=1235)
+    parser.add_argument("--max_seq_len", type=int, default=555)
+
+    # Training hyperparameters
+    parser.add_argument("--batch_size", type=int, default=16)
+    parser.add_argument("--num_epochs", type=int, default=80)
+    parser.add_argument("--learning_rate", type=float, default=5e-5)
+    parser.add_argument("--grad_clip", type=float, default=5.0)
+    parser.add_argument("--weight_decay", type=float, default=1e-4)
+    parser.add_argument("--seed", type=int, default=42)
+
+    # Model architecture (must match pre-trained model)
+    parser.add_argument("--hidden_size", type=int, default=256)
+    parser.add_argument("--encoder_layers", type=int, default=3)
+    parser.add_argument("--decoder_layers", type=int, default=6)
+    parser.add_argument("--num_heads", type=int, default=8)
+    parser.add_argument("--ff_dim", type=int, default=2048)
+    parser.add_argument("--dropout", type=float, default=0.2)
+    parser.add_argument("--use_upsample", action="store_true", default=True,
+                        help="Enable horizontal upsampling layer (default: True)")
+    parser.add_argument("--no_upsample", action="store_true",
+                        help="Disable horizontal upsampling layer")
+
+    # Teacher forcing
+    parser.add_argument("--tf_noise_rate", type=float, default=0.05,
+                        help="Teacher forcing noise rate (default: 0.05)")
+
+    # Encoder freezing
+    parser.add_argument("--freeze_epochs", type=int, default=10,
+                        help="Number of epochs to freeze CNN encoder (default: 10)")
+    parser.add_argument("--encoder_lr_mult", type=float, default=0.1,
+                        help="Learning rate multiplier for encoder (default: 0.1)")
+
+    # LR scheduler
+    parser.add_argument("--lr_patience", type=int, default=5,
+                        help="ReduceLROnPlateau patience")
+    parser.add_argument("--lr_factor", type=float, default=0.5,
+                        help="ReduceLROnPlateau factor")
+
+    # Early stopping
+    parser.add_argument("--patience", type=int, default=15)
+
+    # Training options
+    parser.add_argument("--mixed_precision", action="store_true", default=True)
+    parser.add_argument("--no_mixed_precision", action="store_true")
+    parser.add_argument("--no_aug", action="store_true",
+                        help="Disable data augmentation")
+    parser.add_argument("--clean_text", action="store_true", default=True,
+                        help="Clean invisible Unicode characters from labels")
+    parser.add_argument("--no_clean_text", action="store_true")
+
+    # CER computation
+    parser.add_argument("--cer_every", type=int, default=5,
+                        help="Compute train CER every N epochs (0 to disable)")
+    parser.add_argument("--cer_max_samples", type=int, default=256,
+                        help="Max samples for train CER computation")
+
+    # Output
+    parser.add_argument("--output_dir", type=str, default="./output",
+                        help="Directory to save model and logs")
+    parser.add_argument("--model_name", type=str, default="finetuned_model",
+                        help="Base name for saved model file")
+
+    return parser.parse_args()
+
+
+# ===============================
+# Vocabulary Loader
+# ===============================
+
+def load_vocabulary(vocab_path):
+    """Load vocabulary from JSON file."""
+    with open(vocab_path, "r", encoding="utf-8") as f:
+        vocab_data = json.load(f)
+
+    if "vocab_list" in vocab_data:
+        char_list = vocab_data["vocab_list"]
+    elif "char_to_idx" in vocab_data:
+        mapping = vocab_data["char_to_idx"]
+        char_list = [None] * len(mapping)
+        for char, idx in mapping.items():
+            char_list[idx] = char
+    else:
+        raise ValueError("Vocabulary JSON must contain 'vocab_list' or 'char_to_idx'")
+
+    char_to_idx = {char: idx for idx, char in enumerate(char_list)}
+    idx_to_char = {idx: char for idx, char in enumerate(char_list)}
+
+    return char_list, char_to_idx, idx_to_char
+
+
+# Special token indices
+PAD_TOKEN = 0
+SOS_TOKEN = 1
+EOS_TOKEN = 2
+
+
+# ===============================
+# Text Cleaning
+# ===============================
+
+INVISIBLE_CHARS = [
+    '\u200e', '\u200f', '\u200b', '\u200d', '\ufeff', '\u00ad',
+    '\u2060', '\u2061', '\u2062', '\u2063', '\u2064',
+    '\u206a', '\u206b', '\u206c', '\u206d', '\u206e', '\u206f',
+    '\u2028', '\u2029',
+]
+
+
+def clean_text(text):
+    """Remove invisible Unicode characters that inflate CER.
+    Preserves ZWNJ (U+200C) which is used in Kurdish."""
+    for char in INVISIBLE_CHARS:
+        if char != '\u200c':  # Keep ZWNJ
+            text = text.replace(char, '')
+    text = re.sub(r' +', ' ', text)
+    lines = text.split('\n')
+    lines = [line.strip() for line in lines]
+    return '\n'.join(lines)
+
+
+# ===============================
+# Helper Functions
+# ===============================
+
+def tensor_to_text(tensor, idx_to_char):
+    """Convert a tensor of character indices to text."""
+    if isinstance(tensor, torch.Tensor):
+        tensor = tensor.cpu().tolist()
+    text = ""
+    for idx in tensor:
+        if idx == PAD_TOKEN or idx == SOS_TOKEN:
+            continue
+        if idx == EOS_TOKEN:
+            break
+        if idx in idx_to_char:
+            text += idx_to_char[idx]
+    return text
+
+
+# ===============================
+# Dataset
+# ===============================
+
+class KurdishParagraphDataset(data.Dataset):
+    """Dataset for Kurdish handwritten paragraph images."""
+
+    def __init__(self, root_dir, transform=None, max_seq_len=555,
+                 img_height=600, img_width=1235, char_to_idx=None,
+                 clean_text_enabled=True):
+        self.transform = transform
+        self.max_seq_len = max_seq_len
+        self.img_height = img_height
+        self.img_width = img_width
+        self.char_to_idx = char_to_idx
+        self.clean_text_enabled = clean_text_enabled
+
+        self.data = []
+        image_files = []
+        for ext in ["*.tif", "*.tiff", "*.png", "*.jpg", "*.jpeg"]:
+            image_files.extend(glob.glob(os.path.join(root_dir, ext)))
+            image_files.extend(glob.glob(os.path.join(root_dir, ext.upper())))
+        image_files = sorted(list(set(image_files)))
+
+        for img_path in image_files:
+            label_path = os.path.splitext(img_path)[0] + ".txt"
+            if not os.path.exists(label_path):
+                continue
+            try:
+                with open(label_path, "r", encoding="utf-8") as f:
+                    text = f.read().strip()
+            except Exception:
+                try:
+                    with open(label_path, "r", encoding="utf-8-sig") as f:
+                        text = f.read().strip()
+                except Exception:
+                    continue
+
+            if self.clean_text_enabled:
+                text = clean_text(text)
+            if len(text) > 0:
+                self.data.append((img_path, text))
+
+        print(f"  Loaded {len(self.data)} paragraph images from {root_dir}")
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, idx):
+        img_path, text = self.data[idx]
+
+        image = Image.open(img_path).convert("RGB")
+        orig_width, orig_height = image.size
+
+        scale = min(self.img_width / orig_width, self.img_height / orig_height)
+        new_width = int(orig_width * scale)
+        new_height = int(orig_height * scale)
+        image = image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+
+        canvas = Image.new('RGB', (self.img_width, self.img_height), (255, 255, 255))
+        x_offset = self.img_width - new_width  # Right-align for RTL
+        canvas.paste(image, (x_offset, 0))
+
+        if self.transform:
+            canvas = self.transform(canvas)
+
+        indices = ([SOS_TOKEN] +
+                   [self.char_to_idx.get(c, self.char_to_idx.get(" ", 0)) for c in text] +
+                   [EOS_TOKEN])
+        if len(indices) > self.max_seq_len:
+            indices = indices[:self.max_seq_len - 1] + [EOS_TOKEN]
+
+        target = torch.LongTensor(indices)
+        return canvas, target, len(indices), text
+
+
+def collate_fn(batch):
+    """Collate function with padding for variable-length targets."""
+    batch.sort(key=lambda x: x[2], reverse=True)
+    images, targets, lengths, texts = zip(*batch)
+
+    images = torch.stack(images, 0)
+    max_length = max(lengths)
+
+    padded = torch.ones(len(targets), max_length).long() * PAD_TOKEN
+    for i, target in enumerate(targets):
+        padded[i, :lengths[i]] = target[:lengths[i]]
+
+    return images, padded, torch.LongTensor(lengths), texts
+
+
+# ===============================
+# Augmentation
+# ===============================
+
+def build_train_transform():
+    """Standard augmentation for fine-tuning."""
+    class FinetuneTransform:
+        def __call__(self, img):
+            if random.random() < 0.5:
+                img = transforms.ColorJitter(
+                    brightness=0.15, contrast=0.15,
+                    saturation=0.05, hue=0.01)(img)
+
+            if random.random() < 0.4:
+                img = transforms.RandomAffine(
+                    degrees=2, translate=(0.02, 0.02),
+                    scale=(0.97, 1.03), shear=(-2, 2),
+                    interpolation=InterpolationMode.BILINEAR, fill=255)(img)
+
+            if random.random() < 0.15:
+                img = transforms.GaussianBlur(
+                    kernel_size=3, sigma=(0.1, 0.5))(img)
+
+            img = transforms.ToTensor()(img)
+
+            if random.random() < 0.2:
+                noise = torch.randn_like(img) * 0.01
+                img = torch.clamp(img + noise, 0.0, 1.0)
+
+            img = transforms.Normalize(
+                (0.485, 0.456, 0.406), (0.229, 0.224, 0.225))(img)
+            return img
+
+    return FinetuneTransform()
+
+
+def build_eval_transform():
+    """Evaluation transform (normalisation only)."""
+    return transforms.Compose([
+        transforms.ToTensor(),
+        transforms.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225))
+    ])
+
+
+# ===============================
+# Positional Encodings
+# ===============================
+
+class PositionalEncoding2D(nn.Module):
+    """2D sinusoidal positional encoding for visual feature maps."""
+
+    def __init__(self, d_model, max_h=100, max_w=300):
+        super().__init__()
+        pe = torch.zeros(max_h, max_w, d_model)
+        d_half = d_model // 2
+
+        pos_h = torch.arange(0, max_h, dtype=torch.float).unsqueeze(1)
+        div_h = torch.exp(torch.arange(0, d_half, 2).float() * (-math.log(10000.0) / d_half))
+        pe_h = torch.zeros(max_h, d_half)
+        pe_h[:, 0::2] = torch.sin(pos_h * div_h)
+        pe_h[:, 1::2] = torch.cos(pos_h * div_h)
+
+        pos_w = torch.arange(0, max_w, dtype=torch.float).unsqueeze(1)
+        div_w = torch.exp(torch.arange(0, d_half, 2).float() * (-math.log(10000.0) / d_half))
+        pe_w = torch.zeros(max_w, d_half)
+        pe_w[:, 0::2] = torch.sin(pos_w * div_w)
+        pe_w[:, 1::2] = torch.cos(pos_w * div_w)
+
+        for h in range(max_h):
+            for w in range(max_w):
+                pe[h, w, :d_half] = pe_h[h]
+                pe[h, w, d_half:] = pe_w[w]
+
+        self.register_buffer('pe', pe)
+
+    def forward(self, x, height, width):
+        _, seq_len, d_model = x.shape
+        pe_2d = self.pe[:height, :width, :].reshape(height * width, d_model)
+        if seq_len <= pe_2d.size(0):
+            pe_2d = pe_2d[:seq_len]
+        else:
+            pad = torch.zeros(seq_len - pe_2d.size(0), d_model, device=x.device)
+            pe_2d = torch.cat([pe_2d, pad], dim=0)
+        return x + pe_2d.unsqueeze(0)
+
+
+class PositionalEncoding1D(nn.Module):
+    """1D sinusoidal positional encoding for decoder sequences."""
+
+    def __init__(self, d_model, max_len=1000):
+        super().__init__()
+        pe = torch.zeros(max_len, d_model)
+        position = torch.arange(0, max_len, dtype=torch.float).unsqueeze(1)
+        div_term = torch.exp(torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model))
+        pe[:, 0::2] = torch.sin(position * div_term)
+        pe[:, 1::2] = torch.cos(position * div_term)
+        self.register_buffer('pe', pe.unsqueeze(0))
+
+    def forward(self, x):
+        return x + self.pe[:, :x.size(1), :]
+
+
+# ===============================
+# CNN Feature Extractor
+# ===============================
+
+class CNNFeatureExtractor(nn.Module):
+    """DenseNet-121 backbone with optional horizontal upsampling."""
+
+    def __init__(self, output_dim=256, use_upsample=True):
+        super().__init__()
+        densenet = models.densenet121(weights=models.DenseNet121_Weights.DEFAULT)
+        self.features = densenet.features
+        backbone_channels = 1024
+
+        if use_upsample:
+            self.upsample = nn.Sequential(
+                nn.ConvTranspose2d(backbone_channels, 512,
+                                   kernel_size=(1, 4), stride=(1, 2), padding=(0, 1)),
+                nn.BatchNorm2d(512),
+                nn.ReLU(inplace=True))
+            adapt_in = 512
+        else:
+            self.upsample = None
+            adapt_in = backbone_channels
+
+        self.adaptation = nn.Sequential(
+            nn.Conv2d(adapt_in, output_dim, kernel_size=1),
+            nn.BatchNorm2d(output_dim),
+            nn.ReLU(inplace=True))
+
+    def forward(self, x):
+        features = F.relu(self.features(x), inplace=True)
+        if self.upsample is not None:
+            features = self.upsample(features)
+        features = self.adaptation(features)
+        b, c, h, w = features.shape
+        return features.view(b, c, h * w).permute(0, 2, 1), h, w
+
+
+# ===============================
+# Transformer OCR Model
+# ===============================
+
+class TransformerOCRParagraphModel(nn.Module):
+    """DenseNet121-Transformer for end-to-end paragraph recognition."""
+
+    def __init__(self, vocab_size, hidden_size=256, nhead=8,
+                 num_encoder_layers=3, num_decoder_layers=6,
+                 dim_feedforward=2048, dropout=0.2,
+                 use_upsample=True, max_seq_len=555,
+                 tf_noise_rate=0.05):
+        super().__init__()
+
+        self.max_seq_len = max_seq_len
+        self.vocab_size = vocab_size
+        self.tf_noise_rate = tf_noise_rate
+
+        self.feature_extractor = CNNFeatureExtractor(
+            output_dim=hidden_size, use_upsample=use_upsample)
+
+        self.pos_encoder_2d = PositionalEncoding2D(hidden_size)
+        self.pos_decoder_1d = PositionalEncoding1D(hidden_size, max_len=max_seq_len)
+
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=hidden_size, nhead=nhead,
+            dim_feedforward=dim_feedforward, dropout=dropout,
+            batch_first=True)
+        self.transformer_encoder = nn.TransformerEncoder(
+            encoder_layer, num_layers=num_encoder_layers)
+
+        decoder_layer = nn.TransformerDecoderLayer(
+            d_model=hidden_size, nhead=nhead,
+            dim_feedforward=dim_feedforward, dropout=dropout,
+            batch_first=True)
+        self.transformer_decoder = nn.TransformerDecoder(
+            decoder_layer, num_layers=num_decoder_layers)
+
+        self.token_embedding = nn.Embedding(vocab_size, hidden_size)
+        self.output_projection = nn.Linear(hidden_size, vocab_size)
+        self.hidden_size = hidden_size
+
+        nn.init.xavier_uniform_(self.token_embedding.weight)
+        nn.init.xavier_uniform_(self.output_projection.weight)
+
+    def _generate_square_subsequent_mask(self, sz):
+        mask = (torch.triu(torch.ones(sz, sz)) == 1).transpose(0, 1)
+        return mask.float().masked_fill(mask == 0, float('-inf')).masked_fill(mask == 1, 0.0)
+
+    def _add_teacher_forcing_noise(self, tgt_input):
+        if self.tf_noise_rate <= 0 or not self.training:
+            return tgt_input
+        noise_mask = (torch.rand_like(tgt_input.float()) < self.tf_noise_rate)
+        noise_mask = noise_mask & (tgt_input != PAD_TOKEN) & (tgt_input != SOS_TOKEN)
+        random_tokens = torch.randint(3, self.vocab_size, tgt_input.shape, device=tgt_input.device)
+        return torch.where(noise_mask, random_tokens, tgt_input)
+
+    def forward(self, src, tgt, tgt_key_padding_mask=None):
+        memory, feat_h, feat_w = self.feature_extractor(src)
+        memory = self.pos_encoder_2d(memory, feat_h, feat_w)
+        memory = self.transformer_encoder(memory)
+
+        tgt_input = self._add_teacher_forcing_noise(tgt[:, :-1])
+        tgt_embedded = self.pos_decoder_1d(self.token_embedding(tgt_input))
+
+        tgt_mask = self._generate_square_subsequent_mask(tgt_embedded.size(1)).to(src.device)
+        tgt_pad_mask = tgt_key_padding_mask[:, :-1] if tgt_key_padding_mask is not None else None
+
+        output = self.transformer_decoder(
+            tgt_embedded, memory,
+            tgt_mask=tgt_mask, tgt_key_padding_mask=tgt_pad_mask)
+
+        return self.output_projection(output)
+
+    def generate_batch(self, imgs, max_length=None):
+        """Auto-regressive greedy batch generation."""
+        if max_length is None:
+            max_length = self.max_seq_len
+        self.eval()
+        batch_size = imgs.size(0)
+
+        with torch.no_grad():
+            memory, feat_h, feat_w = self.feature_extractor(imgs)
+            memory = self.pos_encoder_2d(memory, feat_h, feat_w)
+            memory = self.transformer_encoder(memory)
+
+            ys = torch.ones(batch_size, 1).fill_(SOS_TOKEN).long().to(imgs.device)
+            finished = torch.zeros(batch_size, dtype=torch.bool, device=imgs.device)
+
+            for _ in range(max_length - 1):
+                tgt_embedded = self.pos_decoder_1d(self.token_embedding(ys))
+                tgt_mask = self._generate_square_subsequent_mask(ys.size(1)).to(imgs.device)
+                out = self.transformer_decoder(tgt_embedded, memory, tgt_mask=tgt_mask)
+                out = self.output_projection(out)
+
+                next_tokens = out[:, -1].argmax(dim=-1)
+                next_tokens[finished] = PAD_TOKEN
+                ys = torch.cat([ys, next_tokens.unsqueeze(1)], dim=1)
+                finished = finished | (next_tokens == EOS_TOKEN)
+                if finished.all():
+                    break
+
+        return ys
+
+    def freeze_encoder(self):
+        """Freeze CNN backbone parameters."""
+        for param in self.feature_extractor.parameters():
+            param.requires_grad = False
+        print("  Encoder (CNN) frozen")
+
+    def unfreeze_encoder(self):
+        """Unfreeze CNN backbone parameters."""
+        for param in self.feature_extractor.parameters():
+            param.requires_grad = True
+        print("  Encoder (CNN) unfrozen")
+
+
+# ===============================
+# Weight Loading
+# ===============================
+
+def load_pretrained_weights(model, pretrained_path, device):
+    """Load pre-trained weights, handling PE size mismatches gracefully."""
+    print(f"\n  Loading pre-trained model: {pretrained_path}")
+
+    if not os.path.exists(pretrained_path):
+        raise FileNotFoundError(f"Checkpoint not found: {pretrained_path}")
+
+    ckpt = torch.load(pretrained_path, map_location=device)
+
+    if 'epoch' in ckpt:
+        print(f"  Pre-trained epoch: {ckpt['epoch']}")
+    if 'val_cer' in ckpt:
+        print(f"  Pre-trained Val CER: {ckpt['val_cer']:.4f}")
+
+    state_dict = ckpt.get('model_state_dict', ckpt)
+    model_state = model.state_dict()
+
+    loaded, skipped = {}, []
+    for key, value in state_dict.items():
+        if key in model_state:
+            if value.shape == model_state[key].shape:
+                loaded[key] = value
+            else:
+                skipped.append((key, f"{value.shape} vs {model_state[key].shape}"))
+        else:
+            skipped.append((key, "not in model"))
+
+    model.load_state_dict(loaded, strict=False)
+
+    print(f"  Loaded: {len(loaded)}/{len(model_state)} parameters")
+    if skipped:
+        print(f"  Skipped: {len(skipped)} (PE buffers regenerated)")
+
+    return model
+
+
+# ===============================
+# Metrics
+# ===============================
+
+def levenshtein_distance(s1, s2):
+    if len(s1) < len(s2):
+        return levenshtein_distance(s2, s1)
+    if len(s2) == 0:
+        return len(s1)
+    prev = range(len(s2) + 1)
+    for c1 in s1:
+        curr = [prev[0] + 1]
+        for j, c2 in enumerate(s2):
+            curr.append(min(prev[j + 1] + 1, curr[j] + 1, prev[j] + (c1 != c2)))
+        prev = curr
+    return prev[-1]
+
+
+def calculate_cer(preds, targets):
+    total_dist = sum(levenshtein_distance(p, t) for p, t in zip(preds, targets))
+    total_chars = sum(len(t) for t in targets)
+    return total_dist / max(1, total_chars)
+
+
+def calculate_wer(preds, targets):
+    total_dist = sum(levenshtein_distance(p.split(), t.split()) for p, t in zip(preds, targets))
+    total_words = sum(len(t.split()) for t in targets)
+    return total_dist / max(1, total_words)
+
+
+def calculate_line_accuracy(preds, targets):
+    total, correct = 0, 0
+    for pred, true in zip(preds, targets):
+        pred_lines = pred.split('\n')
+        true_lines = true.split('\n')
+        total += len(true_lines)
+        for pl, tl in zip(pred_lines, true_lines):
+            if pl.strip() == tl.strip():
+                correct += 1
+    return correct / max(1, total)
+
+
+def evaluate_cer_batch(model, dataloader, device, idx_to_char, max_samples=None):
+    """Compute CER using batch generation."""
+    model.eval()
+    all_preds, all_targets = [], []
+    count = 0
+
+    with torch.no_grad():
+        for images, _, _, texts in dataloader:
+            images = images.to(device)
+            if max_samples and count + images.size(0) > max_samples:
+                images = images[:max_samples - count]
+                texts = texts[:max_samples - count]
+
+            batch_output = model.generate_batch(images)
+            preds = [tensor_to_text(seq, idx_to_char) for seq in batch_output]
+            all_preds.extend(preds)
+            all_targets.extend(texts)
+            count += len(preds)
+
+            if max_samples and count >= max_samples:
+                break
+
+    return calculate_cer(all_preds, all_targets)
+
+
+# ===============================
+# Comprehensive Test Evaluation
+# ===============================
+
+def comprehensive_evaluation(model, dataloader, device, idx_to_char):
+    """Full evaluation with CER, WER, line accuracy, and timing."""
+    model.eval()
+    all_preds, all_targets = [], []
+    inference_times = []
+
+    # Warmup
+    with torch.no_grad():
+        for images, _, _, _ in dataloader:
+            images = images.to(device)
+            _ = model.generate_batch(images[:min(3, images.size(0))])
+            break
+
+    if torch.cuda.is_available():
+        torch.cuda.synchronize()
+
+    with torch.no_grad():
+        for images, _, _, texts in tqdm(dataloader, desc="Evaluating"):
+            images = images.to(device)
+            batch_size = images.size(0)
+
+            if torch.cuda.is_available():
+                torch.cuda.synchronize()
+            start = time.perf_counter()
+
+            batch_output = model.generate_batch(images)
+
+            if torch.cuda.is_available():
+                torch.cuda.synchronize()
+            elapsed = time.perf_counter() - start
+
+            per_sample = elapsed / batch_size
+            inference_times.extend([per_sample] * batch_size)
+
+            preds = [tensor_to_text(seq, idx_to_char) for seq in batch_output]
+            all_preds.extend(preds)
+            all_targets.extend(texts)
+
+    cer = calculate_cer(all_preds, all_targets)
+    wer = calculate_wer(all_preds, all_targets)
+    line_acc = calculate_line_accuracy(all_preds, all_targets)
+
+    total_params = sum(p.numel() for p in model.parameters())
+
+    return {
+        'cer': cer, 'wer': wer, 'line_accuracy': line_acc,
+        'avg_inference_ms': np.mean(inference_times) * 1000,
+        'std_inference_ms': np.std(inference_times) * 1000,
+        'fps': len(inference_times) / sum(inference_times),
+        'total_params': total_params,
+        'predictions': all_preds, 'targets': all_targets,
+    }
+
+
+# ===============================
+# Early Stopping
+# ===============================
+
+class EarlyStopping:
+    def __init__(self, patience=15):
+        self.patience = patience
+        self.counter = 0
+        self.best_cer = float('inf')
+        self.early_stop = False
+
+    def __call__(self, val_cer, model, epoch, path):
+        if val_cer < self.best_cer:
+            self.best_cer = val_cer
+            self.counter = 0
+            torch.save({
+                'epoch': epoch,
+                'model_state_dict': model.state_dict(),
+                'val_cer': val_cer
+            }, path)
+            print(f"  Model saved (Val CER: {val_cer:.4f})")
+        else:
+            self.counter += 1
+            print(f"  Early stopping: {self.counter}/{self.patience}")
+            if self.counter >= self.patience:
+                self.early_stop = True
+                print("  Early stopping triggered.")
+
+
+# ===============================
+# Training Functions
+# ===============================
+
+def train_epoch(model, dataloader, optimizer, criterion, device, scaler,
+                use_mixed_precision=True, grad_clip=5.0):
+    """Train for one epoch."""
+    model.train()
+    epoch_loss = 0
+
+    for images, targets, _, _ in tqdm(dataloader, desc="Training"):
+        images, targets = images.to(device), targets.to(device)
+        tgt_pad_mask = (targets == PAD_TOKEN).to(device)
+
+        optimizer.zero_grad()
+
+        if use_mixed_precision:
+            with autocast(device_type='cuda'):
+                outputs = model(images, targets, tgt_key_padding_mask=tgt_pad_mask)
+                loss = criterion(outputs.reshape(-1, outputs.shape[-1]),
+                                 targets[:, 1:].reshape(-1))
+            scaler.scale(loss).backward()
+            scaler.unscale_(optimizer)
+            torch.nn.utils.clip_grad_norm_(model.parameters(), grad_clip)
+            scaler.step(optimizer)
+            scaler.update()
+        else:
+            outputs = model(images, targets, tgt_key_padding_mask=tgt_pad_mask)
+            loss = criterion(outputs.reshape(-1, outputs.shape[-1]),
+                             targets[:, 1:].reshape(-1))
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.parameters(), grad_clip)
+            optimizer.step()
+
+        epoch_loss += loss.item()
+
+    return epoch_loss / len(dataloader)
+
+
+def evaluate_loss(model, dataloader, criterion, device, use_mixed_precision=True):
+    """Evaluate model loss."""
+    model.eval()
+    epoch_loss = 0
+
+    with torch.no_grad():
+        for images, targets, _, _ in dataloader:
+            images, targets = images.to(device), targets.to(device)
+            tgt_pad_mask = (targets == PAD_TOKEN).to(device)
+
+            if use_mixed_precision:
+                with autocast(device_type='cuda'):
+                    outputs = model(images, targets, tgt_key_padding_mask=tgt_pad_mask)
+                    loss = criterion(outputs.reshape(-1, outputs.shape[-1]),
+                                     targets[:, 1:].reshape(-1))
+            else:
+                outputs = model(images, targets, tgt_key_padding_mask=tgt_pad_mask)
+                loss = criterion(outputs.reshape(-1, outputs.shape[-1]),
+                                 targets[:, 1:].reshape(-1))
+            epoch_loss += loss.item()
+
+    return epoch_loss / len(dataloader)
+
+
+# ===============================
+# Main
+# ===============================
+
+def main():
+    args = parse_args()
+
+    # Handle flag conflicts
+    use_upsample = args.use_upsample and not args.no_upsample
+    use_mixed_precision = args.mixed_precision and not args.no_mixed_precision
+    use_clean_text = args.clean_text and not args.no_clean_text
+
+    # Seeds
+    torch.manual_seed(args.seed)
+    random.seed(args.seed)
+    np.random.seed(args.seed)
+
+    # Device
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"Device: {device}")
+    if torch.cuda.is_available():
+        print(f"GPU: {torch.cuda.get_device_name(0)}")
+
+    # Output directory
+    os.makedirs(args.output_dir, exist_ok=True)
+
+    # Vocabulary
+    char_list, char_to_idx, idx_to_char = load_vocabulary(args.vocab_path)
+    vocab_size = len(char_list)
+    print(f"Vocabulary size: {vocab_size}")
+
+    # Transforms
+    train_transform = build_eval_transform() if args.no_aug else build_train_transform()
+    eval_transform = build_eval_transform()
+
+    # Dataset kwargs
+    ds_kwargs = dict(
+        max_seq_len=args.max_seq_len,
+        img_height=args.img_height,
+        img_width=args.img_width,
+        char_to_idx=char_to_idx,
+        clean_text_enabled=use_clean_text)
+
+    # Datasets
+    train_dir = os.path.join(args.data_dir, "Training")
+    val_dir = os.path.join(args.data_dir, "Validation")
+    test_dir = os.path.join(args.data_dir, "Testing")
+
+    train_dataset = KurdishParagraphDataset(train_dir, transform=train_transform, **ds_kwargs)
+    val_dataset = KurdishParagraphDataset(val_dir, transform=eval_transform, **ds_kwargs)
+    test_dataset = KurdishParagraphDataset(test_dir, transform=eval_transform, **ds_kwargs)
+
+    loader_kwargs = dict(num_workers=0, pin_memory=True, collate_fn=collate_fn)
+    train_loader = data.DataLoader(train_dataset, batch_size=args.batch_size, shuffle=True, **loader_kwargs)
+    val_loader = data.DataLoader(val_dataset, batch_size=args.batch_size, shuffle=False, **loader_kwargs)
+    test_loader = data.DataLoader(test_dataset, batch_size=args.batch_size, shuffle=False, **loader_kwargs)
+
+    print(f"\n  Training: {len(train_dataset)} | Validation: {len(val_dataset)} | Testing: {len(test_dataset)}")
+
+    # Model
+    print("\nInitializing model...")
+    model = TransformerOCRParagraphModel(
+        vocab_size=vocab_size,
+        hidden_size=args.hidden_size,
+        nhead=args.num_heads,
+        num_encoder_layers=args.encoder_layers,
+        num_decoder_layers=args.decoder_layers,
+        dim_feedforward=args.ff_dim,
+        dropout=args.dropout,
+        use_upsample=use_upsample,
+        max_seq_len=args.max_seq_len,
+        tf_noise_rate=args.tf_noise_rate
+    ).to(device)
+
+    # Load pre-trained weights
+    model = load_pretrained_weights(model, args.pretrained_path, device)
+
+    # Freeze encoder
+    if args.freeze_epochs > 0:
+        model.freeze_encoder()
+
+    total_params = sum(p.numel() for p in model.parameters())
+    trainable_params = sum(p.numel() for p in model.parameters() if p.requires_grad)
+    print(f"  Total parameters: {total_params:,}")
+    print(f"  Trainable parameters: {trainable_params:,}")
+
+    # Optimizer with differential learning rates
+    encoder_params = list(model.feature_extractor.parameters())
+    other_params = [p for n, p in model.named_parameters() if 'feature_extractor' not in n]
+
+    optimizer = optim.AdamW([
+        {'params': encoder_params, 'lr': args.learning_rate * args.encoder_lr_mult},
+        {'params': other_params, 'lr': args.learning_rate}
+    ], weight_decay=args.weight_decay)
+
+    scheduler = optim.lr_scheduler.ReduceLROnPlateau(
+        optimizer, mode='min', factor=args.lr_factor,
+        patience=args.lr_patience, min_lr=1e-7)
+
+    criterion = nn.CrossEntropyLoss(ignore_index=PAD_TOKEN)
+    scaler = GradScaler('cuda') if use_mixed_precision else None
+    early_stopping = EarlyStopping(patience=args.patience)
+
+    best_model_path = os.path.join(args.output_dir, f"{args.model_name}.pth")
+
+    # Log file
+    log_path = os.path.join(args.output_dir,
+                            f"{args.model_name}_LOG_{datetime.now():%Y%m%d_%H%M%S}.txt")
+    log_file = open(log_path, 'w', encoding='utf-8')
+
+    def log(msg):
+        print(msg)
+        log_file.write(msg + '\n')
+        log_file.flush()
+
+    log(f"\nFine-tuning started: {datetime.now():%Y-%m-%d %H:%M:%S}")
+    log(f"Pre-trained model: {args.pretrained_path}")
+    log(f"Config: {vars(args)}")
+
+    # Initial evaluation
+    initial_cer = evaluate_cer_batch(model, val_loader, device, idx_to_char)
+    log(f"\n  Initial Val CER (pre-trained): {initial_cer:.4f}")
+
+    # Fine-tuning loop
+    best_val_cer = float('inf')
+
+    for epoch in range(1, args.num_epochs + 1):
+        start_time = time.time()
+
+        # Unfreeze encoder after freeze period
+        if epoch == args.freeze_epochs + 1 and args.freeze_epochs > 0:
+            model.unfreeze_encoder()
+            trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
+            log(f"\n  Epoch {epoch}: Encoder unfrozen ({trainable:,} trainable params)")
+
+        # Train
+        train_loss = train_epoch(model, train_loader, optimizer, criterion,
+                                 device, scaler, use_mixed_precision, args.grad_clip)
+
+        # Train CER (periodic)
+        train_cer = None
+        if args.cer_every > 0 and epoch % args.cer_every == 0:
+            train_cer = evaluate_cer_batch(model, train_loader, device,
+                                           idx_to_char, args.cer_max_samples)
+
+        # Validation
+        val_loss = evaluate_loss(model, val_loader, criterion, device, use_mixed_precision)
+        val_cer = evaluate_cer_batch(model, val_loader, device, idx_to_char)
+
+        scheduler.step(val_cer)
+        elapsed = time.time() - start_time
+        mins, secs = divmod(elapsed, 60)
+
+        lr_enc = optimizer.param_groups[0]['lr']
+        lr_dec = optimizer.param_groups[1]['lr']
+
+        cer_str = f", Train CER: {train_cer:.4f}" if train_cer is not None else ""
+        log(f"Epoch {epoch}/{args.num_epochs} ({mins:.0f}m {secs:.0f}s) | "
+            f"Train Loss: {train_loss:.4f}{cer_str} | "
+            f"Val Loss: {val_loss:.4f} | Val CER: {val_cer:.4f} | "
+            f"LR: Enc={lr_enc:.2e}, Dec={lr_dec:.2e}")
+
+        if val_cer < best_val_cer:
+            best_val_cer = val_cer
+
+        early_stopping(val_cer, model, epoch, best_model_path)
+        if early_stopping.early_stop:
+            break
+
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+    # Final comprehensive evaluation
+    log(f"\nLoading best model for final evaluation...")
+    ckpt = torch.load(best_model_path, map_location=device)
+    model.load_state_dict(ckpt['model_state_dict'])
+    log(f"  Best epoch: {ckpt['epoch']}, Best Val CER: {ckpt['val_cer']:.4f}")
+
+    # Validation results
+    log(f"\n--- Validation Set ---")
+    val_results = comprehensive_evaluation(model, val_loader, device, idx_to_char)
+    log(f"  CER: {val_results['cer']:.4f} | WER: {val_results['wer']:.4f} | "
+        f"Line Acc: {val_results['line_accuracy']:.4f}")
+    log(f"  Inference: {val_results['avg_inference_ms']:.2f} ms | FPS: {val_results['fps']:.2f}")
+
+    # Test results
+    log(f"\n--- Test Set ---")
+    test_results = comprehensive_evaluation(model, test_loader, device, idx_to_char)
+    log(f"  CER: {test_results['cer']:.4f} ({(1-test_results['cer'])*100:.2f}% accuracy)")
+    log(f"  WER: {test_results['wer']:.4f} ({(1-test_results['wer'])*100:.2f}% accuracy)")
+    log(f"  Line Accuracy: {test_results['line_accuracy']:.4f}")
+    log(f"  Inference: {test_results['avg_inference_ms']:.2f} ± {test_results['std_inference_ms']:.2f} ms")
+    log(f"  FPS: {test_results['fps']:.2f}")
+    log(f"  Parameters: {test_results['total_params']:,}")
+
+    # Sample predictions
+    log(f"\n--- Sample Predictions ---")
+    for i in range(min(5, len(test_results['predictions']))):
+        log(f"\nSample {i + 1}:")
+        pred_preview = test_results['predictions'][i][:200]
+        true_preview = test_results['targets'][i][:200]
+        log(f"  Predicted: {pred_preview}")
+        log(f"  Actual:    {true_preview}")
+
+    log(f"\nFine-tuning complete: {datetime.now():%Y-%m-%d %H:%M:%S}")
+    log(f"Best model: {best_model_path}")
+    log(f"Improvement: {initial_cer:.4f} -> {best_val_cer:.4f} "
+        f"({(initial_cer - best_val_cer)*100:.2f}% absolute)")
+
+    log_file.close()
+    print(f"Log saved to: {log_path}")
+
+
+if __name__ == "__main__":
+    main()

Scripts/generate_paragraphs.py

@@ -0,0 +1,380 @@
+"""
+Synthetic Handwritten Paragraph Generator
+Single-Writer Consistency | Cross-Source Mixing | Zero Duplicate Orders
+
+Generates synthetic paragraph images from handwritten line sources for
+pre-training paragraph recognition models. Supports RTL scripts.
+
+Guarantees:
+  1. Single-writer consistency: all lines in each paragraph from one writer
+  2. Cross-source mixing: multi-line paragraphs use lines from 2+ sources
+  3. Zero duplicate text orderings across the entire dataset
+  4. Source-level isolation: training and validation use separate line pools
+  5. Configurable reuse caps per source to control line repetition
+
+Usage:
+    python generate_paragraphs.py \
+        --unique_train_dir ./data/UniqueLines/Training \
+        --fixed_train_dir ./data/FixedLines/Training \
+        --synthetic_train_dir ./data/SyntheticLines/Training \
+        --unique_val_dir ./data/UniqueLines/Validation \
+        --fixed_val_dir ./data/FixedLines/Validation \
+        --synthetic_val_dir ./data/SyntheticLines/Validation \
+        --output_dir ./SyntheticParagraphs_12000 \
+        --dataset_size 12000
+"""
+
+import os, glob, random, argparse, gc
+import numpy as np
+from PIL import Image
+from tqdm import tqdm
+from datetime import datetime
+from collections import defaultdict
+
+
+def parse_args():
+    p = argparse.ArgumentParser(description="Synthetic Paragraph Generator")
+    p.add_argument("--unique_train_dir", type=str, required=True)
+    p.add_argument("--fixed_train_dir", type=str, default=None)
+    p.add_argument("--synthetic_train_dir", type=str, default=None)
+    p.add_argument("--unique_val_dir", type=str, required=True)
+    p.add_argument("--fixed_val_dir", type=str, default=None)
+    p.add_argument("--synthetic_val_dir", type=str, default=None)
+    p.add_argument("--output_dir", type=str, required=True)
+    p.add_argument("--output_format", type=str, default="TIFF", choices=["TIFF","PNG","JPEG"])
+    p.add_argument("--dataset_size", type=int, default=12000)
+    p.add_argument("--train_ratio", type=float, default=0.85)
+    p.add_argument("--min_lines", type=int, default=1)
+    p.add_argument("--max_lines", type=int, default=7)
+    p.add_argument("--spacing_min", type=int, default=15)
+    p.add_argument("--spacing_max", type=int, default=35)
+    p.add_argument("--canvas_width", type=int, default=2470)
+    p.add_argument("--canvas_height", type=int, default=1200)
+    p.add_argument("--padding", type=int, default=40)
+    p.add_argument("--train_fixed_cap", type=float, default=1.5)
+    p.add_argument("--train_synthetic_cap", type=float, default=2.5)
+    p.add_argument("--val_fixed_cap", type=float, default=1.0)
+    p.add_argument("--val_synthetic_cap", type=float, default=2.0)
+    p.add_argument("--crop_whitespace", action="store_true", default=True)
+    p.add_argument("--no_crop_whitespace", action="store_true")
+    p.add_argument("--clean_left_edge", action="store_true", default=True)
+    p.add_argument("--no_clean_left_edge", action="store_true")
+    p.add_argument("--whitespace_threshold", type=int, default=250)
+    p.add_argument("--edge_pixels", type=int, default=8)
+    p.add_argument("--max_attempts", type=int, default=500)
+    p.add_argument("--seed", type=int, default=42)
+    p.add_argument("--gc_interval", type=int, default=100)
+    return p.parse_args()
+
+
+def extract_writer_id(filename):
+    basename = os.path.splitext(os.path.basename(filename))[0]
+    parts = basename.split('_')
+    return parts[0] if parts else basename
+
+
+def load_line_dataset(directory, name="Dataset"):
+    if not directory or not os.path.exists(directory):
+        return []
+    files = []
+    for ext in ["*.tif","*.tiff","*.png","*.jpg","*.jpeg","*.bmp"]:
+        files.extend(glob.glob(os.path.join(directory, ext)))
+        files.extend(glob.glob(os.path.join(directory, ext.upper())))
+    files = sorted(list(set(files)))
+    data, skipped = [], 0
+    for p in files:
+        lp = os.path.splitext(p)[0] + ".txt"
+        if not os.path.exists(lp):
+            skipped += 1; continue
+        try:
+            with open(lp, "r", encoding="utf-8") as f: label = f.readline().strip()
+        except:
+            try:
+                with open(lp, "r", encoding="utf-8-sig") as f: label = f.readline().strip()
+            except: skipped += 1; continue
+        if label: data.append((p, label))
+    print(f"    {name}: {len(data)} lines, {skipped} skipped")
+    return data
+
+
+def merge_lines_by_writer(source_pairs):
+    merged = defaultdict(list)
+    counts = defaultdict(lambda: defaultdict(int))
+    for src, lines in source_pairs:
+        for path, label in lines:
+            wid = extract_writer_id(path)
+            merged[wid].append((path, label, src))
+            counts[wid][src] += 1
+    return dict(merged), {k: dict(v) for k, v in counts.items()}
+
+
+class SingleWriterParagraphGenerator:
+    def __init__(self, merged, totals, fixed_cap, synth_cap, min_l, max_l, max_att):
+        self.merged = merged
+        self.used = set()
+        self.totals = totals
+        self.usage = defaultdict(int)
+        self.fcap, self.scap = fixed_cap, synth_cap
+        self.min_l, self.max_l, self.max_att = min_l, max_l, max_att
+        self.line_usage = defaultdict(int)
+        self.line_src = {}
+        for lines in merged.values():
+            for p, _, s in lines: self.line_src[p] = s
+        self.valid = {w: l for w, l in merged.items() if len(l) >= min_l}
+        self.wlist = list(self.valid.keys())
+        self.writers_used = set()
+        self.src_para = defaultdict(int)
+        self.n_paras = 0
+        self.n_lines = 0
+        self.n_dups = 0
+
+    def _capped(self, s):
+        if s == "unique": return False
+        c = self.fcap if s == "fixed" else self.scap
+        return self.usage[s] >= int(c * self.totals.get(s, 0))
+
+    def _both_capped(self):
+        return self._capped("fixed") and self._capped("synthetic")
+
+    def _avail(self, wlines):
+        return [x for x in wlines if x[2] == "unique" or not self._capped(x[2])]
+
+    def get_paragraph_lines(self):
+        if not self.wlist: return None
+        bc = self._both_capped()
+        for _ in range(self.max_att):
+            wid = random.choice(self.wlist)
+            av = self._avail(self.valid[wid])
+            if len(av) < self.min_l: continue
+            nl = random.randint(self.min_l, min(self.max_l, len(av)))
+            sel = None
+            if nl >= 2 and not bc:
+                srcs = set(s for _, _, s in av)
+                if len(srcs) < 2:
+                    if self.min_l <= 1: nl = 1; sel = random.sample(av, 1)
+                    else: continue
+                else:
+                    for _ in range(30):
+                        c = random.sample(av, nl)
+                        if len(set(s for _, _, s in c)) >= 2: sel = c; break
+                    if sel is None: continue
+            else:
+                sel = random.sample(av, nl)
+            if sel is None: continue
+            key = tuple(l for _, l, _ in sel)
+            if key in self.used: self.n_dups += 1; continue
+            tmp = defaultdict(int)
+            for _, _, s in sel:
+                if s in ("fixed", "synthetic"): tmp[s] += 1
+            ok = True
+            for s in ("fixed", "synthetic"):
+                if tmp[s] > 0:
+                    c = self.fcap if s == "fixed" else self.scap
+                    if self.usage[s] + tmp[s] > int(c * self.totals.get(s, 0)): ok = False; break
+            if not ok: continue
+            self.used.add(key); self.n_paras += 1; self.n_lines += nl
+            self.writers_used.add(wid)
+            si = set()
+            for p, _, s in sel:
+                self.usage[s] += 1; self.line_usage[p] += 1; si.add(s)
+            for s in si: self.src_para[s] += 1
+            return sel, wid
+        return None
+
+    def get_stats(self):
+        st = {}
+        for s in ["unique", "fixed", "synthetic"]:
+            t = self.totals.get(s, 0); u = self.usage.get(s, 0)
+            uu = sum(1 for p, c in self.line_usage.items() if c > 0 and self.line_src.get(p) == s)
+            st[s] = {'available': t, 'used': u, 'unique_used': uu,
+                      'ratio': u / max(t, 1), 'utilisation': uu / max(t, 1) * 100}
+        return st
+
+
+def load_image(path):
+    try: return Image.open(path).convert("RGB")
+    except: return None
+
+
+def crop_whitespace(image, threshold=250, margin=5):
+    g = np.array(image.convert('L'))
+    m = g < threshold
+    r, c = np.any(m, axis=1), np.any(m, axis=0)
+    if not np.any(r) or not np.any(c): return image
+    ri, ci = np.where(r)[0], np.where(c)[0]
+    return image.crop((max(0, ci[0]-margin), max(0, ri[0]-margin),
+                        min(image.width, ci[-1]+margin+1), min(image.height, ri[-1]+margin+1)))
+
+
+def clean_left_edge(image, edge_px=8, wt=240, rs=10, vt=500):
+    a = np.array(image, dtype=np.float32)
+    _, w = a.shape[:2]
+    if w <= edge_px: return image
+    for col in range(min(edge_px, w)):
+        cd = a[:, col, :]
+        rm, gm, bm = np.mean(cd[:,0]), np.mean(cd[:,1]), np.mean(cd[:,2])
+        ov = (rm+gm+bm)/3; v = np.var(cd)
+        if (ov > wt or (rm > gm+rs and rm > bm+rs) or
+            (v < vt and ov > 180) or (rm > 200 and rm > gm and rm > bm and ov > 180)):
+            a[:, col, :] = 255.0
+    return Image.fromarray(a.astype(np.uint8))
+
+
+def process_line(img, cw, do_crop, do_clean, wst, epx):
+    if do_crop: img = crop_whitespace(img, threshold=wst, margin=3)
+    if do_clean: img = clean_left_edge(img, edge_px=epx)
+    if img.width > cw:
+        s = cw / img.width
+        img = img.resize((cw, max(int(img.height * s), 20)), Image.Resampling.LANCZOS)
+    return img
+
+
+def create_paragraph(imgs, sp, cw, ch, pad, content_w, do_crop, do_clean, wst, epx):
+    proc = [process_line(i, content_w, do_crop, do_clean, wst, epx)
+            for i in imgs if i.width > 0 and i.height > 0]
+    if not proc: return None, 0
+    th = pad*2 + sum(p.height for p in proc) + sp*(len(proc)-1)
+    ah = min(th, ch)
+    canvas = Image.new('RGB', (cw + pad*2, ah), (255, 255, 255))
+    y, used = pad, 0
+    for p in proc:
+        if y + p.height > ah - pad: break
+        x = max(cw + pad - p.width, pad)
+        canvas.paste(p, (x, y)); y += p.height + sp; used += 1
+    return canvas, used
+
+
+def generate_split(gen, n, out_dir, name, cw, ch, pad, smin, smax,
+                   do_crop, do_clean, wst, epx, fmt, gc_int):
+    os.makedirs(out_dir, exist_ok=True)
+    content_w = cw - pad*2
+    wc = defaultdict(int); ld = defaultdict(int)
+    cnt, err = 0, 0
+    pbar = tqdm(range(n), desc=f"Generating {name}")
+    for i in pbar:
+        try:
+            r = gen.get_paragraph_lines()
+            if r is None: err += 1; continue
+            sel, wid = r
+            imgs = [(load_image(p), l) for p, l, _ in sel]
+            imgs = [(im, l) for im, l in imgs if im is not None]
+            if not imgs: err += 1; continue
+            sp = random.randint(smin, smax)
+            pi, lu = create_paragraph([im for im, _ in imgs], sp, cw, ch, pad,
+                                       content_w, do_crop, do_clean, wst, epx)
+            if pi is None or lu == 0: err += 1; continue
+            cnt += 1; wc[wid] += 1; ld[lu] += 1
+            ext = {"TIFF": "tif", "PNG": "png", "JPEG": "jpg"}[fmt]
+            pi.save(os.path.join(out_dir, f"{wid}_para_{wc[wid]:04d}.{ext}"), fmt)
+            with open(os.path.join(out_dir, f"{wid}_para_{wc[wid]:04d}.txt"), "w", encoding="utf-8") as f:
+                f.write("\n".join(l for _, l in imgs[:lu]))
+            del pi
+            if (i+1) % gc_int == 0: gc.collect()
+            pbar.set_postfix({"saved": cnt, "err": err})
+        except Exception as e:
+            err += 1
+            if err < 10: print(f"\nError: {e}")
+            gc.collect()
+    gc.collect()
+    print(f"    {name}: {cnt:,} saved, {err:,} errors")
+    return cnt, err, dict(ld)
+
+
+def print_stats(name, gen, count, ld):
+    st = gen.get_stats()
+    tl = sum(k*v for k, v in ld.items())
+    tp = sum(ld.values())
+    print(f"\n  {name}:")
+    print(f"    Paragraphs: {count:,}, Writers: {len(gen.writers_used)}")
+    if tp > 0: print(f"    Avg lines/para: {tl/tp:.2f}")
+    for s in ["unique", "fixed", "synthetic"]:
+        d = st[s]
+        if d['available'] > 0:
+            print(f"    {s.capitalize():12s}: {d['ratio']:.2f}x reuse, "
+                  f"{d['unique_used']:,}/{d['available']:,} ({d['utilisation']:.1f}%)")
+    print(f"    Duplicates rejected: {gen.n_dups:,}")
+
+
+def main():
+    args = parse_args()
+    random.seed(args.seed); np.random.seed(args.seed)
+    do_crop = args.crop_whitespace and not args.no_crop_whitespace
+    do_clean = args.clean_left_edge and not args.no_clean_left_edge
+    ts = int(args.dataset_size * args.train_ratio); vs = args.dataset_size - ts
+
+    print("\n" + "="*70)
+    print("SYNTHETIC PARAGRAPH GENERATOR")
+    print("="*70)
+    print(f"Size: {args.dataset_size:,} (train={ts:,}, val={vs:,})")
+
+    print("\n[1] Loading lines...")
+    ut = load_line_dataset(args.unique_train_dir, "Unique Train")
+    ft = load_line_dataset(args.fixed_train_dir, "Fixed Train")
+    st = load_line_dataset(args.synthetic_train_dir, "Synth Train")
+    uv = load_line_dataset(args.unique_val_dir, "Unique Val")
+    fv = load_line_dataset(args.fixed_val_dir, "Fixed Val")
+    sv = load_line_dataset(args.synthetic_val_dir, "Synth Val")
+
+    tt = {"unique": len(ut), "fixed": len(ft), "synthetic": len(st)}
+    vt = {"unique": len(uv), "fixed": len(fv), "synthetic": len(sv)}
+
+    print("\n[2] Verifying isolation...")
+    tp = set(os.path.abspath(p) for p, _ in ut+ft+st)
+    vp = set(os.path.abspath(p) for p, _ in uv+fv+sv)
+    ov = tp & vp
+    print(f"    {'WARNING: '+str(len(ov))+' overlap!' if ov else 'Zero overlap confirmed'}")
+    del tp, vp
+
+    print("\n[3] Merging by writer...")
+    src_t = [("unique", ut)] + ([("fixed", ft)] if ft else []) + ([("synthetic", st)] if st else [])
+    src_v = [("unique", uv)] + ([("fixed", fv)] if fv else []) + ([("synthetic", sv)] if sv else [])
+    tm, _ = merge_lines_by_writer(src_t)
+    vm, _ = merge_lines_by_writer(src_v)
+    print(f"    Train: {len(tm)} writers | Val: {len(vm)} writers")
+
+    tg = SingleWriterParagraphGenerator(tm, tt, args.train_fixed_cap, args.train_synthetic_cap,
+                                         args.min_lines, args.max_lines, args.max_attempts)
+    vg = SingleWriterParagraphGenerator(vm, vt, args.val_fixed_cap, args.val_synthetic_cap,
+                                         args.min_lines, args.max_lines, args.max_attempts)
+
+    td = os.path.join(args.output_dir, "Training")
+    vd = os.path.join(args.output_dir, "Validation")
+
+    print(f"\n[4] Generating training ({ts:,})...")
+    tc, te, tld = generate_split(tg, ts, td, "Training", args.canvas_width, args.canvas_height,
+                                  args.padding, args.spacing_min, args.spacing_max,
+                                  do_crop, do_clean, args.whitespace_threshold, args.edge_pixels,
+                                  args.output_format, args.gc_interval)
+
+    print(f"\n[5] Generating validation ({vs:,})...")
+    vc, ve, vld = generate_split(vg, vs, vd, "Validation", args.canvas_width, args.canvas_height,
+                                  args.padding, args.spacing_min, args.spacing_max,
+                                  do_crop, do_clean, args.whitespace_threshold, args.edge_pixels,
+                                  args.output_format, args.gc_interval)
+
+    print("\n" + "="*70)
+    print("COMPLETE")
+    print("="*70)
+    print(f"  Total: {tc+vc:,} (train={tc:,}, val={vc:,}, errors={te+ve:,})")
+    print_stats("Training", tg, tc, tld)
+    print_stats("Validation", vg, vc, vld)
+    print(f"\n  Output: {args.output_dir}")
+    print(f"  Finished: {datetime.now():%Y-%m-%d %H:%M:%S}")
+
+    info = os.path.join(args.output_dir, "generation_info.txt")
+    with open(info, "w", encoding="utf-8") as f:
+        f.write(f"Generated: {datetime.now():%Y-%m-%d %H:%M:%S}\n")
+        f.write(f"Size: {args.dataset_size}, Train: {tc}, Val: {vc}\n")
+        f.write(f"Config: {vars(args)}\n")
+        for nm, g in [("Training", tg), ("Validation", vg)]:
+            s = g.get_stats(); f.write(f"\n{nm}:\n")
+            for src in ["unique","fixed","synthetic"]:
+                d = s[src]
+                if d['available'] > 0:
+                    f.write(f"  {src}: {d['used']:,}/{d['available']:,} ({d['ratio']:.2f}x)\n")
+    print(f"  Info: {info}")
+    gc.collect()
+
+
+if __name__ == "__main__":
+    main()

Scripts/inference.py

@@ -0,0 +1,516 @@
+"""
+Kurdish Handwritten Paragraph Recognition - Inference Script
+
+Usage:
+    # Single image
+    python inference.py --image sample.tif --model_path model.safetensors --vocab_path vocab.json
+
+    # Directory of images
+    python inference.py --image_dir ./test_images --model_path model.safetensors --vocab_path vocab.json
+
+    # With .pth checkpoint
+    python inference.py --image sample.tif --model_path finetuned_model.pth --vocab_path vocab.json
+
+    # KHATT Arabic model (different vocab)
+    python inference.py --image arabic_sample.tif --model_path khatt_model.safetensors \
+                        --vocab_path khatt_vocab.json
+"""
+
+import os
+import glob
+import json
+import math
+import time
+import argparse
+from PIL import Image
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import torchvision.transforms as transforms
+import torchvision.models as models
+
+
+# ===============================
+# Argument Parser
+# ===============================
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Kurdish Handwritten Paragraph Recognition - Inference")
+
+    # Input
+    parser.add_argument("--image", type=str, default=None,
+                        help="Path to a single paragraph image")
+    parser.add_argument("--image_dir", type=str, default=None,
+                        help="Directory of paragraph images to process")
+
+    # Model and vocabulary
+    parser.add_argument("--model_path", type=str, required=True,
+                        help="Path to model weights (.pth or .safetensors)")
+    parser.add_argument("--vocab_path", type=str, required=True,
+                        help="Path to vocabulary JSON file (vocab.json)")
+    parser.add_argument("--config_path", type=str, default=None,
+                        help="Path to config.json (auto-loads architecture settings)")
+
+    # Image dimensions
+    parser.add_argument("--img_height", type=int, default=600)
+    parser.add_argument("--img_width", type=int, default=1235)
+
+    # Model architecture (overridden by config.json if provided)
+    parser.add_argument("--hidden_size", type=int, default=256)
+    parser.add_argument("--encoder_layers", type=int, default=3)
+    parser.add_argument("--decoder_layers", type=int, default=6)
+    parser.add_argument("--num_heads", type=int, default=8)
+    parser.add_argument("--ff_dim", type=int, default=2048)
+    parser.add_argument("--max_seq_len", type=int, default=555)
+    parser.add_argument("--use_upsample", action="store_true", default=True)
+    parser.add_argument("--no_upsample", action="store_true")
+
+    # Output
+    parser.add_argument("--output_file", type=str, default=None,
+                        help="Save predictions to text file")
+    parser.add_argument("--show_timing", action="store_true",
+                        help="Show per-image inference time")
+
+    # Device
+    parser.add_argument("--device", type=str, default=None,
+                        help="Device (cuda/cpu, auto-detected if not set)")
+
+    return parser.parse_args()
+
+
+# ===============================
+# Vocabulary
+# ===============================
+
+PAD_TOKEN = 0
+SOS_TOKEN = 1
+EOS_TOKEN = 2
+
+
+def load_vocabulary(vocab_path):
+    """Load vocabulary from JSON file."""
+    with open(vocab_path, "r", encoding="utf-8") as f:
+        vocab_data = json.load(f)
+
+    if "vocab_list" in vocab_data:
+        char_list = vocab_data["vocab_list"]
+    elif "char_to_idx" in vocab_data:
+        mapping = vocab_data["char_to_idx"]
+        char_list = [None] * len(mapping)
+        for char, idx in mapping.items():
+            char_list[idx] = char
+    else:
+        raise ValueError("Vocabulary JSON must contain 'vocab_list' or 'char_to_idx'")
+
+    idx_to_char = {idx: char for idx, char in enumerate(char_list)}
+    return char_list, idx_to_char
+
+
+def decode_output(tensor, idx_to_char):
+    """Convert tensor of character indices to text."""
+    if isinstance(tensor, torch.Tensor):
+        tensor = tensor.cpu().tolist()
+    text = ""
+    for idx in tensor:
+        if idx == PAD_TOKEN or idx == SOS_TOKEN:
+            continue
+        if idx == EOS_TOKEN:
+            break
+        if idx in idx_to_char:
+            text += idx_to_char[idx]
+    return text
+
+
+# ===============================
+# Positional Encodings
+# ===============================
+
+class PositionalEncoding2D(nn.Module):
+    """2D sinusoidal positional encoding for visual feature maps."""
+
+    def __init__(self, d_model, max_h=100, max_w=300):
+        super().__init__()
+        pe = torch.zeros(max_h, max_w, d_model)
+        d_half = d_model // 2
+
+        pos_h = torch.arange(0, max_h, dtype=torch.float).unsqueeze(1)
+        div_h = torch.exp(torch.arange(0, d_half, 2).float() * (-math.log(10000.0) / d_half))
+        pe_h = torch.zeros(max_h, d_half)
+        pe_h[:, 0::2] = torch.sin(pos_h * div_h)
+        pe_h[:, 1::2] = torch.cos(pos_h * div_h)
+
+        pos_w = torch.arange(0, max_w, dtype=torch.float).unsqueeze(1)
+        div_w = torch.exp(torch.arange(0, d_half, 2).float() * (-math.log(10000.0) / d_half))
+        pe_w = torch.zeros(max_w, d_half)
+        pe_w[:, 0::2] = torch.sin(pos_w * div_w)
+        pe_w[:, 1::2] = torch.cos(pos_w * div_w)
+
+        for h in range(max_h):
+            for w in range(max_w):
+                pe[h, w, :d_half] = pe_h[h]
+                pe[h, w, d_half:] = pe_w[w]
+
+        self.register_buffer('pe', pe)
+
+    def forward(self, x, height, width):
+        _, seq_len, d_model = x.shape
+        pe_2d = self.pe[:height, :width, :].reshape(height * width, d_model)
+        if seq_len <= pe_2d.size(0):
+            pe_2d = pe_2d[:seq_len]
+        else:
+            pad = torch.zeros(seq_len - pe_2d.size(0), d_model, device=x.device)
+            pe_2d = torch.cat([pe_2d, pad], dim=0)
+        return x + pe_2d.unsqueeze(0)
+
+
+class PositionalEncoding1D(nn.Module):
+    """1D sinusoidal positional encoding for decoder sequences."""
+
+    def __init__(self, d_model, max_len=1000):
+        super().__init__()
+        pe = torch.zeros(max_len, d_model)
+        position = torch.arange(0, max_len, dtype=torch.float).unsqueeze(1)
+        div_term = torch.exp(torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model))
+        pe[:, 0::2] = torch.sin(position * div_term)
+        pe[:, 1::2] = torch.cos(position * div_term)
+        self.register_buffer('pe', pe.unsqueeze(0))
+
+    def forward(self, x):
+        return x + self.pe[:, :x.size(1), :]
+
+
+# ===============================
+# CNN Feature Extractor
+# ===============================
+
+class CNNFeatureExtractor(nn.Module):
+    """DenseNet-121 backbone with optional horizontal upsampling."""
+
+    def __init__(self, output_dim=256, use_upsample=True):
+        super().__init__()
+        densenet = models.densenet121(weights=models.DenseNet121_Weights.DEFAULT)
+        self.features = densenet.features
+        backbone_channels = 1024
+
+        if use_upsample:
+            self.upsample = nn.Sequential(
+                nn.ConvTranspose2d(backbone_channels, 512,
+                                   kernel_size=(1, 4), stride=(1, 2), padding=(0, 1)),
+                nn.BatchNorm2d(512),
+                nn.ReLU(inplace=True))
+            adapt_in = 512
+        else:
+            self.upsample = None
+            adapt_in = backbone_channels
+
+        self.adaptation = nn.Sequential(
+            nn.Conv2d(adapt_in, output_dim, kernel_size=1),
+            nn.BatchNorm2d(output_dim),
+            nn.ReLU(inplace=True))
+
+    def forward(self, x):
+        features = F.relu(self.features(x), inplace=True)
+        if self.upsample is not None:
+            features = self.upsample(features)
+        features = self.adaptation(features)
+        b, c, h, w = features.shape
+        return features.view(b, c, h * w).permute(0, 2, 1), h, w
+
+
+# ===============================
+# Transformer OCR Model
+# ===============================
+
+class TransformerOCRParagraphModel(nn.Module):
+    """DenseNet121-Transformer for end-to-end paragraph recognition."""
+
+    def __init__(self, vocab_size, hidden_size=256, nhead=8,
+                 num_encoder_layers=3, num_decoder_layers=6,
+                 dim_feedforward=2048, dropout=0.0,
+                 use_upsample=True, max_seq_len=555):
+        super().__init__()
+
+        self.max_seq_len = max_seq_len
+        self.vocab_size = vocab_size
+
+        self.feature_extractor = CNNFeatureExtractor(
+            output_dim=hidden_size, use_upsample=use_upsample)
+
+        self.pos_encoder_2d = PositionalEncoding2D(hidden_size)
+        self.pos_decoder_1d = PositionalEncoding1D(hidden_size, max_len=max_seq_len)
+
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=hidden_size, nhead=nhead,
+            dim_feedforward=dim_feedforward, dropout=dropout,
+            batch_first=True)
+        self.transformer_encoder = nn.TransformerEncoder(
+            encoder_layer, num_layers=num_encoder_layers)
+
+        decoder_layer = nn.TransformerDecoderLayer(
+            d_model=hidden_size, nhead=nhead,
+            dim_feedforward=dim_feedforward, dropout=dropout,
+            batch_first=True)
+        self.transformer_decoder = nn.TransformerDecoder(
+            decoder_layer, num_layers=num_decoder_layers)
+
+        self.token_embedding = nn.Embedding(vocab_size, hidden_size)
+        self.output_projection = nn.Linear(hidden_size, vocab_size)
+
+    def _generate_square_subsequent_mask(self, sz):
+        mask = (torch.triu(torch.ones(sz, sz)) == 1).transpose(0, 1)
+        return mask.float().masked_fill(mask == 0, float('-inf')).masked_fill(mask == 1, 0.0)
+
+    def generate(self, img, max_length=None):
+        """Auto-regressive greedy generation for a single image."""
+        if max_length is None:
+            max_length = self.max_seq_len
+
+        self.eval()
+        with torch.no_grad():
+            if img.dim() == 3:
+                img = img.unsqueeze(0)
+
+            memory, feat_h, feat_w = self.feature_extractor(img)
+            memory = self.pos_encoder_2d(memory, feat_h, feat_w)
+            memory = self.transformer_encoder(memory)
+
+            ys = torch.ones(1, 1).fill_(SOS_TOKEN).long().to(img.device)
+
+            for _ in range(max_length - 1):
+                tgt_embedded = self.pos_decoder_1d(self.token_embedding(ys))
+                tgt_mask = self._generate_square_subsequent_mask(ys.size(1)).to(img.device)
+                out = self.transformer_decoder(tgt_embedded, memory, tgt_mask=tgt_mask)
+                out = self.output_projection(out)
+
+                next_word = out[0, -1].argmax().item()
+                ys = torch.cat([ys, torch.ones(1, 1).long().fill_(next_word).to(img.device)], dim=1)
+
+                if next_word == EOS_TOKEN:
+                    break
+
+        return ys[0]
+
+    def generate_batch(self, imgs, max_length=None):
+        """Auto-regressive greedy batch generation."""
+        if max_length is None:
+            max_length = self.max_seq_len
+
+        self.eval()
+        batch_size = imgs.size(0)
+
+        with torch.no_grad():
+            memory, feat_h, feat_w = self.feature_extractor(imgs)
+            memory = self.pos_encoder_2d(memory, feat_h, feat_w)
+            memory = self.transformer_encoder(memory)
+
+            ys = torch.ones(batch_size, 1).fill_(SOS_TOKEN).long().to(imgs.device)
+            finished = torch.zeros(batch_size, dtype=torch.bool, device=imgs.device)
+
+            for _ in range(max_length - 1):
+                tgt_embedded = self.pos_decoder_1d(self.token_embedding(ys))
+                tgt_mask = self._generate_square_subsequent_mask(ys.size(1)).to(imgs.device)
+                out = self.transformer_decoder(tgt_embedded, memory, tgt_mask=tgt_mask)
+                out = self.output_projection(out)
+
+                next_tokens = out[:, -1].argmax(dim=-1)
+                next_tokens[finished] = PAD_TOKEN
+                ys = torch.cat([ys, next_tokens.unsqueeze(1)], dim=1)
+                finished = finished | (next_tokens == EOS_TOKEN)
+                if finished.all():
+                    break
+
+        return ys
+
+
+# ===============================
+# Image Preprocessing
+# ===============================
+
+def preprocess_image(image_path, img_height, img_width):
+    """Load and preprocess a paragraph image.
+    Aspect-ratio-preserving resize, right-aligned on white canvas for RTL."""
+    image = Image.open(image_path).convert("RGB")
+    orig_w, orig_h = image.size
+
+    scale = min(img_width / orig_w, img_height / orig_h)
+    new_w = int(orig_w * scale)
+    new_h = int(orig_h * scale)
+    image = image.resize((new_w, new_h), Image.Resampling.LANCZOS)
+
+    canvas = Image.new("RGB", (img_width, img_height), color=(255, 255, 255))
+    x_offset = img_width - new_w  # Right-align for RTL
+    canvas.paste(image, (x_offset, 0))
+
+    transform = transforms.Compose([
+        transforms.ToTensor(),
+        transforms.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225))
+    ])
+    return transform(canvas)
+
+
+# ===============================
+# Config Loader
+# ===============================
+
+def load_config(config_path):
+    """Load architecture settings from config.json."""
+    with open(config_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+# ===============================
+# Main
+# ===============================
+
+def main():
+    args = parse_args()
+
+    if args.image is None and args.image_dir is None:
+        print("Error: Provide --image or --image_dir")
+        return
+
+    # Device
+    if args.device:
+        device = torch.device(args.device)
+    else:
+        device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"Device: {device}")
+
+    # Load config if provided (overrides CLI args)
+    if args.config_path and os.path.exists(args.config_path):
+        config = load_config(args.config_path)
+        print(f"Loaded config from: {args.config_path}")
+        args.hidden_size = config.get("hidden_size", args.hidden_size)
+        args.encoder_layers = config.get("num_encoder_layers", args.encoder_layers)
+        args.decoder_layers = config.get("num_decoder_layers", args.decoder_layers)
+        args.num_heads = config.get("num_attention_heads", args.num_heads)
+        args.ff_dim = config.get("feed_forward_dim", args.ff_dim)
+        args.max_seq_len = config.get("max_sequence_length", args.max_seq_len)
+        args.img_height = config.get("image_height", args.img_height)
+        args.img_width = config.get("image_width", args.img_width)
+        if "use_upsample" in config:
+            args.use_upsample = config["use_upsample"]
+            args.no_upsample = not config["use_upsample"]
+
+    use_upsample = args.use_upsample and not args.no_upsample
+
+    # Vocabulary
+    char_list, idx_to_char = load_vocabulary(args.vocab_path)
+    vocab_size = len(char_list)
+    print(f"Vocabulary: {vocab_size} tokens")
+
+    # Model
+    model = TransformerOCRParagraphModel(
+        vocab_size=vocab_size,
+        hidden_size=args.hidden_size,
+        nhead=args.num_heads,
+        num_encoder_layers=args.encoder_layers,
+        num_decoder_layers=args.decoder_layers,
+        dim_feedforward=args.ff_dim,
+        use_upsample=use_upsample,
+        max_seq_len=args.max_seq_len
+    ).to(device)
+
+    # Load weights
+    print(f"Loading weights: {args.model_path}")
+    if args.model_path.endswith(".safetensors"):
+        from safetensors.torch import load_file
+        state_dict = load_file(args.model_path)
+    else:
+        checkpoint = torch.load(args.model_path, map_location=device)
+        state_dict = checkpoint.get("model_state_dict", checkpoint)
+
+    # Handle PE size mismatches
+    model_state = model.state_dict()
+    filtered = {}
+    for key, value in state_dict.items():
+        if key in model_state:
+            if value.shape == model_state[key].shape:
+                filtered[key] = value
+    model.load_state_dict(filtered, strict=False)
+
+    model.eval()
+    total_params = sum(p.numel() for n, p in model.named_parameters() if '.pe' not in n)
+    print(f"Model loaded: {total_params:,} parameters")
+    print(f"Upsample: {'ON' if use_upsample else 'OFF'}")
+    print(f"Image size: {args.img_height} x {args.img_width}")
+    print(f"Max sequence length: {args.max_seq_len}")
+
+    # Collect images
+    image_paths = []
+    if args.image:
+        image_paths = [args.image]
+    elif args.image_dir:
+        for ext in ("*.tif", "*.tiff", "*.png", "*.jpg", "*.jpeg", "*.bmp"):
+            image_paths.extend(glob.glob(os.path.join(args.image_dir, ext)))
+            image_paths.extend(glob.glob(os.path.join(args.image_dir, ext.upper())))
+        image_paths = sorted(list(set(image_paths)))
+
+    if not image_paths:
+        print("No images found.")
+        return
+
+    print(f"\nProcessing {len(image_paths)} image(s)...\n")
+
+    # Output file
+    out_file = None
+    if args.output_file:
+        out_file = open(args.output_file, "w", encoding="utf-8")
+
+    total_time = 0
+
+    for img_path in image_paths:
+        filename = os.path.basename(img_path)
+
+        # Preprocess
+        tensor = preprocess_image(img_path, args.img_height, args.img_width).to(device)
+
+        # Inference with timing
+        if torch.cuda.is_available():
+            torch.cuda.synchronize()
+        start = time.perf_counter()
+
+        output = model.generate(tensor)
+
+        if torch.cuda.is_available():
+            torch.cuda.synchronize()
+        elapsed = time.perf_counter() - start
+        total_time += elapsed
+
+        # Decode
+        text = decode_output(output, idx_to_char)
+        lines = text.split('\n')
+
+        # Display
+        print(f"{'='*60}")
+        print(f"File: {filename}")
+        if args.show_timing:
+            print(f"Time: {elapsed*1000:.1f} ms")
+        print(f"Lines detected: {len(lines)}")
+        print(f"{'─'*60}")
+        for i, line in enumerate(lines):
+            print(f"  Line {i+1}: {line}")
+        print()
+
+        # Save to file
+        if out_file:
+            out_file.write(f"# {filename}\n")
+            out_file.write(text + "\n\n")
+
+    # Summary
+    print(f"{'='*60}")
+    print(f"Done. {len(image_paths)} image(s) processed.")
+    if args.show_timing:
+        avg_ms = (total_time / len(image_paths)) * 1000
+        print(f"Average inference: {avg_ms:.1f} ms/image")
+        print(f"Total time: {total_time:.2f} s")
+
+    if out_file:
+        out_file.close()
+        print(f"Predictions saved to: {args.output_file}")
+
+
+if __name__ == "__main__":
+    main()

Scripts/pretrain.py

@@ -0,0 +1,987 @@
+"""
+Kurdish Handwritten Paragraph Recognition - Pre-training Script
+DenseNet121-Transformer Architecture with Curriculum Learning
+
+Pre-trains the model on synthetic paragraph images before fine-tuning
+on real handwritten paragraphs.
+
+Usage:
+    python pretrain.py --data_dir ./data/SyntheticParagraphs_12000 --vocab_path ./vocab.json
+    python pretrain.py --data_dir ./data/SyntheticParagraphs_12000 --vocab_path ./vocab.json --no_curriculum
+"""
+
+import os
+import glob
+import time
+import argparse
+import json
+import math
+import random
+import numpy as np
+from PIL import Image
+from datetime import datetime
+
+import torch
+import torch.nn as nn
+import torch.optim as optim
+import torch.utils.data as data
+import torchvision.transforms as transforms
+import torchvision.models as models
+from torchvision.transforms import InterpolationMode
+from torch.nn import functional as F
+from torch.amp import autocast, GradScaler
+from tqdm import tqdm
+import gc
+
+
+# ===============================
+# Argument Parser
+# ===============================
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Kurdish Handwritten Paragraph Recognition - Pre-training")
+
+    # Data paths
+    parser.add_argument("--data_dir", type=str, required=True,
+                        help="Root directory with Training/ and Validation/ subfolders")
+    parser.add_argument("--vocab_path", type=str, required=True,
+                        help="Path to vocabulary JSON file (vocab.json)")
+
+    # Image dimensions
+    parser.add_argument("--img_height", type=int, default=600)
+    parser.add_argument("--img_width", type=int, default=1235)
+    parser.add_argument("--max_seq_len", type=int, default=555)
+
+    # Training hyperparameters
+    parser.add_argument("--batch_size", type=int, default=16)
+    parser.add_argument("--num_epochs", type=int, default=80)
+    parser.add_argument("--learning_rate", type=float, default=1e-4)
+    parser.add_argument("--grad_clip", type=float, default=5.0)
+    parser.add_argument("--weight_decay", type=float, default=1e-4)
+    parser.add_argument("--seed", type=int, default=42)
+
+    # Model architecture
+    parser.add_argument("--hidden_size", type=int, default=256)
+    parser.add_argument("--encoder_layers", type=int, default=3)
+    parser.add_argument("--decoder_layers", type=int, default=6)
+    parser.add_argument("--num_heads", type=int, default=8)
+    parser.add_argument("--ff_dim", type=int, default=2048)
+    parser.add_argument("--dropout", type=float, default=0.3)
+    parser.add_argument("--use_upsample", action="store_true", default=True,
+                        help="Enable horizontal upsampling layer (default: True)")
+    parser.add_argument("--no_upsample", action="store_true",
+                        help="Disable horizontal upsampling layer")
+
+    # Teacher forcing
+    parser.add_argument("--tf_noise_rate", type=float, default=0.15,
+                        help="Teacher forcing noise rate (default: 0.15)")
+
+    # Curriculum learning
+    parser.add_argument("--no_curriculum", action="store_true",
+                        help="Disable curriculum learning (train on all data from start)")
+
+    # LR scheduler
+    parser.add_argument("--lr_step_size", type=int, default=15,
+                        help="StepLR step size in epochs")
+    parser.add_argument("--lr_gamma", type=float, default=0.5,
+                        help="StepLR decay factor")
+
+    # Early stopping
+    parser.add_argument("--patience", type=int, default=15)
+
+    # Training options
+    parser.add_argument("--mixed_precision", action="store_true", default=True)
+    parser.add_argument("--no_mixed_precision", action="store_true")
+    parser.add_argument("--no_aug", action="store_true",
+                        help="Disable data augmentation")
+
+    # CER computation
+    parser.add_argument("--cer_every", type=int, default=5,
+                        help="Compute train CER every N epochs (0 to disable)")
+    parser.add_argument("--cer_max_samples", type=int, default=256,
+                        help="Max samples for train CER computation")
+
+    # Output
+    parser.add_argument("--output_dir", type=str, default="./output",
+                        help="Directory to save model and logs")
+    parser.add_argument("--model_name", type=str, default="pretrained_model",
+                        help="Base name for saved model file")
+
+    return parser.parse_args()
+
+
+# ===============================
+# Vocabulary Loader
+# ===============================
+
+def load_vocabulary(vocab_path):
+    """Load vocabulary from JSON file."""
+    with open(vocab_path, "r", encoding="utf-8") as f:
+        vocab_data = json.load(f)
+
+    if "vocab_list" in vocab_data:
+        char_list = vocab_data["vocab_list"]
+    elif "char_to_idx" in vocab_data:
+        mapping = vocab_data["char_to_idx"]
+        char_list = [None] * len(mapping)
+        for char, idx in mapping.items():
+            char_list[idx] = char
+    else:
+        raise ValueError("Vocabulary JSON must contain 'vocab_list' or 'char_to_idx'")
+
+    char_to_idx = {char: idx for idx, char in enumerate(char_list)}
+    idx_to_char = {idx: char for idx, char in enumerate(char_list)}
+
+    return char_list, char_to_idx, idx_to_char
+
+
+# Special token indices (fixed by convention)
+PAD_TOKEN = 0
+SOS_TOKEN = 1
+EOS_TOKEN = 2
+
+
+# ===============================
+# Helper Functions
+# ===============================
+
+def tensor_to_text(tensor, idx_to_char):
+    """Convert a tensor of character indices to text."""
+    if isinstance(tensor, torch.Tensor):
+        tensor = tensor.cpu().tolist()
+    text = ""
+    for idx in tensor:
+        if idx == PAD_TOKEN or idx == SOS_TOKEN:
+            continue
+        if idx == EOS_TOKEN:
+            break
+        if idx in idx_to_char:
+            text += idx_to_char[idx]
+    return text
+
+
+def count_lines_in_text(text):
+    """Count the number of lines in a paragraph text."""
+    if not text:
+        return 0
+    return text.count('\n') + 1
+
+
+# ===============================
+# Curriculum Learning
+# ===============================
+
+# Default schedule: progressive difficulty over 80 epochs
+DEFAULT_CURRICULUM = [
+    (1,  8,  1, 1),   # Epochs 1-8:   1 line only
+    (9,  16, 1, 2),   # Epochs 9-16:  1-2 lines
+    (17, 28, 2, 3),   # Epochs 17-28: 2-3 lines
+    (29, 40, 2, 4),   # Epochs 29-40: 2-4 lines
+    (41, 52, 3, 5),   # Epochs 41-52: 3-5 lines
+    (53, 64, 3, 6),   # Epochs 53-64: 3-6 lines
+    (65, 80, 4, 7),   # Epochs 65-80: 4-7 lines (full complexity)
+]
+
+
+def categorize_paragraphs_by_lines(data_dir):
+    """Group paragraph samples by their line count."""
+    categories = {}
+
+    image_files = []
+    for ext in ["*.tif", "*.tiff", "*.png", "*.jpg", "*.jpeg"]:
+        image_files.extend(glob.glob(os.path.join(data_dir, ext)))
+        image_files.extend(glob.glob(os.path.join(data_dir, ext.upper())))
+    image_files = sorted(list(set(image_files)))
+
+    for img_path in image_files:
+        label_path = os.path.splitext(img_path)[0] + ".txt"
+        if not os.path.exists(label_path):
+            continue
+
+        try:
+            with open(label_path, "r", encoding="utf-8") as f:
+                text = f.read().strip()
+        except Exception:
+            try:
+                with open(label_path, "r", encoding="utf-8-sig") as f:
+                    text = f.read().strip()
+            except Exception:
+                continue
+
+        num_lines = count_lines_in_text(text)
+        if num_lines not in categories:
+            categories[num_lines] = []
+        categories[num_lines].append((img_path, text))
+
+    return categories
+
+
+def get_curriculum_stage(epoch, schedule):
+    """Get the min/max line range for the current epoch."""
+    for start_epoch, end_epoch, min_lines, max_lines in schedule:
+        if start_epoch <= epoch <= end_epoch:
+            return min_lines, max_lines
+    return 1, 7
+
+
+def filter_paragraphs_by_lines(categories, min_lines, max_lines):
+    """Filter paragraphs to include only those within the line range."""
+    filtered = []
+    for num_lines, paragraphs in categories.items():
+        if min_lines <= num_lines <= max_lines:
+            filtered.extend(paragraphs)
+    return filtered
+
+
+# ===============================
+# Dataset
+# ===============================
+
+class KurdishParagraphDataset(data.Dataset):
+    """Dataset for Kurdish handwritten paragraph images."""
+
+    def __init__(self, root_dir=None, transform=None, max_samples=None,
+                 max_seq_len=555, filtered_data=None, img_height=600,
+                 img_width=1235, char_to_idx=None):
+        self.transform = transform
+        self.max_seq_len = max_seq_len
+        self.img_height = img_height
+        self.img_width = img_width
+        self.char_to_idx = char_to_idx
+
+        if filtered_data is not None:
+            self.data = filtered_data
+        else:
+            self.data = []
+            image_files = []
+            for ext in ["*.tif", "*.tiff", "*.png", "*.jpg", "*.jpeg"]:
+                image_files.extend(glob.glob(os.path.join(root_dir, ext)))
+                image_files.extend(glob.glob(os.path.join(root_dir, ext.upper())))
+            image_files = sorted(list(set(image_files)))
+
+            for img_path in image_files:
+                label_path = os.path.splitext(img_path)[0] + ".txt"
+                if not os.path.exists(label_path):
+                    continue
+                try:
+                    with open(label_path, "r", encoding="utf-8") as f:
+                        text = f.read().strip()
+                except Exception:
+                    try:
+                        with open(label_path, "r", encoding="utf-8-sig") as f:
+                            text = f.read().strip()
+                    except Exception:
+                        continue
+                if len(text) > 0:
+                    self.data.append((img_path, text))
+
+        if max_samples and max_samples < len(self.data):
+            random.shuffle(self.data)
+            self.data = self.data[:max_samples]
+
+        label = "filtered" if filtered_data else root_dir
+        print(f"  Loaded {len(self.data)} paragraph images ({label})")
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, idx):
+        img_path, text = self.data[idx]
+
+        image = Image.open(img_path).convert("RGB")
+        orig_width, orig_height = image.size
+
+        # Aspect-ratio-preserving resize
+        scale = min(self.img_width / orig_width, self.img_height / orig_height)
+        new_width = int(orig_width * scale)
+        new_height = int(orig_height * scale)
+        image = image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+
+        # Right-aligned on white canvas (RTL script)
+        canvas = Image.new('RGB', (self.img_width, self.img_height), (255, 255, 255))
+        x_offset = self.img_width - new_width
+        canvas.paste(image, (x_offset, 0))
+
+        if self.transform:
+            canvas = self.transform(canvas)
+
+        # Encode text to indices
+        indices = ([SOS_TOKEN] +
+                   [self.char_to_idx.get(c, self.char_to_idx.get(" ", 0)) for c in text] +
+                   [EOS_TOKEN])
+        if len(indices) > self.max_seq_len:
+            indices = indices[:self.max_seq_len - 1] + [EOS_TOKEN]
+
+        target = torch.LongTensor(indices)
+        return canvas, target, len(indices), text
+
+
+def collate_fn(batch):
+    """Collate function with padding for variable-length targets."""
+    batch.sort(key=lambda x: x[2], reverse=True)
+    images, targets, lengths, texts = zip(*batch)
+
+    images = torch.stack(images, 0)
+    max_length = max(lengths)
+
+    padded = torch.ones(len(targets), max_length).long() * PAD_TOKEN
+    for i, target in enumerate(targets):
+        padded[i, :lengths[i]] = target[:lengths[i]]
+
+    return images, padded, torch.LongTensor(lengths), texts
+
+
+# ===============================
+# Augmentation
+# ===============================
+
+def build_train_transform():
+    """Training augmentation pipeline for paragraph images."""
+    class ParagraphTransform:
+        def __call__(self, img):
+            if random.random() < 0.5:
+                img = transforms.ColorJitter(brightness=0.15, contrast=0.15)(img)
+
+            if random.random() < 0.4:
+                img = transforms.RandomAffine(
+                    degrees=2, translate=(0.02, 0.02),
+                    scale=(0.98, 1.02), shear=(-3, 3),
+                    interpolation=InterpolationMode.BILINEAR, fill=255)(img)
+
+            if random.random() < 0.2:
+                img = transforms.GaussianBlur(kernel_size=3, sigma=(0.1, 0.5))(img)
+
+            img = transforms.ToTensor()(img)
+
+            if random.random() < 0.3:
+                noise = torch.randn_like(img) * 0.01
+                img = torch.clamp(img + noise, 0.0, 1.0)
+
+            img = transforms.Normalize(
+                (0.485, 0.456, 0.406), (0.229, 0.224, 0.225))(img)
+            return img
+
+    return ParagraphTransform()
+
+
+def build_eval_transform():
+    """Evaluation transform (normalisation only)."""
+    return transforms.Compose([
+        transforms.ToTensor(),
+        transforms.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225))
+    ])
+
+
+# ===============================
+# Positional Encodings
+# ===============================
+
+class PositionalEncoding2D(nn.Module):
+    """2D sinusoidal positional encoding for visual feature maps."""
+
+    def __init__(self, d_model, max_h=100, max_w=300):
+        super().__init__()
+        pe = torch.zeros(max_h, max_w, d_model)
+        d_half = d_model // 2
+
+        pos_h = torch.arange(0, max_h, dtype=torch.float).unsqueeze(1)
+        div_h = torch.exp(torch.arange(0, d_half, 2).float() * (-math.log(10000.0) / d_half))
+        pe_h = torch.zeros(max_h, d_half)
+        pe_h[:, 0::2] = torch.sin(pos_h * div_h)
+        pe_h[:, 1::2] = torch.cos(pos_h * div_h)
+
+        pos_w = torch.arange(0, max_w, dtype=torch.float).unsqueeze(1)
+        div_w = torch.exp(torch.arange(0, d_half, 2).float() * (-math.log(10000.0) / d_half))
+        pe_w = torch.zeros(max_w, d_half)
+        pe_w[:, 0::2] = torch.sin(pos_w * div_w)
+        pe_w[:, 1::2] = torch.cos(pos_w * div_w)
+
+        for h in range(max_h):
+            for w in range(max_w):
+                pe[h, w, :d_half] = pe_h[h]
+                pe[h, w, d_half:] = pe_w[w]
+
+        self.register_buffer('pe', pe)
+
+    def forward(self, x, height, width):
+        _, seq_len, d_model = x.shape
+        pe_2d = self.pe[:height, :width, :].reshape(height * width, d_model)
+        if seq_len <= pe_2d.size(0):
+            pe_2d = pe_2d[:seq_len]
+        else:
+            pad = torch.zeros(seq_len - pe_2d.size(0), d_model, device=x.device)
+            pe_2d = torch.cat([pe_2d, pad], dim=0)
+        return x + pe_2d.unsqueeze(0)
+
+
+class PositionalEncoding1D(nn.Module):
+    """1D sinusoidal positional encoding for decoder sequences."""
+
+    def __init__(self, d_model, max_len=1000):
+        super().__init__()
+        pe = torch.zeros(max_len, d_model)
+        position = torch.arange(0, max_len, dtype=torch.float).unsqueeze(1)
+        div_term = torch.exp(torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model))
+        pe[:, 0::2] = torch.sin(position * div_term)
+        pe[:, 1::2] = torch.cos(position * div_term)
+        self.register_buffer('pe', pe.unsqueeze(0))
+
+    def forward(self, x):
+        return x + self.pe[:, :x.size(1), :]
+
+
+# ===============================
+# CNN Feature Extractor
+# ===============================
+
+class CNNFeatureExtractor(nn.Module):
+    """DenseNet-121 backbone with optional horizontal upsampling."""
+
+    def __init__(self, output_dim=256, use_upsample=True):
+        super().__init__()
+        densenet = models.densenet121(weights=models.DenseNet121_Weights.DEFAULT)
+        self.features = densenet.features
+        backbone_channels = 1024
+
+        if use_upsample:
+            self.upsample = nn.Sequential(
+                nn.ConvTranspose2d(backbone_channels, 512,
+                                   kernel_size=(1, 4), stride=(1, 2), padding=(0, 1)),
+                nn.BatchNorm2d(512),
+                nn.ReLU(inplace=True))
+            adapt_in = 512
+        else:
+            self.upsample = None
+            adapt_in = backbone_channels
+
+        self.adaptation = nn.Sequential(
+            nn.Conv2d(adapt_in, output_dim, kernel_size=1),
+            nn.BatchNorm2d(output_dim),
+            nn.ReLU(inplace=True))
+
+    def forward(self, x):
+        features = F.relu(self.features(x), inplace=True)
+        if self.upsample is not None:
+            features = self.upsample(features)
+        features = self.adaptation(features)
+        b, c, h, w = features.shape
+        return features.view(b, c, h * w).permute(0, 2, 1), h, w
+
+
+# ===============================
+# Transformer OCR Model
+# ===============================
+
+class TransformerOCRParagraphModel(nn.Module):
+    """
+    DenseNet121-Transformer for end-to-end paragraph recognition.
+
+    Architecture:
+        1. DenseNet-121 CNN + optional horizontal upsample
+        2. 2D positional encoding + Transformer encoder
+        3. Transformer decoder with 1D positional encoding
+        4. Linear output projection
+    """
+
+    def __init__(self, vocab_size, hidden_size=256, nhead=8,
+                 num_encoder_layers=3, num_decoder_layers=6,
+                 dim_feedforward=2048, dropout=0.3,
+                 use_upsample=True, max_seq_len=555,
+                 tf_noise_rate=0.15):
+        super().__init__()
+
+        self.max_seq_len = max_seq_len
+        self.vocab_size = vocab_size
+        self.tf_noise_rate = tf_noise_rate
+
+        self.feature_extractor = CNNFeatureExtractor(
+            output_dim=hidden_size, use_upsample=use_upsample)
+
+        self.pos_encoder_2d = PositionalEncoding2D(hidden_size)
+        self.pos_decoder_1d = PositionalEncoding1D(hidden_size, max_len=max_seq_len)
+
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=hidden_size, nhead=nhead,
+            dim_feedforward=dim_feedforward, dropout=dropout,
+            batch_first=True)
+        self.transformer_encoder = nn.TransformerEncoder(
+            encoder_layer, num_layers=num_encoder_layers)
+
+        decoder_layer = nn.TransformerDecoderLayer(
+            d_model=hidden_size, nhead=nhead,
+            dim_feedforward=dim_feedforward, dropout=dropout,
+            batch_first=True)
+        self.transformer_decoder = nn.TransformerDecoder(
+            decoder_layer, num_layers=num_decoder_layers)
+
+        self.token_embedding = nn.Embedding(vocab_size, hidden_size)
+        self.output_projection = nn.Linear(hidden_size, vocab_size)
+        self.hidden_size = hidden_size
+
+        nn.init.xavier_uniform_(self.token_embedding.weight)
+        nn.init.xavier_uniform_(self.output_projection.weight)
+
+    def _generate_square_subsequent_mask(self, sz):
+        mask = (torch.triu(torch.ones(sz, sz)) == 1).transpose(0, 1)
+        return mask.float().masked_fill(mask == 0, float('-inf')).masked_fill(mask == 1, 0.0)
+
+    def _add_teacher_forcing_noise(self, tgt_input):
+        """Replace random tokens to build decoder robustness."""
+        if self.tf_noise_rate <= 0 or not self.training:
+            return tgt_input
+        noise_mask = (torch.rand_like(tgt_input.float()) < self.tf_noise_rate)
+        noise_mask = noise_mask & (tgt_input != PAD_TOKEN) & (tgt_input != SOS_TOKEN)
+        random_tokens = torch.randint(3, self.vocab_size, tgt_input.shape, device=tgt_input.device)
+        return torch.where(noise_mask, random_tokens, tgt_input)
+
+    def forward(self, src, tgt, tgt_key_padding_mask=None):
+        # Encode
+        memory, feat_h, feat_w = self.feature_extractor(src)
+        memory = self.pos_encoder_2d(memory, feat_h, feat_w)
+        memory = self.transformer_encoder(memory)
+
+        # Decode with teacher forcing
+        tgt_input = self._add_teacher_forcing_noise(tgt[:, :-1])
+        tgt_embedded = self.pos_decoder_1d(self.token_embedding(tgt_input))
+
+        tgt_mask = self._generate_square_subsequent_mask(tgt_embedded.size(1)).to(src.device)
+        tgt_pad_mask = tgt_key_padding_mask[:, :-1] if tgt_key_padding_mask is not None else None
+
+        output = self.transformer_decoder(
+            tgt_embedded, memory,
+            tgt_mask=tgt_mask, tgt_key_padding_mask=tgt_pad_mask)
+
+        return self.output_projection(output)
+
+    def generate_batch(self, imgs, max_length=None):
+        """Auto-regressive greedy batch generation."""
+        if max_length is None:
+            max_length = self.max_seq_len
+        self.eval()
+        batch_size = imgs.size(0)
+
+        with torch.no_grad():
+            memory, feat_h, feat_w = self.feature_extractor(imgs)
+            memory = self.pos_encoder_2d(memory, feat_h, feat_w)
+            memory = self.transformer_encoder(memory)
+
+            ys = torch.ones(batch_size, 1).fill_(SOS_TOKEN).long().to(imgs.device)
+            finished = torch.zeros(batch_size, dtype=torch.bool, device=imgs.device)
+
+            for _ in range(max_length - 1):
+                tgt_embedded = self.pos_decoder_1d(self.token_embedding(ys))
+                tgt_mask = self._generate_square_subsequent_mask(ys.size(1)).to(imgs.device)
+                out = self.transformer_decoder(tgt_embedded, memory, tgt_mask=tgt_mask)
+                out = self.output_projection(out)
+
+                next_tokens = out[:, -1].argmax(dim=-1)
+                next_tokens[finished] = PAD_TOKEN
+                ys = torch.cat([ys, next_tokens.unsqueeze(1)], dim=1)
+                finished = finished | (next_tokens == EOS_TOKEN)
+                if finished.all():
+                    break
+
+        return [tensor_to_text(seq, idx_to_char) for seq in ys]
+
+
+# ===============================
+# Metrics
+# ===============================
+
+def levenshtein_distance(s1, s2):
+    if len(s1) < len(s2):
+        return levenshtein_distance(s2, s1)
+    if len(s2) == 0:
+        return len(s1)
+    prev = range(len(s2) + 1)
+    for c1 in s1:
+        curr = [prev[0] + 1]
+        for j, c2 in enumerate(s2):
+            curr.append(min(prev[j + 1] + 1, curr[j] + 1, prev[j] + (c1 != c2)))
+        prev = curr
+    return prev[-1]
+
+
+def calculate_cer(preds, targets):
+    total_dist = sum(levenshtein_distance(p, t) for p, t in zip(preds, targets))
+    total_chars = sum(len(t) for t in targets)
+    return total_dist / max(1, total_chars)
+
+
+def calculate_wer(preds, targets):
+    total_dist = sum(levenshtein_distance(p.split(), t.split()) for p, t in zip(preds, targets))
+    total_words = sum(len(t.split()) for t in targets)
+    return total_dist / max(1, total_words)
+
+
+def evaluate_cer_batch(model, dataloader, device, idx_to_char, max_samples=None):
+    """Compute CER using batch generation."""
+    model.eval()
+    all_preds, all_targets = [], []
+    count = 0
+
+    with torch.no_grad():
+        for images, _, _, texts in tqdm(dataloader, desc="Computing CER"):
+            images = images.to(device)
+            if max_samples and count + images.size(0) > max_samples:
+                images = images[:max_samples - count]
+                texts = texts[:max_samples - count]
+
+            preds = model.generate_batch(images)
+            all_preds.extend(preds)
+            all_targets.extend(texts)
+            count += len(preds)
+
+            if max_samples and count >= max_samples:
+                break
+
+    return calculate_cer(all_preds, all_targets)
+
+
+def evaluate_full(model, dataloader, device, idx_to_char):
+    """Full evaluation returning CER, WER, predictions, and targets."""
+    model.eval()
+    all_preds, all_targets = [], []
+
+    with torch.no_grad():
+        for images, _, _, texts in tqdm(dataloader, desc="Evaluating"):
+            images = images.to(device)
+            preds = model.generate_batch(images)
+            all_preds.extend(preds)
+            all_targets.extend(texts)
+
+    cer = calculate_cer(all_preds, all_targets)
+    wer = calculate_wer(all_preds, all_targets)
+    return cer, wer, all_preds, all_targets
+
+
+# ===============================
+# Early Stopping
+# ===============================
+
+class EarlyStopping:
+    def __init__(self, patience=15):
+        self.patience = patience
+        self.counter = 0
+        self.best_cer = float('inf')
+        self.early_stop = False
+
+    def __call__(self, val_cer, model, epoch, path):
+        if val_cer < self.best_cer:
+            self.best_cer = val_cer
+            self.counter = 0
+            torch.save({
+                'epoch': epoch,
+                'model_state_dict': model.state_dict(),
+                'val_cer': val_cer
+            }, path)
+            print(f"  Model saved (Val CER: {val_cer:.4f})")
+        else:
+            self.counter += 1
+            print(f"  Early stopping: {self.counter}/{self.patience}")
+            if self.counter >= self.patience:
+                self.early_stop = True
+                print("  Early stopping triggered.")
+
+    def reset(self):
+        self.counter = 0
+
+
+# ===============================
+# Training Functions
+# ===============================
+
+def train_epoch(model, dataloader, optimizer, criterion, device, scaler,
+                use_mixed_precision=True, grad_clip=5.0):
+    """Train for one epoch."""
+    model.train()
+    epoch_loss = 0
+
+    for images, targets, _, _ in tqdm(dataloader, desc="Training"):
+        images, targets = images.to(device), targets.to(device)
+        tgt_pad_mask = (targets == PAD_TOKEN).to(device)
+
+        optimizer.zero_grad()
+
+        if use_mixed_precision:
+            with autocast(device_type='cuda'):
+                outputs = model(images, targets, tgt_key_padding_mask=tgt_pad_mask)
+                loss = criterion(outputs.reshape(-1, outputs.shape[-1]),
+                                 targets[:, 1:].reshape(-1))
+            scaler.scale(loss).backward()
+            scaler.unscale_(optimizer)
+            torch.nn.utils.clip_grad_norm_(model.parameters(), grad_clip)
+            scaler.step(optimizer)
+            scaler.update()
+        else:
+            outputs = model(images, targets, tgt_key_padding_mask=tgt_pad_mask)
+            loss = criterion(outputs.reshape(-1, outputs.shape[-1]),
+                             targets[:, 1:].reshape(-1))
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.parameters(), grad_clip)
+            optimizer.step()
+
+        epoch_loss += loss.item()
+
+    return epoch_loss / len(dataloader)
+
+
+def evaluate_loss(model, dataloader, criterion, device, use_mixed_precision=True):
+    """Evaluate model loss."""
+    model.eval()
+    epoch_loss = 0
+
+    with torch.no_grad():
+        for images, targets, _, _ in dataloader:
+            images, targets = images.to(device), targets.to(device)
+            tgt_pad_mask = (targets == PAD_TOKEN).to(device)
+
+            if use_mixed_precision:
+                with autocast(device_type='cuda'):
+                    outputs = model(images, targets, tgt_key_padding_mask=tgt_pad_mask)
+                    loss = criterion(outputs.reshape(-1, outputs.shape[-1]),
+                                     targets[:, 1:].reshape(-1))
+            else:
+                outputs = model(images, targets, tgt_key_padding_mask=tgt_pad_mask)
+                loss = criterion(outputs.reshape(-1, outputs.shape[-1]),
+                                 targets[:, 1:].reshape(-1))
+
+            epoch_loss += loss.item()
+
+    return epoch_loss / len(dataloader)
+
+
+# ===============================
+# Main
+# ===============================
+
+def main():
+    global idx_to_char  # Used by generate_batch -> tensor_to_text
+
+    args = parse_args()
+
+    # Handle flag conflicts
+    use_upsample = args.use_upsample and not args.no_upsample
+    use_mixed_precision = args.mixed_precision and not args.no_mixed_precision
+    use_curriculum = not args.no_curriculum
+
+    # Seeds
+    torch.manual_seed(args.seed)
+    random.seed(args.seed)
+    np.random.seed(args.seed)
+
+    # Device
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"Device: {device}")
+    if torch.cuda.is_available():
+        print(f"GPU: {torch.cuda.get_device_name(0)}")
+
+    # Output directory
+    os.makedirs(args.output_dir, exist_ok=True)
+
+    # Vocabulary
+    char_list, char_to_idx, idx_to_char = load_vocabulary(args.vocab_path)
+    vocab_size = len(char_list)
+    print(f"Vocabulary size: {vocab_size}")
+
+    # Data directories
+    train_dir = os.path.join(args.data_dir, "Training")
+    val_dir = os.path.join(args.data_dir, "Validation")
+
+    # Categorize paragraphs by line count
+    print("\nCategorizing paragraphs by line count...")
+    train_categories = categorize_paragraphs_by_lines(train_dir)
+    val_categories = categorize_paragraphs_by_lines(val_dir)
+
+    total_train = sum(len(v) for v in train_categories.values())
+    total_val = sum(len(v) for v in val_categories.values())
+    print(f"  Training: {total_train} paragraphs")
+    print(f"  Validation: {total_val} paragraphs")
+
+    if use_curriculum:
+        print("\n  Curriculum schedule:")
+        for s, e, mn, mx in DEFAULT_CURRICULUM:
+            label = f"{mn} line only" if mn == mx else f"{mn}-{mx} lines"
+            print(f"    Epochs {s:2d}-{e:2d}: {label}")
+
+    # Transforms
+    train_transform = build_eval_transform() if args.no_aug else build_train_transform()
+    eval_transform = build_eval_transform()
+
+    # Dataset common kwargs
+    ds_kwargs = dict(
+        max_seq_len=args.max_seq_len,
+        img_height=args.img_height,
+        img_width=args.img_width,
+        char_to_idx=char_to_idx)
+
+    # Model
+    print("\nInitializing model...")
+    model = TransformerOCRParagraphModel(
+        vocab_size=vocab_size,
+        hidden_size=args.hidden_size,
+        nhead=args.num_heads,
+        num_encoder_layers=args.encoder_layers,
+        num_decoder_layers=args.decoder_layers,
+        dim_feedforward=args.ff_dim,
+        dropout=args.dropout,
+        use_upsample=use_upsample,
+        max_seq_len=args.max_seq_len,
+        tf_noise_rate=args.tf_noise_rate
+    ).to(device)
+
+    total_params = sum(p.numel() for p in model.parameters())
+    print(f"  Parameters: {total_params:,}")
+    print(f"  Upsample: {'ON' if use_upsample else 'OFF'}")
+    print(f"  Curriculum: {'ON' if use_curriculum else 'OFF'}")
+    print(f"  Teacher forcing noise: {args.tf_noise_rate * 100:.0f}%")
+
+    # Optimizer, scheduler, criterion
+    optimizer = optim.AdamW(model.parameters(), lr=args.learning_rate,
+                            weight_decay=args.weight_decay)
+    scheduler = optim.lr_scheduler.StepLR(optimizer,
+                                          step_size=args.lr_step_size,
+                                          gamma=args.lr_gamma)
+    criterion = nn.CrossEntropyLoss(ignore_index=PAD_TOKEN)
+    scaler = GradScaler('cuda') if use_mixed_precision else None
+    early_stopping = EarlyStopping(patience=args.patience)
+
+    best_model_path = os.path.join(args.output_dir, f"{args.model_name}.pth")
+
+    # Log file
+    log_path = os.path.join(args.output_dir,
+                            f"{args.model_name}_LOG_{datetime.now():%Y%m%d_%H%M%S}.txt")
+    log_file = open(log_path, 'w', encoding='utf-8')
+
+    def log(msg):
+        print(msg)
+        log_file.write(msg + '\n')
+        log_file.flush()
+
+    log(f"\nPre-training started: {datetime.now():%Y-%m-%d %H:%M:%S}")
+    log(f"Config: {vars(args)}")
+
+    # Training loop
+    current_min_lines = None
+    current_max_lines = None
+    train_loader = None
+    val_loader = None
+
+    for epoch in range(1, args.num_epochs + 1):
+        start_time = time.time()
+
+        # Curriculum stage management
+        if use_curriculum:
+            new_min, new_max = get_curriculum_stage(epoch, DEFAULT_CURRICULUM)
+
+            if new_min != current_min_lines or new_max != current_max_lines:
+                current_min_lines, current_max_lines = new_min, new_max
+
+                train_filtered = filter_paragraphs_by_lines(
+                    train_categories, current_min_lines, current_max_lines)
+                val_filtered = filter_paragraphs_by_lines(
+                    val_categories, current_min_lines, current_max_lines)
+
+                label = (f"{current_min_lines} line only" if current_min_lines == current_max_lines
+                         else f"{current_min_lines}-{current_max_lines} lines")
+                log(f"\n  Curriculum stage: {label} "
+                    f"(train={len(train_filtered)}, val={len(val_filtered)})")
+
+                train_dataset = KurdishParagraphDataset(
+                    transform=train_transform, filtered_data=train_filtered, **ds_kwargs)
+                val_dataset = KurdishParagraphDataset(
+                    transform=eval_transform, filtered_data=val_filtered, **ds_kwargs)
+
+                train_loader = data.DataLoader(
+                    train_dataset, batch_size=args.batch_size, shuffle=True,
+                    num_workers=0, collate_fn=collate_fn, pin_memory=True)
+                val_loader = data.DataLoader(
+                    val_dataset, batch_size=args.batch_size, shuffle=False,
+                    num_workers=0, collate_fn=collate_fn, pin_memory=True)
+
+                early_stopping.reset()
+        else:
+            if train_loader is None:
+                all_train = [p for ps in train_categories.values() for p in ps]
+                all_val = [p for ps in val_categories.values() for p in ps]
+
+                train_dataset = KurdishParagraphDataset(
+                    transform=train_transform, filtered_data=all_train, **ds_kwargs)
+                val_dataset = KurdishParagraphDataset(
+                    transform=eval_transform, filtered_data=all_val, **ds_kwargs)
+
+                train_loader = data.DataLoader(
+                    train_dataset, batch_size=args.batch_size, shuffle=True,
+                    num_workers=0, collate_fn=collate_fn, pin_memory=True)
+                val_loader = data.DataLoader(
+                    val_dataset, batch_size=args.batch_size, shuffle=False,
+                    num_workers=0, collate_fn=collate_fn, pin_memory=True)
+
+        # Train
+        train_loss = train_epoch(model, train_loader, optimizer, criterion,
+                                 device, scaler, use_mixed_precision, args.grad_clip)
+
+        # Train CER (periodic)
+        train_cer = None
+        if args.cer_every > 0 and epoch % args.cer_every == 0:
+            train_cer = evaluate_cer_batch(model, train_loader, device,
+                                           idx_to_char, args.cer_max_samples)
+
+        # Validation
+        val_loss = evaluate_loss(model, val_loader, criterion, device, use_mixed_precision)
+        val_cer = evaluate_cer_batch(model, val_loader, device, idx_to_char)
+
+        scheduler.step()
+        elapsed = time.time() - start_time
+        mins, secs = divmod(elapsed, 60)
+
+        # Log
+        cer_str = f", Train CER: {train_cer:.4f}" if train_cer is not None else ""
+        log(f"Epoch {epoch}/{args.num_epochs} ({mins:.0f}m {secs:.0f}s) | "
+            f"Train Loss: {train_loss:.4f}{cer_str} | "
+            f"Val Loss: {val_loss:.4f} | Val CER: {val_cer:.4f}")
+
+        # Early stopping and model saving
+        early_stopping(val_cer, model, epoch, best_model_path)
+        if early_stopping.early_stop:
+            break
+
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+    # Final evaluation on full validation set
+    log(f"\nLoading best model for final evaluation...")
+    ckpt = torch.load(best_model_path, map_location=device)
+    model.load_state_dict(ckpt['model_state_dict'])
+
+    all_val = [p for ps in val_categories.values() for p in ps]
+    full_val_dataset = KurdishParagraphDataset(
+        transform=eval_transform, filtered_data=all_val, **ds_kwargs)
+    full_val_loader = data.DataLoader(
+        full_val_dataset, batch_size=args.batch_size, shuffle=False,
+        num_workers=0, collate_fn=collate_fn, pin_memory=True)
+
+    final_cer, final_wer, preds, targets = evaluate_full(
+        model, full_val_loader, device, idx_to_char)
+
+    log(f"\nFinal Validation Results (Full Set, {len(full_val_dataset)} paragraphs):")
+    log(f"  CER: {final_cer:.4f}")
+    log(f"  WER: {final_wer:.4f}")
+
+    log(f"\nSample Predictions:")
+    for i in range(min(3, len(preds))):
+        log(f"\n--- Sample {i + 1} ---")
+        log(f"Predicted: {preds[i][:200]}")
+        log(f"Actual:    {targets[i][:200]}")
+
+    log(f"\nPre-training complete: {datetime.now():%Y-%m-%d %H:%M:%S}")
+    log(f"Best model saved to: {best_model_path}")
+
+    log_file.close()
+    print(f"Log saved to: {log_path}")
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,6 @@
+torch>=2.0.0
+torchvision>=0.15.0
+numpy>=1.21.0
+Pillow>=9.0.0
+tqdm>=4.60.0
+safetensors>=0.3.0