RefLAM

Reference-Grounded Line Annotation for Historical Manuscripts

RefLAM turns manuscript page images and an existing clean reference transcription into validated, line-level OCR training data — without ever bypassing human review. It powers AraMS-28k, a 14-book, 3,043-page dataset of genuine historical Arabic manuscripts with explicit main/margin layout annotation.

📄 Full method, proofs, and evaluation: Reflam paper

---

Why this exists

Line-level HTR training data for historical Arabic manuscripts is either hand-annotated (accurate, but ~40 lines/hour) or produced by OCR-to-reference alignment methods that haven't been extended to multi-script, two-zone (main + margin) manuscript layouts with any correctness guarantee.

RefLAM combines:

• A vision-capable MLLM (Gemini) for zero-shot, layout-tagged OCR of a full page.
• A diacritic-agnostic fuzzy alignment engine that grounds every OCR line in a contiguous span of a pre-existing clean reference transcription.
• The Confidence-100 rule: a maximal alignment score is not a heuristic — it is a provable guarantee of character-for-character normalized-string identity (see docs/confidence_100_proof.md). This is what lets reviewers triage lines instead of transcribing them from scratch.

Measured result: a 75× throughput gain over manual annotation (3,000 vs. 40 lines/hr) on fully page-validated books, with zero human oversight sacrificed — every line, at every confidence level, is still reviewed by a person before release.

---

Pipeline overview

Full stage-by-stage detail (page-anchor detection, greedy windowed alignment, thresholds) is in docs/RefLAM.pdf, Section 3.

---

Repository Structure

reflam/ — pipeline package (segmentation, OCR, normalize, align, confidence)
tools/  — browser-based human review app
docs/   — paper, pipeline overview, proof of the Confidence-100 rule

---

Installation

git clone https://github.com/ArchaText/reflam-pipeline.git
cd reflam-pipeline

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env    # add your GEMINI_API_KEYS

Usage

python reflam/reflam_pipeline.py \
  --gt-file data/ground_truth/book_19.txt \
  --image-dir data/raw/book_19_pages \
  --output-dir data/output/book_19 \

Each page produces:

File	Contents
page_lines.txt	raw Gemini OCR output
page_gt_aligned.txt	aligned reference text per line
alignment.txt	human-readable per-line match report with confidence scores
line_XXX.gemini.txt / line_XXX.gt.txt	per-line pairs
ArMan_8K_dataset.json	full structured dataset for the book

A run-level summary (per-book and global averages, median confidence, drift) is written to alignment_report.txt.

---

The Confidence-100 Rule

Under the indel (LCS-based) similarity ratio used for line alignment, a score of exactly 100 is provably equivalent to character-for-character identity between the normalized OCR line and the normalized reference span — not just "very similar." This is what allows the review tool to treat a 100 score as "verify segmentation only" rather than "re-read the line."

Important: RefLAM does not auto-accept confidence-100 lines. The rule lets a reviewer move fast — it never bypasses inspection.

---

Throughput

Method	Lines / person-hour
Manual baseline (full transcription + bbox)	~40
RefLAM, confidence-100 lines (fast review)	~3,000
Speedup	75×

See docs/RefLAM.pdf, Section 6.1, for the full measurement methodology and the comparison against prior-art throughput estimates.

---

Dataset: AraMS-28k

RefLAM was used to construct AraMS-28k. See the dataset repository for download links, schema, and statistics.

Property	Value
Books	14
Total pages	3,043
Main-text lines	27,969
Margin lines	695
Scripts	Naskh, Ruq'ah, Maghrebi
Margin anchor coverage	~30%
Train / val / test split	9 / 2 / 3 books
License	CC BY-NC-SA 4.0

---

Limitations

• Requires a clean reference transcription to already exist for the target book.
• ~30% of margin lines could not be confidently anchored to a main-text insertion point.
• The line aligner is greedy, not globally optimal.
• Relies on a proprietary MLLM (Gemini); mitigated via response caching and a narrow I/O contract designed to accept an open-source substitute.

---

Citation

If you use AraMS-28k in your research, please cite:

@article{guechaoui2026arams28k,
  title={AraMS-28k: The Largest Publicly Released Line-Level Dataset of Historical Arabic Manuscripts with Margin and Insertion-Anchor Annotations},
  author={Guechaoui, Mohamed and Zellagui, Mohamed Diaa and Chaib, Souleyman and Dhelim, Sahraoui},
  journal={arXiv preprint arXiv:2608.26921},
  year={2026},
  doi={10.48550/arXiv.2608.26921}
}

If you use RefLAM or its annotation pipeline, please also cite:

@article{guechaoui2026reflam,
  title={RefLAM: A Reference-Grounded Line Annotation Pipeline for Historical Arabic Manuscripts},
  author={Guechaoui, Mohamed and Zellagui, Mohamed Diaa and Chaib, Souleyman and Dhelim, Sahraoui},
  journal={arXiv preprint arXiv:2608.25140},
  year={2026},
  doi={10.48550/arXiv.2608.25140}
}

Related papers

• AraMS-28k: https://arxiv.org/abs/2608.26921
• RefLAM: https://arxiv.org/abs/2608.25140

License

Code: MIT. Dataset (AraMS-28k): CC BY-NC-SA 4.0.