nepali-ocr-ai

🇳🇵 nepali-ocr-ai (लिपिकार AI)

High-Fidelity Nepali Vision OCR, Contextual Varnavinyas Grammar Checker, Bi-directional Preeti-Unicode Phonetic Transcoder, and OpenXML Word (.docx) Repair Substrate.

Part of the Aaradhya Dev Tamrakar Personal Tool Ecosystem (Module #19).

---

🎯 Key Problems Solved

1. The 30-Year Font Fracture:
   • Administrative and legal institutions in Nepal remain heavily dependent on legacy 8-bit ASCII font hacks (Preeti, Kantipur, Himali, Sagarmatha).
   • In legacy fonts, g]kfnL visually renders as नेपाली, but underlying codepoints are Latin letters. This breaks search, copy-paste, screen readers, indexing, and modern AI/NLP models.
   • Conversely, sending modern Unicode Devanagari (Kalimati, Mangal) to government offices often causes rejection if their internal templates require Preeti.
2. Compound Conjuncts & Visual-Ordering Inversion:
   • In Preeti, prefix vowel signs (ि / l), rephs (र् / {), and sub-characters are typed in visual display order (typing l before the letter).
   • In Unicode, characters are stored in phonetic order (Consonant + Halanta + Consonant + Matra).
   • Naive search-and-replace fails catastrophically on compound conjuncts (e.g. क्ष, त्र, ज्ञ, द्ध, द्य, दृ, ङ्क).
3. Noisy Scanned Documents & Degradation:
   • Faint photocopies, skewed legal notices, and official government circulars fail standard OCR engines.
   • nepali-ocr-ai leverages Multimodal Vision AI (Gemini Flash Vision) with fallback local OCR (tesseract-ocr with nep.traineddata).
4. Nepali Grammar & Varnavinyas Orthography Chaos:
   • Resolves ह्रस्व (short) vs. दीर्घ (long) vowel confusion (ि/ी, ु/ू).
   • Enforces correct sibilant distinction across तालव्य (श), मूर्धन्य (ष), and दन्त्य (स).
   • Detects पदयोग र पदवियोग (joint postpositions like विभक्ति vs. split verbs).
   • Aligns Subject-Verb Honorific Agreement (लिङ्ग, वचन, पुरुष र आदर अनुसार क्रियापदको सङ्गति) according to official Nepal Academy (नेपाल प्रज्ञा-प्रतिष्ठान) rules.
5. OpenXML Word (.docx) Corruption:
   • Translates mixed-font documents in-place without destroying paragraph styles, margins, headings, or table layouts.

---

🏗️ System Architecture

                                  [ Scanned Document / Image / PDF / Text / DOCX ]
                                                         │
                                                         ▼
                                           ┌───────────────────────────┐
                                           │ Vision OCR Ingestion      │
                                           │ • Multimodal Flash Vision │
                                           │ • Layout & Bounding Boxes │
                                           └─────────────┬─────────────┘
                                                         │ Clean Unicode Devanagari
                                                         ▼
                                           ┌───────────────────────────┐
                                           │ Hybrid Grammar & Linter   │
                                           │ 1. Deterministic Lexicon  │
                                           │    • Varnavinyas (ह्रस्व/दीर्घ) │
                                           │    • Padayoga/Padaviyoga  │
                                           │ 2. Contextual LLM Suggester│
                                           │    • Honorific / Adar Fit │
                                           │    • Legal Register Audit │
                                           └─────────────┬─────────────┘
                                                         │ Linted / Standardized Unicode
                          ┌──────────────────────────────┴──────────────────────────────┐
                          ▼                                                             ▼
           ┌─────────────────────────────┐                               ┌─────────────────────────────┐
           │ Mode 1: Modern Unicode DOCX │                               │ Mode 2: Legacy Preeti DOCX  │
           │ • Target: Mangal / Kalimati │                               │ • Syllabic AST Transcoder   │
           │ • Proper OpenXML font tags  │                               │ • Prefix matra / reph shift │
           │ • Universal Searchability   │                               │ • Injects Preeti font glyphs│
           └──────────────┬──────────────┘                               └──────────────┬──────────────┘
                          │                                                             │
                          └──────────────────────────────┬──────────────────────────────┘
                                                         ▼
                                           ┌───────────────────────────┐
                                           │ OpenXML DOCX Generator    │
                                           │ • Inline Proofing / Marks │
                                           │ • Preserved Table Layouts │
                                           │ • Native Word Output      │
                                           └───────────────────────────┘

---

⚡ Quick Start

1. Installation

# Clone the repository
git clone https://github.com/Aaradhya-Dev-Tamrakar/nepali-ocr-ai.git
cd nepali-ocr-ai

# Create virtual environment and install dependencies
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt

2. CLI Usage

# OCR an image/scan directly into a Word document (Unicode mode)
python -m nepali_ocr_ai.cli ocr ./scans/notice.jpg -o ./output/notice.docx --font unicode

# OCR and output as legacy Preeti Word document
python -m nepali_ocr_ai.cli ocr ./scans/notice.jpg -o ./output/notice_preeti.docx --font preeti

# Run Varnavinyas grammar and orthography linting
python -m nepali_ocr_ai.cli lint "उहाले काम गरि सके पछि जानु भयो ।"

# Convert an existing Word document with broken/mixed Preeti fonts to clean Unicode
python -m nepali_ocr_ai.cli repair-docx ./dirty_document.docx -o ./clean_document.docx --target unicode

---

🔌 FastMCP Tool Integration

nepali-ocr-ai exposes a native Model Context Protocol (FastMCP) server over stdio, allowing agents in Claude Desktop, Antigravity, or Nexus to invoke it directly:

Claude Desktop Configuration (claude_desktop_config.json)

{
  "mcpServers": {
    "nepali-ocr-ai": {
      "command": "python",
      "args": ["-m", "nepali_ocr_ai.mcp_server"],
      "cwd": "F:\Aaradhya-Dev-Tamrakar\nepali-ocr-ai"
    }
  }
}

Exposed Capabilities:

1. ocr_nepali_document: Scans images/PDFs and returns structured text + layout blocks.
2. check_nepali_grammar: Audits Varnavinyas orthography, spelling, and honorific subject-verb agreement.
3. transcode_nepali_fonts: Bi-directional deterministic transcoding between Unicode $\longleftrightarrow$ Preeti.
4. repair_word_document: In-place OpenXML Word document font correction.

---

📜 Invariants & Verification

Invariant ID	Rule Description	Enforcement Engine
INV-NEP-001	Round-Trip Determinism: Unicode $ o$ Preeti $ o$ Unicode guarantees $\ge 99.8%$ character fidelity without ligature loss.	Syllabic AST unit tests (pytest tests/)
INV-NEP-002	Style & Layout Preservation: Word repairs preserve 100% of tables, column widths, and styles.	OpenXML AST validator
INV-NEP-003	Headless Completeness: 100% of pipeline executable via CLI/Python API.	CLI test suite
INV-NEP-004	Grammar Transparency: Rule violations are explicitly separated from stylistic/honorific suggestions.	JSON structured report

---

📄 License & Author

• Principal Architect: Aaradhya Dev Tamrakar
• License: MIT License
• Ecosystem Brain: Aaradhya-Dev-Tamrakar/brainstorm