academic-doc-sanitizer

Academic Document Sanitizer & Visual Compiler 🎓⚡

Transform messy, raw LaTeX notes and Google Doc exports into publication-grade, executive Microsoft Word (.docx) and PDF (.pdf) documents with zero syntax leaks and instant visual hierarchy.

🛑 The Problem: The "Raw LaTeX & Flat Text" Curse

When engineering students export study notes, exam question banks, or AI-generated solutions from Google Docs, ChatGPT, or Gemini, the output is frequently disastrous:

1. Raw LaTeX Leaks: Formulas are riddled with broken markup like \Delta G^\circ, \frac{I_t}{I_0}, \begin{aligned}, and stray $ delimiters.
2. Word OMML Math Stripping: Inserting Office Math ML (OMML) into python-docx without root XML namespace declarations causes Microsoft Word to silently delete all equations on save.
3. Flat, Indistinguishable Hierarchy: Questions, units, metadata, and solutions all blend into identical, tiny body text. You can't tell where a unit begins or where a question prompt ends.
4. Nested Fraction Breakdowns: Flat regular expressions ([^{}]*) crash or truncate whenever a fraction contains nested braces like \frac{\text{H}^+_{\text{ext}}}{\text{H}^+_{\text{int}}}.

🚀 The Solution: Academic Document Sanitizer

Academic Document Sanitizer is a standalone Python tool and autonomous AI Agent Skill that completely solves document compilation for university engineering coursework:

• 7-Phase Unicode Normalization Pipeline: Replaces raw LaTeX with 100% universal, high-fidelity Unicode mathematical typography (ΔG° = -nFE°, S = (l)/(μ₀ μᵣ A), τ = RC, 20 Ω).
• Balanced Stack-Depth Fraction Parser: Accurately extracts arbitrarily nested numerators and denominators using depth counters instead of fragile regexes.
• Executive Visual Architecture:
  • 🏛️ Major Unit Banners: Full-width Deep Navy (#0B2545) colored bands with bold white capital lettering.
  • 📋 Question Callout Panels: Soft ice-blue callout cards (#F0F4F8) with thick solid navy left borders (#193E87), immediately isolating questions from solutions.
  • 🟢 Model Solution Badges: Bold Emerald Green (#107C41) indicator headers.
  • 📊 Publication-Grade Tables: Automatic CSV detection with shaded navy headers, alternating zebra stripes, and clean cell padding.
• Automated Zero-Defect Audit Suite: Programmatically verifies that 0 raw LaTeX tags, 0 stray dollar signs, and 0 syntax leaks survive in the compiled DOCX and PDF.

🏗️ Architecture

flowchart TD
    A["Raw Academic Notes / Google Doc Text Export"] --> B["Environment Unfolder (preprocess_aligned_blocks)"]
    B --> C["Token-Based Equation Isolator (split_display_equations)"]
    C --> D["Structural AST Parser"]
    
    D -->|Unit Header| E["Full-Width Deep Navy Banner (#0B2545)"]
    D -->|Question Title| F["Royal Blue Heading 2 (#133E87)"]
    D -->|Question Text| G["Ice-Blue Callout Panel (#F0F4F8) with Navy Border"]
    D -->|Model Solution| H["Emerald Green Model Solution Indicator (#107C41)"]
    D -->|CSV Rows| I["Publication Table with Shaded Header & Zebra Rows"]
    D -->|Inline / Display Math| J["7-Phase Math Normalizer (math_engine)"]
    
    J --> J1["Phase 0: Sizing hints removal (\\left, \\right)"]
    J1 --> J2["Phase 1: Balanced Stack Fraction Parser (process_fracs)"]
    J2 --> J3["Phase 2: Chemical Formulas (SiO₂, Hg₂Cl₂, Ag/AgCl)"]
    J3 --> J4["Phase 3: Greek & Math Symbols (ΔG°, ⇌, log₁₀, τ, ϕ, Ω)"]
    J4 --> J5["Phase 4: Subscripts & Superscripts via Unicode Dictionaries"]
    J5 --> J6["Phase 5: Purge residual syntax & backslashes"]
    
    E & F & G & H & I & J6 --> K["Native DOCX Compiler"]
    K --> L["Process Hygiene: Terminate WINWORD Zombie Locks"]
    L --> M["High-Resolution PDF Compilation (docx2pdf)"]
    M --> N["Deep Defect Auditor (auditor.py)"]
    N -->|Defects == 0| O["Verified Production Document Output"]

📦 Installation

git clone https://github.com/awateatharva4-pixel/academic-doc-sanitizer.git
cd academic-doc-sanitizer
pip install -r requirements.txt

💻 CLI Quickstart

Compile any markdown or text export into styled .docx and high-contrast .pdf with automated auditing:

python cli.py input_notes.md -o output.docx -p output.pdf --audit

Python API

from academic_doc_sanitizer import compile_document, audit_document

with open("notes.md", "r", encoding="utf-8") as f:
    text = f.read()

# Compile Word & PDF with executive styling
compile_document(text, output_docx="Handbook.docx", output_pdf="Handbook.pdf")

# Audit output
defects = audit_document("Handbook.docx", "Handbook.pdf")
print(f"Total defects found: {len(defects)}")
assert len(defects) == 0

🤖 Using as an AI Agent Skill

This repository includes a ready-to-use Agent Skill specification in skills/academic-doc-sanitizer/SKILL.md.

• Antigravity IDE: Place in ~/.gemini/config/skills/academic-doc-sanitizer/SKILL.md or .agents/skills/.
• Claude Code / Cursor: Add the skill directory to your agent prompt rules.
• Any AI coding assistant equipped with this skill will automatically follow the 7-phase normalization pipeline and visual hierarchy rules whenever you ask it to generate study notes or handbooks.

👤 Author

Atharva

• 1st-Year B.Tech in Artificial Intelligence & Machine Learning (AIML)
• Kolhapur Institute of Technology's College of Engineering (Autonomous), Kolhapur
• Built with 10 CGPA Academic Rigor 🎯

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.