mawshor

Arabic OCR pipeline powered by OnnxTR with fine-tuned ONNX models.

Sample Input Image

Model Prediction Output (cropped for space)

Features

• Arabic document STR: detection and recognition models fine-tuned on Arabic script for document STR tasks (images taken by phone cameras) and scanned documents.
• Orientation correction: detects and corrects both page-level rotation and crop-level skew before inference (--straighten-pages)
• LLM postprocessing: low-confidence OCR words are sent to any OpenAI-compatible LLM for context-aware correction (--postprocess)
• GPU-accelerated: runs on CUDA via ONNX Runtime; CPU fallback available

Models

Four fine-turned Arabic models are loaded from HuggingFace (madskills/):

Models were fine-tuned on synthetic Arabic datasets using DocTR models as a base.

Installation

• Python 3.10+
• CUDA-capable GPU (CPU fallback available but not the primary target)

pip install mawshor            # CPU
pip install "mawshor[gpu]"     # CUDA

Usage

CLI

mawshor <path> [options]

<path> can be a single image/PDF or a directory. Supported image formats: PNG, JPG, JPEG, BMP, TIFF.

# Basic OCR on a single image
mawshor document.jpg

# OCR a directory and save results
mawshor ./scans/ --save

# OCR with page straightening and LLM postprocessing via local Ollama
mawshor document.jpg --straighten-pages --postprocess

# Use a different model or remote endpoint
mawshor document.jpg --postprocess \
  --llm-endpoint https://api.openai.com/v1 \
  --llm-model gpt-4o \
  --llm-api-key sk-...

Python API

import mawshor

# One-shot
results = mawshor.ocr("document.jpg")
print(results[0].text)

# With orientation correction and LLM postprocessing
results = mawshor.ocr("document.jpg", straighten_pages=True, postprocess=True)

# Reuse the predictor across multiple documents (avoids reloading models)
predictor = mawshor.load_predictor(straighten_pages=True)
results = mawshor.ocr("./scans/", predictor=predictor)
for r in results:
    print(r.source, r.text)

Postprocessing

When --postprocess is enabled, OCR output is filtered by confidence and sent to an LLM:

• Words with confidence ≥ 0.8 are passed as-is
• Words with confidence between 0.75–0.8 are passed and flagged as low-confidence
• Words with confidence < 0.75 are dropped before sending

The LLM is prompted as an Arabic copyeditor to fix likely OCR errors, merge/split words, and clean up spacing — without changing meaning or adding content.

Any OpenAI-compatible endpoint works. Ollama runs out of the box with the defaults.