kenny0bi/ami-yoruba-diacritics

ami: Yoruba diacritic restoration

àmì is Yoruba for "mark". This model puts the marks back.

Written Yoruba depends on diacritics: the dotted letters ẹ, ọ, ṣ are different letters, and the tone marks distinguish words that are otherwise spelled the same (oko farm, ọkọ husband, ọkọ̀ vehicle). Most Yoruba text typed on phones and keyboards drops them. This model restores them, character by character, with a 1.29M-parameter BiLSTM that runs comfortably on a CPU, because a tool for restoring text messages should not need a GPU.

Results

Evaluated on the MENYO-20k test split (Adelani et al. 2021), the professionally translated and diacritized benchmark, never touched during training or model selection:

system	char accuracy	word accuracy	ambiguous-word accuracy
leave text unmarked	0.392	0.155	0.122
word lookup (most frequent form)	0.771	0.692	0.786
ami (this model)	0.924	0.860	0.882

Char accuracy is scored only on positions that can legally carry marks, so the model gets no credit for copying consonants. Ambiguous words are those whose stripped form has more than one attested diacritization in training, which is 129,512 of the 149,693 test words: the cases a lookup table cannot decide.

Throughput on a 2014 4-core laptop CPU: about 9,643 characters per second.

Using it

from huggingface_hub import snapshot_download
import sys
path = snapshot_download("kenny0bi/ami-yoruba-diacritics")
sys.path.insert(0, path)
from restore import load_restorer

restorer = load_restorer(path)
print(restorer.restore("bawo ni oko re se n lo"))

The model only ever changes the marks. Base letters, punctuation, numbers and anything non-Yoruba pass through untouched, and combinations that are impossible in Yoruba orthography (a dot on a, a tone on ṣ) are masked out of the softmax, so the model is structurally unable to produce them.

Model details

• character BiLSTM tagger, 1.29M parameters (embedding 64, hidden 192, 2 layers), six output classes per character: plain, grave, acute, dot, dot+grave, dot+acute
• trained on 200,000 lines: the Yoruba side of the MENYO-20k training split plus the diacritized portion of the Yorùbá Text C3 corpus (Alabi et al. 2020), filtered to lines with genuine diacritic density and de-duplicated against the evaluation splits on stripped text
• 3 epochs, 5907s of training on a 2014 laptop CPU
• licence follows the data: CC BY-NC 4.0

Where the marks matter, measured

Knowing only the base letter, a mark costs 1.64 bits per restorable character to guess; e and o are hardest at about 2.5 bits each, because they can take all six classes. Knowing the whole word cuts the residue to 0.61 bits per word. That remainder is what sentence context has to resolve, and it is exactly where this model beats the lookup table.

Limits

• Trained on published prose (news, religious text, Wikipedia-adjacent sources). Informal SMS-style Yoruba, heavy code-switching with English, and dialectal spellings are underrepresented.
• The model restores standard Yoruba orthography and will normalise toward it; it is not a transcription of how any individual speaks.
• Proper names it has never seen get the most probable marking, which may be wrong; names are the hardest case for any restorer.

Training code, evaluation, and the full honest-limits discussion: github.com/Kenny0bi/ami

ONNX exports

The onnx/ folder carries the same model exported for serving (see the gbe project for the pipeline and proofs): model.onnx (fp32, byte-identical restorations to this checkpoint on all 6,573 test sentences) and model.int8.onnx (dynamic INT8, 1.3 MB, ties fp32 at 92.39% vs 92.38% character accuracy on the full test set). The int8 file is what runs in the browser demo at kenny0bi/yoruba-diacritics.