Create README.md

README.md

@@ -0,0 +1,90 @@
+---
+license: mit
+language:
+- ar
+- aeb
+pipeline_tag: image-to-text
+base_model: microsoft/trocr-base-handwritten
+tags:
+- image-to-text
+- ocr
+- handwriting-recognition
+- htr
+- arabic
+- tunisian
+- trocr
+- vision-encoder-decoder
+- offline
+---
+
+# trocr-tunisian-arabic — handwritten Tunisian Arabic recognition
+
+A TrOCR vision-encoder/decoder fine-tuned for **handwritten Tunisian Arabic**, with a 30k-token Arabic-native vocabulary.
+
+## Why this exists
+
+Cloud OCR services handle printed Arabic reasonably and handwritten dialectal Arabic poorly. For the use case this was built for, they were not an option at all: Tunisian legal documents contain privileged client data that cannot leave the premises under the country's data-protection regime. That ruled out every managed service and required a model that runs fully offline.
+
+## Intended use
+
+Offline extraction of handwritten Arabic from structured forms.
+
+Built for and deployed in [Wathiqa](https://github.com/GhwazouaniWala/Wathiqa), which turns handwritten Tunisian legal forms into structured, searchable client records without any cloud dependency.
+
+**This is a word-level model.** In Wathiqa it sits behind a segmentation stage: the ink mask is dilated horizontally by a kernel scaled to text height — Arabic joins letters within a word but not between words, so inter-word gaps are the reliable separator — and the resulting components are read right to left. Feeding a full unsegmented line will not work well.
+
+## Usage
+
+<!-- Paste the VisionEncoderDecoderModel loading and generation code you have
+     actually run, including the processor and any generation config used. -->
+
+## Where it sits in a real pipeline
+
+Wathiqa routes each field type to a purpose-built engine rather than asking one model to cover everything:
+
+| Field type | Engine |
+|---|---|
+| Arabic text, names, notes | **This model** |
+| CIN, passport, number, phone, date | Dedicated digit recogniser with a constrained alphabet and shape validation |
+| Printed captions | EasyOCR (Arabic + Latin) |
+| Checkboxes | Fill-ratio detector |
+| Signatures | Ink-presence detector |
+
+That routing exists because these are genuinely different problems, and the limitations below are the reason.
+
+## Limitations
+
+- **Trained on isolated words**, not lines or sentences. Word segmentation is the caller's responsibility.
+- **Not for digits.** Numeric fields need a separate path — a word model asked for a digit string produces confident nonsense. Wathiqa isolates characters, constrains the alphabet to `0-9` and separators, then validates the assembled value against the field's expected shape.
+- **Not for printed text.** Printed captions are a different problem and route elsewhere.
+- **A blank crop returns confident nonsense rather than silence.** Empty-field detection must happen before the model is called; Wathiqa reports fields with no ink as empty and never sends them to a model.
+- Trained on Tunisian handwriting. Performance on other regional Arabic hands is untested.
+
+## Training
+
+Fine-tuned from [`microsoft/trocr-base-handwritten`](https://huggingface.co/microsoft/trocr-base-handwritten) on handwritten Tunisian Arabic, with the decoder vocabulary replaced by a 30k-token Arabic-native vocabulary.
+
+<!-- Optional but worth adding: number of training samples, how the corpus was
+     collected and labelled, image preprocessing, and CER/WER on a held-out set. -->
+
+## Related work
+
+| Model | Purpose |
+|---|---|
+| [`Ghazouaniwala/emotions_speech`](https://huggingface.co/Ghazouaniwala/emotions_speech) | Speaker-independent speech emotion recognition |
+| [`Ghazouaniwala/silma-tts-derja`](https://huggingface.co/Ghazouaniwala/silma-tts-derja) | Tunisian Derja speech synthesis |
+
+## Citation
+
+```bibtex
+@misc{ghazouani2025trocrtunisian,
+  author = {Ghazouani, Wala Eddine},
+  title  = {trocr-tunisian-arabic: handwritten Tunisian Arabic recognition},
+  year   = {2025},
+  url    = {https://huggingface.co/Ghazouaniwala/trocr-tunisian-arabic}
+}
+```
+
+---
+
+Built by [Wala Eddine Ghazouani](https://www.walaghazouani.com) · [GitHub](https://github.com/GhwazouaniWala) · [LinkedIn](https://www.linkedin.com/in/ghazouani-wala-eddine)