Parser Module — File Format Extraction

Format-specific extractors for PDF, DOCX, Excel, HTML, Markdown, JSON, Text, EPUB, and PowerPoint.

What is this? — The parser layer handles file-format specifics: decoding PDF streams, walking DOCX XML trees, iterating Excel cells, traversing HTML DOMs. Each format gets its own extraction strategy.

Core Parsers

200KB+

Code

Alt Engines

Core Parsers (Format-Specific)

PDF Parser

pdf_parser.py (85KB) — Master handler for PDF files.

Text extraction via pdfplumber

Layout recognition

Table detection & cell grid

Figure extraction

OCR fallback for scanned PDFs

Focus: PDF Parsing Pipeline

DOCX Parser

docx_parser.py (6.7KB) — Microsoft Word extraction via python-docx.

Heading hierarchy preservation
Paragraph-level text grouping
Table extraction via XML parsing
Embedded image handling
Style metadata (bold, italic, font)

Excel Parser

excel_parser.py (11KB) — XLSX cell extraction and structure.

Sheet enumeration
Merged cell handling
Formula vs. value detection
Cell type coercion (date, number, text)
Row/column grouping

HTML Parser

html_parser.py (8.3KB) — BeautifulSoup-based DOM traversal.

Recursive element walking
Block-level vs. inline detection
Link extraction
Script/style tag filtering
Deep nesting unwinding

Markdown Parser

markdown_parser.py (12KB) — AST-based MD extraction.

Heading-based sectioning
Code block preservation
List structure preservation
Link and image metadata
Blockquote hierarchies

JSON Parser

json_parser.py (6.4KB) — JSON and JSONL extraction.

JSON tree flattening
JSONL line-by-line parsing
Key extraction strategy
Nested object handling

Text Parser

txt_parser.py (2.3KB) — Plain text with line grouping.

Blank-line-based chunking
Paragraph detection
Encoding detection

EPUB Parser

epub_parser.py (5.3KB) — E-book extraction via zipfile.

OPF manifest parsing
Chapter order preservation
XHTML content extraction
Metadata (title, author)

PowerPoint Parser

ppt_parser.py (3.7KB) — PPTX slide text extraction.

Slide enumeration
Text box extraction
Speaker notes
Title/content grouping

Figure Parser

figure_parser.py (12KB) — Image & figure extraction.

Figure detection in PDFs
DOCX image extraction
Excel image indexing
Caption association
Vector vs. raster differentiation

Alternative Engines (Pluggable Strategies)

deepdoc offers multiple parsing strategies. Choose based on your document corpus and accuracy/speed trade-off.

Engine	File	Best For	Trade-off
Standard (pdf_parser.py)	85KB	Born-digital PDFs, mixed layouts	Balanced: fast + accurate
Docling	docling_parser.py (23KB)	Complex layouts, academic papers	Slower: higher accuracy
MinerU	mineru_parser.py (31KB)	Financial reports, structured docs	Specialized: layout-aware
PaddleOCR	paddleocr_parser.py (23KB)	Scanned documents, Chinese text	OCR-first: multilingual
TCADp	tcadp_parser.py (24KB)	Tables + charts	Table-focused
OpenDataLoader	opendataloader_parser.py (16KB)	Structured extraction	JSON-oriented output

Parser Interface (Common Pattern)

All parsers implement a standard extraction flow:

class RAGFlow*Parser:
    def __init__(self, **kwargs):
        # Initialize dependencies (models, clients, etc.)
        pass
    
    def parse(self, file_path, **options):
        # Main entry point
        # Returns: list[Section]
        # Section = {text, type, bbox?, table_html?, image_path?}
        pass
    
    def parse_into_bboxes(self, file_path, **options):
        # Returns: list[BBox] with spatial coordinates
        # For layout-aware retrieval
        pass

Parser Decision Tree

