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

License

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