PROJECT_FACTS_DOSSIER.md

# 📋 PROJECT FACTS DOSSIER: Rakīm AI (رَقِيم)

This dossier provides a verified, factual inventory of the Arabic manuscript HTR/OCR project based on a deep inspection of codebase files, test logs, config files, and the presentation dashboard. 

---

## 1. Project Naming Inventory & Recommendation

* **Names Currently in Use:**
  1. **Phoenix AI:** Main name defined in `config.py` (`PROJECT_NAME = "Phoenix AI"`), `docker-compose.yml`, and environmental configurations. Developed by the "Phoenix Team" (فريق فنكس).
  2. **Muharaf (مُحرف):** Used in the core `README.md`, the older `project_review_report.md` ("Muharaf OCR Project Review & Execution Guide"), and the SQLite cache database filename (`muharaf_cache.db`).
  3. **Rakīm / رَقيم (Rakīm AI):** Used in the unified presentation document `المقارنة_الموحدة.md` and the HTR handoff notes `HTR_handoff_v2.md`.
  4. **Athar:** Mentioned in historical requirements but not active in core codebase configurations.

* **Unified Name Recommendation:** 
  We strongly recommend unifying the project under the name **Rakīm AI (رَقيم)** for the final report and user interface. 
  * *Rationale:* "رَقِيم" is a classical Arabic term meaning "inscribed tablet" or "writing," which perfectly aligns with the cultural preservation of manuscripts. It sounds highly professional, unique, and premium for a national AI competition, whereas "Phoenix AI" represents the team name and "Muharaf" is a generic tool name.

---

## 2. One-Paragraph Project Description

**Rakīm AI** is an intelligent, end-to-end pipeline system designed to transcribe, segment, analyze, and catalog historical handwritten Arabic manuscripts (HTR/OCR), with a primary focus on Maghrebi calligraphic hands. The system takes raw manuscript page images, processes them through a layout routing engine to select optimal neural segmentation and recognition models, classifies lines into main text (*matn*) or margins (*hashiya*), corrects transcriptions using a local character n-gram language model, and provides a suite of AI-assisted tools (automatic summarization, title suggestion, entity extraction, context dictionary definitions, fuzzy Levenshtein search, and manuscript catalog matching against OpenITI and Fihrist databases).

---

## 3. Implemented Architecture

The system implements a structured processing pipeline:

```mermaid

graph TD

    A[Raw Page Image] --> B[Image Deskew & Preprocessing]

    B --> C[Kraken nlbin Binarization]

    C --> D[Layout Router]

    D -->|Framed Layout| E1[Logic Segmentation Model: logic_philosophy_v2_seg]

    D -->|General Layout| E2[Default Segmentation Model: seg_best]

    E1 & E2 --> F[Line Polygons & Coordinates]

    F --> G[Adaptive Line Merging & Noise Filtering]

    G --> H[Region Classifier: Matn vs. Hashiya]

    H --> I[Recognition Model Routing]

    I -->|Framed Layout & Logic| J1[Logic Rec Model: logic_philosophy_v2_rec]

    I -->|General/Dense Layout| J2[Default Rec Model: exp6_best]

    J1 & J2 --> K[CTC Beam Search decoding / Optional LM fusion: char8_trainval.lm]

    K --> L[Logical Arabic Text Output]

    L --> M[Post-OCR AI Analysis / Fuzzy Search / Catalog Matching]

```

* *Optional Components:* Language Model (LM) decoding (activated by setting `USE_LM=true` in `.env`) and AI Analysis Features (rely on external OpenRouter/Gemini API keys).

---

## 4. Model Inventory

