I'rāb-guided Arabic diacritization — explainable multi-task NLP that predicts diacritics, grammatical role, and orthographic errors jointly.
Python
0
84 commits
updated May 7, 2026
An explainable Arabic NLP system that jointly predicts:
ذهب → ذَهَبَذهب → verb, past tense, indeclinableالى → إلىUnlike pure neural diacritizers (CATT, Sadeed, CAMeL-BERT), this system attaches a grammatical justification to every diacritic it predicts. The i'rāb head acts both as an auxiliary training signal (regularizing the encoder) and as an interpretability layer (exposing the model's syntactic reasoning).
# Clone + install
git clone <repo-url> irab-tashkeel
cd irab-tashkeel
pip install -e ".[dev]"
# Download corpora
python scripts/download_data.py --all
# Train a small dev model (~5M params, CPU-friendly)
python -m irab_tashkeel.training.cli --config configs/model_small.yaml
# Train the production model (60M params, requires GPU)
python -m irab_tashkeel.training.cli --config configs/model_medium.yaml
# Evaluate
python -m irab_tashkeel.evaluation.eval_cli --checkpoint runs/medium/best.pt
# Run the Streamlit demo
export MODEL_CKPT=runs/medium/best.pt
streamlit run app/app.py
| Directory | Purpose |
|---|---|
src/irab_tashkeel/ | Python package — data, models, training, inference, rules |
configs/ | YAML model/training configs (small / medium / large) |
scripts/ | Command-line utilities (download data, upload to HF Hub) |
tests/ | Unit tests — run with pytest |
docs/ | Architecture, data, training, evaluation, deployment docs |
app/ | Streamlit demo (deploys to HF Spaces) |
notebooks/ | Jupyter notebooks for exploration and error analysis |
A character-level transformer encoder shared across three task heads:
Trained jointly on Tashkeela (~75M words, diacritics only) + QAC (78K words, diacritics + i'rāb) + I3rab Treebank (600 MSA sentences, i'rāb only) + synthetic error injections. Weighted multi-task loss with per-sample masking so each example only contributes to the heads for which it has labels.
For the full story see docs/ARCHITECTURE.md.
If you're using Claude Code to develop this project, start by reading:
docs/DEVELOPMENT.md — which modules do whatdocs/ARCHITECTURE.md — the model designdocs/DATA.md — the corpora and schemasCommon tasks:
src/irab_tashkeel/data/synthetic.py + update ERR_LABELS in src/irab_tashkeel/models/labels.pysrc/irab_tashkeel/rules/grammar.py — each rule is a methodsrc/irab_tashkeel/evaluation/metrics.pyapp/app.pyBuilt on research contributions from:
MIT. See LICENSE.
I'rāb-guided Arabic diacritization — explainable multi-task NLP that predicts diacritics, grammatical role, and orthographic errors jointly.
Python
0
84 commits
updated May 7, 2026
An explainable Arabic NLP system that jointly predicts:
ذهب → ذَهَبَذهب → verb, past tense, indeclinableالى → إلىUnlike pure neural diacritizers (CATT, Sadeed, CAMeL-BERT), this system attaches a grammatical justification to every diacritic it predicts. The i'rāb head acts both as an auxiliary training signal (regularizing the encoder) and as an interpretability layer (exposing the model's syntactic reasoning).
# Clone + install
git clone <repo-url> irab-tashkeel
cd irab-tashkeel
pip install -e ".[dev]"
# Download corpora
python scripts/download_data.py --all
# Train a small dev model (~5M params, CPU-friendly)
python -m irab_tashkeel.training.cli --config configs/model_small.yaml
# Train the production model (60M params, requires GPU)
python -m irab_tashkeel.training.cli --config configs/model_medium.yaml
# Evaluate
python -m irab_tashkeel.evaluation.eval_cli --checkpoint runs/medium/best.pt
# Run the Streamlit demo
export MODEL_CKPT=runs/medium/best.pt
streamlit run app/app.py
| Directory | Purpose |
|---|---|
src/irab_tashkeel/ | Python package — data, models, training, inference, rules |
configs/ | YAML model/training configs (small / medium / large) |
scripts/ | Command-line utilities (download data, upload to HF Hub) |
tests/ | Unit tests — run with pytest |
docs/ | Architecture, data, training, evaluation, deployment docs |
app/ | Streamlit demo (deploys to HF Spaces) |
notebooks/ | Jupyter notebooks for exploration and error analysis |
A character-level transformer encoder shared across three task heads:
Trained jointly on Tashkeela (~75M words, diacritics only) + QAC (78K words, diacritics + i'rāb) + I3rab Treebank (600 MSA sentences, i'rāb only) + synthetic error injections. Weighted multi-task loss with per-sample masking so each example only contributes to the heads for which it has labels.
For the full story see docs/ARCHITECTURE.md.
If you're using Claude Code to develop this project, start by reading:
docs/DEVELOPMENT.md — which modules do whatdocs/ARCHITECTURE.md — the model designdocs/DATA.md — the corpora and schemasCommon tasks:
src/irab_tashkeel/data/synthetic.py + update ERR_LABELS in src/irab_tashkeel/models/labels.pysrc/irab_tashkeel/rules/grammar.py — each rule is a methodsrc/irab_tashkeel/evaluation/metrics.pyapp/app.pyBuilt on research contributions from:
MIT. See LICENSE.