pdfplumber + layout"] PDFEngine -->|docling| PDFDocling["docling_parser.py
Meta's model"] PDFEngine -->|mineru| PDFMineru["mineru_parser.py
Vision-first"] PDFEngine -->|paddleocr| PDFPaddle["paddleocr_parser.py
Scanned-first"] DOCX --> DocxImpl["python-docx
XML walk"] EXCEL --> ExcelImpl["openpyxl
cell iteration"] HTML --> HtmlImpl["BeautifulSoup
DOM traversal"] MD --> MdImpl["markdown-it
AST parsing"] TXT --> TxtImpl["line grouping
encoding detect"] EPUB --> EpubImpl["zipfile + lxml
OPF + XHTML"] PPT --> PptImpl["python-pptx
slide walk"] JSON --> JsonImpl["json.load
tree flatten"] PDFStd --> Output["Output: Sections
+ optional bboxes"] PDFDocling --> Output PDFMineru --> Output PDFPaddle --> Output DocxImpl --> Output ExcelImpl --> Output HtmlImpl --> Output MdImpl --> Output TxtImpl --> Output EpubImpl --> Output PptImpl --> Output JsonImpl --> Output classDef inputStyle fill:#1a3a52,stroke:#58a6ff,color:#f0f6fc classDef decisionStyle fill:#3d3d1a,stroke:#d29922,color:#f0f6fc classDef pdfStyle fill:#2d5a3d,stroke:#3fb950,color:#f0f6fc classDef implStyle fill:#5a2d3d,stroke:#f85149,color:#f0f6fc classDef outputStyle fill:#3d5a2d,stroke:#d29922,color:#f0f6fc class Input inputStyle class Format,PDFEngine decisionStyle class PDF,PDFStd,PDFDocling,PDFMineru,PDFPaddle pdfStyle class DOCX,EXCEL,HTML,MD,TXT,EPUB,PPT,JSON,DocxImpl,ExcelImpl,HtmlImpl,MdImpl,TxtImpl,EpubImpl,PptImpl,JsonImpl implStyle class Output outputStyle

Typical Parser Flow (PDF Example)

Init: Load pdfplumber, initialize LayoutRecognizer, OCR client, XGBoost model
Open: pdfplumber.open(file_path)
Iterate pages: for page in pdf.pages
Extract text: page.extract_text() — may return None if no text layer
Render image: if no text, render page at 3x zoom
Run layout: LayoutRecognizer(image) → bboxes with class labels
Assign text: Match extracted text to bboxes (spatial overlap)
Detect tables: For "Table" bboxes, run TableStructureRecognizer
Extract figures: For "Figure" bboxes, crop and save image
OCR fallback: For low-confidence text regions, run OCR
Assemble page: Collect all regions into semantic blocks (heading, text, table, figure)
Output: List of sections with type, text, bbox, confidence

Error Handling Philosophy

Fallback chain: Gracefully degrade rather than fail.

Text extraction fails → Try OCR instead
Layout detection fails → Output raw text (unstructured)
Table detection fails → Keep as text
Figure caption lost → Keep figure without caption
Model loading fails (local) → Download from HuggingFace
Remote DLA fails → Fall back to local ONNX
Low confidence → Include with confidence flag, let downstream decide

Performance Characteristics

Parser	Speed	Accuracy	Scanned PDFs	Multilingual
pdf_parser.py (standard)	Fast	High	Good (with OCR)	Good
docling_parser.py	Medium	Very High	Excellent	Good
mineru_parser.py	Medium	Very High	Excellent	Fair
paddleocr_parser.py	Medium	High	Excellent	Excellent (80+ langs)
docx_parser.py	Very Fast	Excellent	N/A	Good
html_parser.py	Very Fast	Good	N/A	Good

Resume Parser (Specialized)

Directory: parser/resume/ — Dedicated resume extraction with field detection (contact, experience, skills, education).

Summary

The parser layer abstracts away format specifics. Whether your input is a scanned PDF, a spreadsheet, or HTML, deepdoc's parsers extract semantic content and pass it to the vision and chunking layers. Multi-engine support lets you optimize for accuracy, speed, or language coverage.