ichkil — Arabic Tashkeel for Python

Vocalize bare Arabic text with a tiny, self-contained ONNX model (≈5 MB, CPU-only, no GPU, no tokenizer, no server). One call, fully offline after the first run.

ichkil downloads its model from Hugging Face on first use, verifies its SHA-256, and runs inference with ONNX Runtime. After that it is 100 % offline.

import ichkil

ichkil.diacritize("محمد قرأ الكتاب في المدرسة")
# -> 'مُحَمَّدٌ قَرَأَ الْكِتَابَ فِي الْمَدْرَسَةِ'

Install

pip install ichkil

Requires Python ≥ 3.9 (tested on 3.9 – 3.12). Dependencies: huggingface_hub, onnxruntime (CPU).

Quickstart

import ichkil

# one-liner (lazy model download on first call, then cached)
ichkil.diacritize("العلم نور والجهل ظلمة")
# -> 'الْعِلْمِ نُورٌ وَالْجَهْلُ ظُلْمَةُ'

# explicit control
from ichkil import Diacritizer

d = Diacritizer()                      # downloads + verifies + caches the model
d.diacritize("القهوة جميلة في الصباح")
# -> 'الْقَهْوَةِ جَمِيلَةٌ فِي الصَّبَاحِ'

labels = d.predict_labels("كتاب")      # [4, 2, 1, 4]  (one label id per character, 0..12)

# fully offline: point at local files
d = Diacritizer.from_file("./model.onnx")

Command line

pip install ichkil
ichkil "محمد قرأ الكتاب"
# مُحَمَّدٌ قَرَأَ الْكِتَابَ

ichkil --json "العلم نور"
# {"input": "العلم نور", "output": "الْعِلْمِ نُورٌ"}

cat text.txt | ichkil                  # read from stdin
ichkil --model ./model.onnx "محمد"    # offline mode

API

Label contract

The model predicts exactly one label per input character:

Already-vocalized input is stripped first, so diacritize is idempotent. Non-Arabic characters (Latin letters, digits, punctuation, spaces) pass through unchanged.

Model provenance

• Repository: ichkil/ichkil (model.onnx, config.json, SHA256SUMS)
• SHA-256 of model.onnx: 9055816b214346b0a8044a4a8deceb36e818dffd0b04699715ea23883bf54744
• Contract: input_ids int64 [batch, seq] → logits float32 [batch, seq, 13]; sequence length fully dynamic (up to max_seq_len = 1024 in the golden contract)
• Quality: DER 2.80 % on the reference evaluation set; ONNX output is bit-identical to the PyTorch reference (equivalence verified)
• The cross-runtime golden vectors shipped in tests/golden.json are a verbatim copy of the core repository's golden/vectors.json

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                                   # pure pipeline tests (no network)
pytest -m integration                     # + model tests (downloads once, ~5 MB)
ruff check . && ruff format --check .    # lint

Publishing

v* tags are built and published to PyPI via GitHub trusted publishing (OIDC) — no API token is stored anywhere. One-time setup on pypi.org/project/ichkil: Project settings → Publishing → Add a publisher with github.com/Ichkil/ichkil-python, workflow: publish.yml.

Sibling libraries

• ichkil-js — npm package (Node.js + browser)
• ichkil-go — Go module
• Core repo — training, evaluation, model spec, golden vectors

License

MIT © 2026 Maaouia BenHamed