| Model File | Type | Role | Used in Profile | Status / Notes |
| :--- | :--- | :--- | :--- | :--- |
| `seg_best.mlmodel` | Segmentation (BLLA) | Default line segmenter | `default` profile, and fallback in `auto` | Implemented and active. Tends to over-segment pages with margins/marginalia. |
| `exp6_best.mlmodel` | Recognition (TorchSeq) | Default recognition model for Maghrebi handwriting | `default` profile, and fallback in `auto` | Implemented and active. Highly accurate on Maghrebi manuscript hands. |
| `logic_philosophy_v2_seg.mlmodel` | Segmentation (BLLA) | Specialized segmenter for framed/dense manuscripts | `logic` profile, and selected in `auto` when frame detected | Implemented and active. Renamed from `logic_shamsiyya_seg.mlmodel`. |
| `logic_philosophy_v2_rec.mlmodel` | Recognition (TorchSeq) | Specialized recognition for philosophy manuscripts | `logic` profile, and selected in `auto` when framed page detected | Implemented and active. Renamed from `logic_shamsiyya.mlmodel` or `reg.mlmodel`. |
| `char8_trainval.lm` | Language Model (n-gram) | Character-level language model for error correction | Enabled via `USE_LM=true` | Implemented and verified. Improves CER on test sets. |
| `reg(96.5).mlmodel` | Recognition (Legacy) | Legacy standard recognition model | None | Obsolete. Must NOT be used by default (causes gibberish outputs on Maghrebi hands). |
| `logic_shamsiyya.mlmodel` | Recognition (Alternative) | Alternative name / backup of logic recognition model | None | Present in models directory. |
| `logic_shamsiyya_seg.mlmodel` | Segmentation (Alternative) | Alternative name / backup of logic segmentation model | None | Present in models directory. |

---

## 5. Model Routing System

The application features an independent routing system that selects segmentation and recognition models dynamically or lets users force them:

* **Segmentation Profiles:** `auto` | `default` | `logic`
* **Recognition Profiles:** `auto` | `default` | `logic`

### Routing Decisions under `auto`:
1. **Framed Page Layout:** The router scans the page for a framed structure (straight horizontal and vertical borders enclosing a text block). If detected, it sets the route to `segmentation=logic` and `recognition=logic` (reason: `framed_text_block`).
2. **Dense Handwritten Layout (No Frame):** The router measures ink density, horizontal line groupings, and the presence of red ink. If it looks like a dense philosophy page, it uses `segmentation=logic` to capture crowded text, but falls back to `recognition=default` (`exp6_best.mlmodel`) because the general recognition model is more accurate for dense handwriting. (reason: `dense_red_layout:...;recognition_default_for_dense_layout`).
3. **General Layout:** If layout cues are weak, it falls back to `segmentation=default` (`seg_best.mlmodel`) and `recognition=default` (`exp6_best.mlmodel`). (reason: `forced_default`).

### Verification Reports (`output/logic_router_tests/`):
* `report_default_default.md`: Confirms that when profiles are forced to `default`, both models run `seg_best.mlmodel` and `exp6_best.mlmodel` on all samples.
* `report_logic_default.md`: Confirms that when profiles are forced to `logic/default`, the system pairs `logic_philosophy_v2_seg.mlmodel` with `exp6_best.mlmodel`.
* `report_logic_logic.md`: Confirms that when profiles are forced to `logic/logic`, the system pairs `logic_philosophy_v2_seg.mlmodel` with `logic_philosophy_v2_rec.mlmodel`.
* `report.md` (auto/auto): Verifies that `sample_01_framed_margin.jpg` correctly routes to `logic/logic` (framed), while `sample_02, 03, 04` correctly route to `logic/default` (dense handwriting).

---

## 6. Current `.env` Configuration (Safe Values)

Safe parameters extracted from `backend/.env` (and `backend/.env.example` templates):
* `USE_VISION_OCR=false` (forces local Kraken engine instead of cloud vision APIs).
* `REC_MODEL_FILE=exp6_best.mlmodel` (default recognition model).
* `SEG_MODEL_FILE=seg_best.mlmodel` (default segmentation model).
* `DEVICE=auto` (resolves to `cuda` if torch detects GPU, else `cpu`).
* `USE_FP16=true` (enables half-precision for GPU speedups).
* `USE_LM=false` (disabled by default in the environment for stable demonstration, but fully functional when set to `true`).
* `CANDIDATES_ENABLED=false` (disabled by default; when enabled, allows extraction of visual/text alternatives).
* `AUTO_CANDIDATES=false` (disabled by default; when enabled, automatically pre-computes candidates for low-confidence lines).
* `FAST_SEGMENTATION=true` (reduces neural BLLA segmentation time to 1-3 seconds instead of 15-30 seconds).
* `MAX_IMAGE_SIZE=4000` (limits image resolution to prevent memory overflow).

