# 📝 NEW REPORT OUTLINE: Rakīm AI (رَقِيم)

This outline serves as a blueprint for rewriting the official paper/report for the national competition, aligning it with the verified codebase implementation and removing all outdated technical assumptions.

---

## 1. Abstract
* **Focus:** High-level summary of Rakīm AI.
* **Content:** Describe the problem of historical Arabic (Maghrebi) manuscript digitization, the proposed tiered pipeline (segmentation + recognition), dynamic routing based on layout analysis, local offline character-level language models, and semantic post-OCR enrichment. State the final achieved metrics: **7.50% CER** on unseen pages and catalog integration of **~50,000 manuscript copies**.

---

## 2. Problem Statement
* **Focus:** Digital isolation of historical Arabic cultural heritage.
* **Content:**
  * **Linguistic & Calligraphic Barriers:** Standard commercial OCR engines are trained on modern printed fonts and fail completely when confronted with historical handwritten scripts (e.g., Maghrebi calligraphic hands).
  * **Structural Complexity:** Historical manuscripts contain crowded layouts, marginal notes (*marginalia* / *hashiya*), page damage, and ink bleed-through.
  * **Computational Cost:** High resource demands of deep learning architectures in academic environments.

---

## 3. Objectives
* **Focus:** Engineering a scalable, local-first manuscript processing suite.
* **Content:**
  * Build a pipeline that transitions from raw images to editable, search-indexed Arabic texts.
  * Develop a dynamic layout router to select optimal model pairs.
  * Integrate offline post-OCR language correction to reduce Character Error Rates (CER).
  * Deploy semantic features (summarization, indexing, dictionary lookup) and collection matching.

---

## 4. System Architecture
* **Focus:** Detailed breakdown of the processing pipeline.
* **Content:**
  * **Preprocessing & Binarization:** Deskewing and Sauvola-based local adaptive thresholding (`nlbin`).
  * **Dynamic Layout Routing:** Heuristic evaluation of image layout (framed vs. dense vs. open) to select corresponding models.
  * **Neural Line Segmentation:** Extraction of baseline polygons using BLLA (Baseline Layout Analysis) networks.
  * **Region Classification:** Separating main text body (*matn*) from margins (*hashiya*) using positional boundaries.
  * **Neural Text Recognition:** Sequence recognition using PyTorch-based convolutional-recurrent networks (CRNN).
  * **Language Model Shallow Fusion:** offline character-level n-gram beam search decoding.
  * **Performance Layer:** SQLite cash-database, FP16 half-precision, and direct multi-worker deployments.

---

## 5. Dataset and Model Training
* **Focus:** Fine-tuning methodologies and datasets.
* **Content:**
  * **Datasets:** Use of the RASAM Maghrebi dataset and TariMa historical dataset.
  * **Training Strategy:** Moving away from standard generic printed baselines (`reg(96.5)`) via low-learning-rate fine-tuning (`lrate 0.0001`) with learning rate warmup and backbones freezing.
  * **Data Replay:** Balanced line-level (not page-level) replay training to prevent catastrophic forgetting.

---

## 6. Model Routing
* **Focus:** Layout-aware model selection.
* **Content:**
  * **Framed Layout Classifier:** Hough-transform-like detection of straight bounding frame borders. Pairs specialized philosophy segmentation (`logic_philosophy_v2_seg`) with specialized recognition (`logic_philosophy_v2_rec`).
  * **Dense Layout Classifier:** Color mask ratios (red/black ink) and horizontal ink histograms. Pairs specialized segmentation (`logic_philosophy_v2_seg`) with general recognition (`exp6_best`) for handwriting stability.
  * **General Fallback:** Uses `seg_best` and `exp6_best` when structural cues are absent.

---

## 7. Language Model and Post-processing
* **Focus:** Offline transcription refinement.
* **Content:**
  * **Shallow Fusion Decoding:** Integrating `char8_trainval.lm` inside CTC beam search decoding to select visually and contextually probable characters.
  * **Algorithmic Post-Processor:** Post-OCR rule engine (`PostProcessor.process`) to resolve dangling characters, spacing anomalies, and common Arabic letter mergers.

---

## 8. AI-Assisted Manuscript Analysis Features
* **Focus:** High-level semantic interpretation.
* **Content:**
  * **On-Demand LLM Integration:** Balancing cloud API latency by calling OpenRouter/Gemini only on user demand.
  * **Features:** Semantic page summary, title suggestions, named entity extraction (scholars, books, dates), contextual definition hovering, and fuzzy Levenshtein search.

---

## 9. Experiments and Results
* **Focus:** Factual digital findings (incorporating `METRICS_TABLE.md`).
* **Content:**
  * Compare `exp6_best` (7.50% unseen CER) with legacy baseline failure.
  * Demonstrate language model improvements: **7.48% → 6.79%** (RASAM) and **10.27% → 8.81%** (TariMa).
  * Document layout routing test outcomes (100% correct routing on standard samples).
  * Compare CPU vs. GPU latencies: **~14s** CPU run vs. **~4s** GPU run vs. **0s** cash hit.

---

## 10. Applications
* **Focus:** Real-world deployments.
* **Content:**
  * Academic transcription workspace.
  * Local libraries manuscript indexing.
  * Duplication matching (cross-collection matching of copies using Fihrist/OpenITI metadata).

---

## 11. Limitations
* **Focus:** Objective bottlenecks.
* **Content:**
  * **Over-Segmentation:** Tendency of segmenters to segment margins into small text fragments when borders are faint.
  * **Catalog Limitation:** Local catalog search matches metadata fingerprints, not full-text manuscript content.
  * **Docker GPU Bounds:** Docker container deployment is CPU-based; GPU acceleration requires local PyTorch execution.

---

## 12. Future Work
* **Focus:** Roadmap for Rakīm AI.
* **Content:**
  * Expanding fine-tuning sets to cover all **8 manuscript families** visually identified.
  * Training a single robust segmentation model that handles marginalia natively.
  * Implementing a local full-text reuse index to search actual transcribed texts against external corpuses.

---

## 13. References
* **Content:**
  * The RASAM Dataset and TariMa Project.
  * OpenITI (Open Islamic Texts Initiative) and FIHRIST (UK Union Catalogue of Islamic Manuscripts).
  * Kraken OCR Engine & eScriptorium Framework.
  * PyTorch and CUDA developer references.