AraSpellX

Arabic spelling and OCR error correction with a small character-level transformer trained from scratch.

AraSpellX reads Arabic text, typed by people or produced by OCR, and predicts for every character whether to keep it, delete it, replace it or insert something after it. The AraSpellX package turns these predictions into the corrected text and a list of corrections, each with its position in the input, a calibrated confidence and an error category, so that a pipeline can apply only confident edits, show suggestions or flag words.

Example

Output of this model for a typed sentence:

ذهبت الي الجامعه صباحا لكي احضر المحاضره الاولي، ثم قابلت صديقي في المكتبه.
ذهبت إلى الجامعة صباحا لكي أحضر المحاضرة الأولى، ثم قابلت صديقي في المكتبة.

  الي -> إلى            98%   mixed
  الجامعه -> الجامعة     100%   ta_marbuta
  احضر -> أحضر          94%   hamza_alef
  المحاضره -> المحاضرة   100%   ta_marbuta
  الاولي، -> الأولى،     99%   mixed
  المكتبه. -> المكتبة.   100%   ta_marbuta

On OCR output it corrects what it is sure about and leaves the rest: in تعتبر المدينه من أهم المراكز النجارية في المنطفة، حيث يقصدها الزوار من حميع أنحاء العالم. it fixes المدينه → المدينة and حميع → جميع and leaves the garbled النجارية and المنطفة as they are.

Intended use

• Search and retrieval-augmented generation: clean Arabic text before indexing it, so that misspelled words match their correct forms.
• OCR post-processing of printed Arabic: fix common OCR confusions without risking the text that was read correctly.
• Text review: suggest or flag likely spelling errors using each correction's confidence and position.

Out of scope: grammar (agreement, case endings), punctuation and style, converting dialect to standard spelling, adding or fixing diacritics, handwriting and layout. The target spelling is standard modern Arabic orthography, as in edited publications and Arabic Wikipedia.

How to use

With the AraSpellX package (recommended)

The package normalizes the input, reads long text in overlapping windows, applies the confidence threshold and the editing rules, maps every correction back to the input, and calibrates the confidences.

git clone -b v1 https://github.com/mahmoudalrefaey/AraSpellX.git
cd AraSpellX
uv sync

from araspellx.correct.corrector import Corrector

corrector = Corrector("mahmoudalrefaey/AraSpellX")              # downloads this repository once
result = corrector.correct("ذهبت الي الجامعه", source="typed")    # source="ocr" for OCR output

print(result.text)   # ذهبت إلى الجامعة
for c in result.corrections:
    print(c.start, c.end, c.original, c.replacement, round(c.confidence, 2), c.category)

A local web page for trying the model (right-to-left, nothing leaves the computer):

python -m araspellx.correct.demo --model mahmoudalrefaey/AraSpellX

With transformers only

The model is a standard BertForTokenClassification and predicts one label per character:

import torch
from transformers import AutoModelForTokenClassification, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("mahmoudalrefaey/AraSpellX")
model = AutoModelForTokenClassification.from_pretrained("mahmoudalrefaey/AraSpellX").eval()

text = "ذهبت الي الجامعه"
inputs = tokenizer(text, return_tensors="pt")   # one token per character, plus [CLS] and [SEP]
with torch.no_grad():
    probs = model(**inputs).logits.softmax(-1)[0]
for char, p in zip(text, probs[1:-1]):
    label = model.config.id2label[p.argmax().item()]
    if label != "K":
        print(char, label, round(p.max().item(), 2))   # ا R:إ 0.96 · ي R:ى 0.95 · ه R:ة 0.99

Labels: K keep, D delete, R:x replace with x, and …+s insert s after the character; the [CLS] position carries insertions before the first character. This raw output is not yet a corrected text: use the package, or reproduce its normalization, windowing, threshold and editing rules.

Outputs of the package

How it works

• Normalization: look-alike Persian and Urdu letters are folded into Arabic ones, presentation-form ligatures expanded, letters stored as a base letter plus a combining hamza or madda composed, and tatweel and invisible characters removed. Every character keeps a link to its span in the input.
• Edit labels: one label per character, from the 178 most frequent edits of the training data (99.5% of all edits). Correct text stays correct by default, and every change is an explicit decision with a probability.
• Editing rules: only Arabic letters, diacritics, tatweel and spaces are edited. Digits, Latin text, symbols and existing punctuation are never changed; a letter that OCR made of a punctuation mark may be turned back into it. Spacing next to punctuation follows Arabic typography.
• Threshold and calibration: an edit is applied only above a confidence of 0.9, chosen on development data to keep damage on clean text within 0.05%. calibration.json maps raw confidences to observed accuracy, with one fit for typed and one for OCR input.

Training data

All training and test data are public. Training text is filtered against every test set (any paragraph sharing an 8-word passage with a test text is dropped), and test pages are held out by a hash of their page id.

Training procedure

During both stages each attention head's largest score is capped at 50 by scaling its query; this prevents a runaway head that collapsed an earlier pretraining run, and leaves the saved model a standard BERT.

Evaluation

Measured on frozen test sets of real text at the threshold of 0.9:

T-1 is scored on the words the editors fixed, because a single Wikipedia edit leaves a paragraph's other errors in place; strict precision against such references counts the model's fixes of those errors as damage. References in general contain spelling errors, so some edits counted as harmful are fixes of the reference itself. Full method and per-set results: evaluation.

Limitations

• OCR recall is low. On real scans the model rarely makes a page worse, but it removes only 13% of word errors (the project's target is 20%): most OCR errors are badly garbled words, and it fixes about 1 in 10 of them.
• Errors that produce another valid word need meaning rather than spelling, which a 15M-parameter character model knows little about.
• Quranic text and accepted spelling variants are not protected: verses are corrected like any other text, and either form of a word with two accepted spellings (مسؤول/مسئول) may be changed.
• Dialect and diacritized text are left alone, not corrected.
• The training text is encyclopedic (Wikipedia) and classical (Wikisource); informal registers such as social media were not evaluated.

Files

License and attribution

The model and the code are released under the MIT License. The training text comes from Wikimedia projects (CC BY-SA) and from the Yarmouk Arabic OCR Dataset (Abu Doush, AlKhateeb and Gharibeh, CSIT 2018, doi:10.1109/CSIT.2018.8486162); test data also include NOD (CC BY 4.0) and the OpenITI OCR gold standard (CC BY-NC-SA 4.0, evaluation only). OCR training pairs were produced with Tesseract (Apache-2.0). The project started from AraSpell (Salhab and Abu-Khzam); the edit-label approach follows GECToR and Alhafni and Habash's Arabic text editing.

Citation

@software{alrefaey2026araspellx,
  author = {Al-Refaey, Mahmoud},
  title  = {{AraSpellX}: Arabic Spelling and {OCR} Error Correction with a Character-Level Transformer},
  year   = {2026},
  url    = {https://huggingface.co/mahmoudalrefaey/AraSpellX}
}