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.