Mashkul (مشكول) — Arabic Text Diacritization
Mashkul automatically restores Arabic diacritics (تشكيل / حركات) to undiacritized text, using a lightweight character-level BiGRU model.
Input: كان العرب يحبون العلم ويقدرون العلماء
Output: كَانَ الْعَرَبُ يُحِبُّونَ الْعِلْمَ وَيُقَدِّرُونَ الْعُلَمَاءَ
- 🔗 Code & full project: github.com/ahmedmgelwan/Mashkul
- 📦 Model size: ~1.7 MB
Model Description
Mashkul treats diacritization as a character-level sequence tagging problem: each Arabic letter is classified into one of the possible diacritic marks (or "no diacritic"), using a Bidirectional GRU over a window of characters.
- Architecture: Embedding → 2-layer Bidirectional GRU → Linear classification head
- Framework: PyTorch
- Vocabulary: built dynamically from the training corpus (character-level, not subword)
Intended Uses & Limitations
Intended uses:
- Adding diacritics to Modern Standard Arabic (MSA) text for education, TTS preprocessing, or readability tools.
Limitations:
- Trained on the Tashkeela corpus, which is mostly classical/religious prose — accuracy is noticeably lower on out-of-domain text such as classical poetry.
- Case-ending diacritics (الإعراب, the last letter of each word) are the most common source of errors, since they can depend on grammatical context the model doesn't fully capture.
- Not trained on dialectal Arabic.
How to Use
The model isn't wrapped in the transformers library, so you'll need the
inference code from the GitHub repo above.
git clone https://github.com/ahmedmgelwan/Mashkul.git
cd Mashkul
pip install -r requirements.txt
from huggingface_hub import hf_hub_download
from src.infer import Diacritizer
model_path = hf_hub_download("ahmedmgelwan/Mashkul", "model.pt")
tokenizer_path = hf_hub_download("ahmedmgelwan/Mashkul", "tokenizer.json")
diacritizer = Diacritizer.from_pretrained(model_path, tokenizer_path, device="cpu")
print(diacritizer.diacritize("كان العرب يحبون العلم ويقدرون العلماء"))
Training Data
Trained on arbml/tashkeela, a large corpus of fully diacritized classical Arabic text (~50K training sentences used, split into fixed-length character windows).
Evaluation Results
Evaluated on a held-out test split from the same dataset:
| Metric | Value |
|---|---|
| Character Accuracy | 96.33% |
| Word Error Rate (WER) | 13.97% |
| Diacritic Error Rate (DER) | 3.67% |
| Diacritic Error Rate — excluding last letter | 3.39% |
| Sentence Exact Match | 9.58% |
Author
Built by Ahmed Gelwan as a learning project in Arabic NLP and deep learning.