README.md

---

language:
  - ckb
license: cc-by-nc-4.0
tags:
  - handwritten-text-recognition
  - kurdish
  - sorani
  - crnn
  - frequency-adaptive-attention
  - ctc
  - pytorch
  - safetensors
datasets:
  - DASTNUS
metrics:
  - cer
  - wer
pipeline_tag: image-to-text
---


# KHWR: Kurdish Handwritten Word Recognition

This repository hosts the trained models and inference code accompanying the
study on Kurdish handwritten word recognition with the proposed
**Frequency-Adaptive Attention (FAA)** mechanism, evaluated on the **DASTNUS

Unique Words** subset against three competitive attention baselines under a
controlled multi-seed protocol.

The repository includes four base architectures (Baseline, Luong, MHSA, and
the proposed FAA).

## Repository Structure

```

KHWR/

├── FAA-Word-Model/                  # Proposed FAA (seed 42)

│   ├── model.safetensors

│   ├── config.json

│   ├── vocab.json

│   ├── idx_to_char.json

│   └── README.md

├── Baseline-Word-Model/             # CRNN without attention (seed 42)

├── Luong-Word-Model/                # Luong multiplicative attention (seed 42)

├── MHSA-Word-Model/                 # Multi-Head Self-Attention (seed 42)

├── Scripts/

│   ├── train.py

│   └── inference.py

├── Sample/

│   ├── sample_word.tif

│   └── sample_word.txt

├── requirements.txt

└── README.md

```

## Architecture

All four model families share an identical CNN and BiLSTM backbone and differ
only in the attention block placed between BiLSTM layers 2 and 3, which
isolates the contribution of each attention design.

| Model | Attention Block | Parameters |
|-------|------------------|:----------:|
| Baseline | none | 3,838,065 |
| Luong | multiplicative attention | 3,915,345 |
| MHSA | Multi-Head Self-Attention (4 heads, ff = 320) | 4,044,625 |
| **FAA (proposed)** | **Frequency-Adaptive Attention** | **3,997,859** |

Shared backbone:
- CNN: 6 convolutional blocks, maximum 256 channels
- RNN: 3 BiLSTM layers, hidden size 160 per direction
- Decoder: Connectionist Temporal Classification (CTC)
- Input resolution: 64 × 164 grayscale
- Vocabulary size: 113 (CTC blank + 112 Kurdish characters and symbols)

## Performance

### Multi-Seed Evaluation on DASTNUS Unique Words

Test set of 8,036 word images, five random seeds (42, 7, 123, 456, 789):

| Model | Mean CER ± Std | Mean WER ± Std |
|-------|:-:|:-:|
| Baseline | 0.0374 ± 0.0009 | 0.1525 ± 0.0037 |
| Luong | 0.0381 ± 0.0009 | 0.1612 ± 0.0040 |
| MHSA | 0.0403 ± 0.0023 | 0.1709 ± 0.0079 |
| **FAA (proposed)** | **0.0358 ± 0.0013** | **0.1426 ± 0.0044** |

### Few-Shot Cross-Domain Adaptation

FAA seed-42 checkpoint adapted to three additional DASTNUS subsets:

| Budget | Person Names CER | Place Names CER | Month Names CER |
|:-:|:-:|:-:|:-:|
| 0% (zero-shot) | 0.1448 | 0.2691 | 0.2043 |
| 5% | 0.1264 | 0.1856 | 0.0157 |
| 100% | **0.0380** | **0.0268** | **0.0087** |

## Installation

```bash

git clone https://huggingface.co/Karez/KHWR

cd KHWR

pip install -r requirements.txt

```

## Quick Start

### Inference

The inference script automatically detects the model family from the
`config.json` next to the chosen `model.safetensors`, so a single command
works for any of the seven model folders in this repository.

```bash

# Single image

python Scripts/inference.py \

    --image Sample/sample_word.tif \

    --model_path FAA-Word-Model/model.safetensors \

    --vocab_path FAA-Word-Model/vocab.json



# Directory of images, save predictions to TSV

python Scripts/inference.py \

    --image_dir ./test_words \

    --model_path FAA-Word-Model/model.safetensors \

    --vocab_path FAA-Word-Model/vocab.json \

    --output_file predictions.tsv

```

### Training

The training script handles all four model families via the `--model_type`
flag, sharing the identical backbone and hyperparameters used in the paper.

```bash

# Train the proposed FAA model

python Scripts/train.py \

    --model_type faa \

    --data_dir ./data/DASTNUS/Unique-Words \

    --vocab_path FAA-Word-Model/vocab.json \

    --output_dir ./output/faa_seed42 \

    --seed 42



# Train one of the baselines (replace faa with baseline / luong / mhsa)

python Scripts/train.py \

    --model_type mhsa \

    --data_dir ./data/DASTNUS/Unique-Words \

    --vocab_path FAA-Word-Model/vocab.json \

    --output_dir ./output/mhsa_seed42 \

    --seed 42

```

### Few-Shot Fine-Tuning

Initialize from the seed-42 FAA checkpoint, then fine-tune on a target subset
with a smaller learning rate and a shorter schedule:

```bash

python Scripts/train.py \

    --model_type faa \

    --data_dir ./data/DASTNUS/Person-Names \

    --vocab_path FAA-Word-Model/vocab.json \

    --init_checkpoint FAA-Word-Model/best_model.pth \

    --learning_rate 1e-4 \

    --num_epochs 30 \

    --patience 5 \

    --output_dir ./output/faa_person_finetune

```

## Models

| Folder | Architecture | Test CER | Test WER |
|--------|--------------|:-:|:-:|
| `FAA-Word-Model/` | CRNN + Frequency-Adaptive Attention | 0.0373 | 0.1480 |
| `Baseline-Word-Model/` | CRNN (no attention) | 0.0380 | 0.1544 |
| `Luong-Word-Model/` | CRNN + Luong attention | 0.0391 | 0.1663 |
| `MHSA-Word-Model/` | CRNN + Multi-Head Self-Attention | 0.0383 | 0.1655 |

All values reported on the held-out test split of the corresponding subset
under greedy CTC decoding, seed 42.

## Dataset

The models in this repository are trained on the DASTNUS Kurdish handwritten
text dataset. Relevant statistics:

| Subset | Samples | Unique Words | Vocabulary |
|--------|:-:|:-:|:-:|
| Unique Words | 54,191 | 2,750 | 21,796 (full DASTNUS) |

## Citation

```bibtex



```

## License

Released under the CC BY-NC 4.0 license. The models and dataset are intended
for non-commercial scientific research only.