🖋️ HandScribe OCR

Production-grade multilingual handwritten OCR for student notes

What is HandScribe?

HandScribe extracts text from handwritten student notes in 80+ languages. It wraps three OCR engines — EasyOCR, PaddleOCR, and TrOCR — behind a single interface with advanced image preprocessing, a CLI, a REST API, and one-command Docker deployment.

Built for Tanzanian students. Designed for everyone.

Quick Start

Usage

CLI

handscribe extract notes.jpg -b easyocr -l en,sw     # extract text
handscribe extract notes.jpg --json                   # output as JSON
handscribe extract notes.jpg -o output.txt -c 0.6     # save to file
handscribe batch ./images/ -o ./results/               # batch process
handscribe compare notes.jpg -l en,sw                  # compare all backends

REST API

uvicorn ocr_engine.api:api --port 8000
# Interactive docs → http://localhost:8000/docs

curl -X POST http://localhost:8000/ocr \
  -F "file=@notes.jpg" -F "backend=easyocr" -F "languages=en,sw"

Python

from ocr_engine import OCREngine, OCRBackend

engine = OCREngine(backend=OCRBackend.EASYOCR, languages=["en", "sw"])
text = engine.extract_text("student_notes.jpg")

OCR Backends

*TrOCR can be fine-tuned for other languages.

Language Codes

CI/CD Pipeline

HandScribe uses two separate GitHub Actions workflows:

How It Works

push / PR
   │
   ├── lint ─── ruff ─ black ─ mypy
   │
   └── test ─── pytest (41 tests, 60% coverage)
         │
         └── on main ── build & push Docker image to Docker Hub


push tag v0.1.0
   │
   └── publish ─── build ─── twine check ─── upload to PyPI

Status Badges

Badge	Status
CI Build
PyPI Publish

Publishing a Release

# 1. Bump version in pyproject.toml
# 2. Tag and push
git tag v0.1.0
git push origin v0.1.0

# → GitHub Actions auto-publishes to PyPI

Docker

docker run -p 8000:8000 ronaldgosso/handscribe        # run
docker build -t handscribe .                           # build
docker compose up -d                                   # compose

Full instructions in CONTRIBUTING.md.

Architecture

handscribe/
├── ocr_engine/
│   ├── engine.py            # Core OCR engine (3 backends)
│   ├── preprocessing.py     # Denoise, CLAHE, binarize, deskew
│   ├── cli.py               # CLI (Typer) — extract, batch, compare, info
│   └── api.py               # REST API (FastAPI) — /ocr, /ocr/text, /ocr/batch
├── tests/
│   └── test_engine.py       # 41 tests
├── .github/workflows/
│   ├── ci.yml               # Lint → Test → Docker
│   └── publish.yml          # Build → PyPI
├── Dockerfile               # Optimized single-stage build
├── docker-compose.yml
└── pyproject.toml

🔧 Add Other OCR Backends

EasyOCR is included by default. Add PaddleOCR or TrOCR as optional extras:

pip install handscribe[paddle]    # PaddleOCR — faster, document-style
pip install handscribe[trocr]     # TrOCR — highest handwriting accuracy
pip install handscribe[all]       # Both PaddleOCR + TrOCR

from ocr_engine import OCREngine, OCRBackend

# Switch backend at runtime
engine = OCREngine(backend=OCRBackend.PADDLE, languages=["en"])
engine = OCREngine(backend=OCRBackend.TROCR)

🧪 Development

git clone https://github.com/ronaldgosso/handscribe.git
cd handscribe
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[all,dev]"
pytest tests/ -v

Full guide → CONTRIBUTING.md

Acknowledgments

• EasyOCR — Jaided AI
• PaddleOCR — PaddlePaddle
• TrOCR — Microsoft
• Tanzanian Students — the inspiration

Ronald Gosso — ronaldgosso@gmail.com · GitHub

Made with ❤️ for students everywhere