slm_document_parser/README.md

SLM Document Parser

A local CPU-optimized document structure and text parser agent powered by Microsoft's MIT-licensed Phi-3.5-mini-instruct and Florence-2-large models running via ONNX Runtime GenAI.

It handles complex document parsing workflows by combining a Hybrid Visual OCR Pipeline (rendering PDF/Office pages to images, detecting tables/figures, running block OCR, and assembling layouts using LLM reasoning) with native layout-aware parsing fallbacks. It also features Semantic Graph-Chunking to slice text into RAG-compliant chunks with cross-linked metadata, and can export results directly to Microsoft Excel.

---

🧠 1. Agentic Architecture & Workflow

The SLM Document Parser operates as an autonomous visual-to-text routing and validation loop:

+-----------------------------------------------------------+
|                      Raw Input File                       |
|           (PDF, DOCX, DOC, PPTX, PPT, TXT, MD)           |
+-----------------------------+-----------------------------+
                              |
                     [Convert to PDF / Image]
                              v
+-----------------------------------------------------------+
|             Hybrid Visual OCR Pipeline (Florence-2)       |
|  - Render PDF page index to PNG image via pypdfium2       |
|  - Run Object Detection (<OD>) to localize tables/figures  |
|  - Crop detected boxes and run local OCR / Captions       |
+-----------------------------+-----------------------------+
                              |
                              v
+-----------------------------------------------------------+
|              Layout Assembly & Markdown Synthesis          |
|  - Combine OCR text, markdown tables, and captions       |
|  - Self-correct formatting trace errors via Phi-3.5 ONNX  |
+-----------------------------+-----------------------------+
                              |
                              v
+-----------------------------------------------------------+
|               Semantic Graph Chunker & Linker             |
|  - Group text into RAG chunks (minimum 15-20 words)       |
|  - Extract headings, keywords, and product references     |
|  - Link related sibling paragraphs together               |
+-----------------------------+-----------------------------+
                              |
                              v
+-----------------------------------------------------------+
|                       Output Formats                      |
|             (Structured JSON, Excel spreadsheet)          |
+-----------------------------------------------------------+

Advanced Features:

1. Hybrid Visual OCR Pipeline: Converts scanned pages or low-text layout pages to images using pypdfium2. Runs Florence-2 <OD> to localize tables and figures, crops and OCRs tables, captions figures, and uses the local LLM to reconstruct the page back into perfect Markdown.
2. Office Document Conversions: Leverages LibreOffice (soffice --headless) on Darwin/Linux to convert formats like .docx, .doc, .pptx, .ppt into clean PDFs for visual parsing, falling back to zip XML extractors and OLE stream readers (olefile).
3. Semantic Linkage Chunking: Divide documents by topics and paragraphs instead of simple character counts. Extract active section headings, subheadings, key terms, and map cross-linked references between sibling chunks.
4. Excel spreadsheet export: Save chunk tables ([Index, Source, Heading, Subheading, Product, Related, Text]) into .xlsx documents.

---

⚡ 2. CPU Performance Tuning Guidelines

1. Allocating Threads (n_threads):
   • Limit n_threads to your CPU's physical core count (excluding hyperthreads) to avoid cache thrashing and lockups.
2. Context Window Configuration (n_ctx):
   • Keep n_ctx as tight as possible (e.g., 4096 or 8192) to reduce token evaluation latency.
3. Memory Limits & Garbage Collection:
   • Florence-2 is memory-intensive. The parser runs page extractions sequentially and cleans temporary page PNG images immediately after synthesis to keep the RAM footprint under 2.0 GB.

---

📂 3. API Reference

SLMDocumentParser

from slm_document_parser.document_parser import SLMDocumentParser

parser = SLMDocumentParser(
    model_path=None,   # Path to the ONNX model directory (defaults to models/phi-3.5-mini-instruct-onnx)
    cache_dir=None,    # Alternative HF cache dir
    n_ctx=4096,        # Context length (defaults to 4096)
    n_threads=4        # Number of CPU threads to use for execution
)

Methods

extract_text(file_path: str) -> str

Extracts layout-reconstructed markdown text from target document file. Runs the hybrid visual OCR pipeline for PDFs and converts office formats automatically if LibreOffice is present.

• file_path (str): Local path to target document.
• Returns: str representing document Markdown.

chunk_document(file_path: str) -> list[dict]

Extracts text and splits it into semantic chunks with metadata linkages.

• file_path (str): Local path to target document.
• Returns: list[dict] containing text and structured metadata headers.

parse_and_chunk_stream(file_path: str) -> Generator

Streaming generator yielding semantic chunks page-by-page as they are processed.

• file_path (str): Local path to target document.
• Returns: Generator yielding chunk dicts.

export_chunks_to_excel(chunks: list[dict], output_path: str, append: bool = False) -> None

Saves the extracted chunks to an Excel spreadsheet.

• chunks (list[dict]): Chunks generated by the parser.
• output_path (str): Target Excel file path.
• append (bool): Set to True to append to an existing Excel worksheet.

---

🚀 4. Usage Example

Here is an end-to-end usage example showing document text extraction, semantic chunking, and Excel sheet exporting:

from slm_document_parser.document_parser import SLMDocumentParser

# Initialize the parser
parser = SLMDocumentParser()

file_path = "financial_report.pdf"

# 1. Parse document text (runs visual OCR pipeline for scanned tables)
markdown_content = parser.extract_text(file_path)
print("--- Document Markdown Output ---")
print(markdown_content[:500])

# 2. Extract semantic RAG chunks with cross-linked indexes
chunks = parser.chunk_document(file_path)

# 3. Export chunks directly to Excel
parser.export_chunks_to_excel(chunks, "rag_database.xlsx")

Generated Output Chunks (JSON):

[
  {
    "text": "SpaceX successfully launched the Falcon 9 rocket from Cape Canaveral Space Force Station, landing the booster return flight for the 15th time. The mission delivered communication payloads into low Earth orbit.",
    "metadata": {
      "source": "financial_report.pdf",
      "heading": "1. Launch Milestones",
      "subheading": "Falcon 9 Performance",
      "product": "SpaceX",
      "key_terms": ["Falcon 9", "Cape Canaveral", "booster"],
      "format": "pdf",
      "chunk_index": 0,
      "related_chunks": [1, 2]
    }
  }
]

Generated Output Excel Spreadsheet Layout:

Chunk Index	Source File	Heading	Subheading	Product	Related Chunks	Text
0	financial_report.pdf	1. Launch Milestones	Falcon 9 Performance	SpaceX	1,2	SpaceX successfully launched...