*Note: Confidential API keys (`OPENROUTER_API_KEY` and `GOOGLE_GEMINI_KEY`) are loaded but masked for safety.*

---

## 7. GPU/Docker Runtime Environment

* **Docker Services (from `docker-compose.yml`):**
  1. `nginx`: Runs Alpine Nginx load balancer on port `80`, mapping to `/etc/nginx/nginx.conf`.
  2. `ocr-worker`: Runs the backend on port `8001` with `2` or `3` replicas (CPUs limited to 2.0, Memory 4GB in production).
* **Local Access URLs:**
  * Through load balancer: `http://localhost/app`
  * Direct API: `http://localhost:8001/app` / API Docs: `http://localhost:8001/docs`
* **GPU Status in Docker:**
  * Docker-compose files force `DEVICE=cpu` and `USE_FP16=false` in the environment variables for workers. Therefore, **Docker runs on CPU only**.
  * Local execution (running `python run.py` natively) supports GPU and mixed precision (`DEVICE=auto` will resolve to `cuda` on local setups with CUDA-compatible cards like the RTX 4050).
* **Verification Command:**
  To check actual logs inside Docker, use:
  `docker logs phoenix_e2e_lmtrue --tail 150` (or the active worker container name).
  To inspect system resources and hardware:
  `GET http://localhost:8001/api/system/info`

---

## 8. Language Model (LM) Decoding Status

* **Status:** Fully implemented and integrated.
* **Model File:** `نماذج/char8_trainval.lm` (character n-gram language model, ~34.5 MB).
* **Operation:** Shallow fusion decoding. It replaces standard greedy decoding in Kraken with a Beam Search CTC decoder (`LMDecoder` in `backend/app/services/ocr/lm_decoder.py`) that scores character transitions based on language probability.
* **Measured Improvements:**
  * **RASAM Dataset (Maghrebi):** Character Error Rate (CER) improved from **7.48% → 6.79%** (absolute reduction of `0.69%`).
  * **TariMa Dataset:** Character Error Rate (CER) improved from **10.27% → 8.81%** (absolute reduction of `1.46%`).
* **Technical Note:** This is a local statistical n-gram model executing via C++ binding (Kraken/PyTorch), not an external generative API (like ChatGPT).

---

## 9. Catalog and Index Data

* **Metadata Databases:** Combined dataset utilizing **OpenITI** (13,364 works) and **FIHRIST** (15,543 manuscripts from UK libraries).
* **Catalog Statistics (`catalog_stats.json`):**

  * **Total Works:** 35,632

  * **Total Manuscript Copies:** 49,980

  * **Works with Multiple Copies:** 6,003 (16.85%)

  * **Average Copies per Work:** 1.4

  * **Top Institutions:** Wellcome Collection, London (11,192 copies); Bodleian Library, Oxford (7,167 copies); University Library, Cambridge (5,233 copies).

  * **Top Sources:** Fihrist (36,616 copies); OpenITI (13,364 copies).

* **App Implementation:** Fully implemented as a dedicated tab ("فهرس المخطوطات") in the frontend workspace. It supports search queries (Arabic/Latin) and matches OCR-extracted text fingerprints against catalog works (`/api/catalog/match-content`).



---



## 10. UI Enhancements



Verified frontend improvements:

1. **Organized Toolbar Layout:** Restructured into a clean two-row toolbar:

   - *Row 1:* Main operations (File upload, Segmentation/Recognition selectors, region filters, bounding box toggle, direct mode, cache clear, and export).

   - *Row 2:* Labeled "🤖 التحليل الذكي (AI)" with analysis buttons (terminology explanation, page explanation, entity extraction, summary/title generation, uncertain highlighting, candidates, and manuscript search).

2. **Scroll Lock Fix:** Replaced layout locks on mobile/tablet viewports (`max-width: 900px`) with natural vertical scrolling (`overflow-y: auto !important` on body and panels), ensuring the text workspace is fully accessible on all screen sizes.

3. **Dedicated Dropdowns:** Added separate dropdown lists for Segmentation (القص) and Recognition (التفريغ) with choices `auto`, `default`, and `logic` to support independent routing control.

4. **Arabic Localization:** Buttons, titles, and explanations are localized into clear Arabic.