semantica/docs/reference/parse.md

title, description, icon

title	description	icon
Parse Module	Document parsing and text extraction — DocumentParser for standard formats and DoclingParser for complex layouts.	file-lines

semantica.parse extracts structured text, layout, tables, and metadata from unstructured documents. DocumentParser handles clean machine-readable files; DoclingParser handles complex layouts, scanned PDFs, and multi-column documents.

Exported Classes

from semantica.parse import (
    DocumentParser,    # auto-detect format — delegates to format-specific parser
    PDFParser,         # PDF text extraction
    DOCXParser,        # Word .docx documents
    HTMLParser,        # HTML / web pages
    MarkdownParser,    # Markdown files
    TXTParser,         # plain text
    JSONParser,        # JSON documents
    XMLParser,         # XML documents
    CSVParser,         # CSV / TSV files
    WebParser,         # URL fetch + HTML parsing
    EmailParser,       # .eml / .msg email files
    CodeParser,        # source code files
    # Data types
    ParsedDocument,    # {text, sections, tables, metadata, source_id}
    DocumentMetadata,  # {title, author, created_date, page_count, language, ...}
)

# Optional — requires: pip install "semantica[docling]"
from semantica.parse import DoclingParser  # advanced OCR + layout analysis

What You Get

• DocumentParser — standard parser for PDF, DOCX, HTML, TXT, JSON, CSV, PPTX, XLSX — auto-detects format
• DoclingParser — advanced parser for complex layouts, merged-cell tables, multi-column PDFs, and OCR (optional dep)
• ParsedDocument — structured output with text, sections, tables, and metadata
• Format-specific parsers — PDFParser, DOCXParser, HTMLParser, WebParser, EmailParser, CodeParser, etc.

DocumentParser

Standard parser for clean, machine-readable documents:

from semantica.parse import DocumentParser

parser = DocumentParser()
parsed = parser.parse("data/report.pdf")

print(parsed.text)       # full clean text
print(parsed.metadata)   # title, author, date, page_count, language, etc.
print(parsed.sections)   # document structure as a list of Section objects

Supported formats: PDF, DOCX, HTML, TXT, JSON, CSV, PPTX, XLSX.

DoclingParser

Advanced parser using the Docling backend — handles layouts that DocumentParser cannot:

pip install "semantica[docling]"

from semantica.parse import DoclingParser

parser = DoclingParser(
    extract_tables=True,       # structured table extraction with cell type detection
    extract_images=True,       # extract image regions for downstream OCR
    output_format="markdown",  # "markdown" | "html" | "json"
)

parsed = parser.parse("data/annual_report.pdf")

print(parsed.text)     # full clean text
print(parsed.tables)   # structured TableData objects with headers and rows
print(parsed.sections) # document structure with heading hierarchy

Use DoclingParser for:

• Multi-column PDF layouts
• Tables with merged cells or complex headers
• PPTX slides with embedded charts
• XLSX spreadsheets with formulas
• Scanned documents with OCR
• Academic papers and technical reports

OCR Support

parser = DoclingParser(
    ocr=True,
    ocr_language=["en"],   # ISO 639-1 codes; list for multi-language documents
    extract_tables=True,
)

parsed = parser.parse("data/scanned_contract.pdf")

Parsed Document Object

Both parsers return a ParsedDocument with the same structure:

@dataclass
class ParsedDocument:
    text:      str                  # full extracted text
    sections:  List[Section]        # heading-based document structure
    tables:    List[TableData]      # structured table data (DoclingParser only)
    metadata:  DocumentMetadata     # title, author, dates, page count
    source_id: str                  # links back to the original DataSource

@dataclass
class DocumentMetadata:
    title:        Optional[str]
    author:       Optional[str]
    created_date: Optional[datetime]
    page_count:   int
    language:     Optional[str]     # ISO 639-1 code
    has_tables:   bool
    has_images:   bool
    word_count:   int
    format:       str               # "pdf" | "docx" | "pptx" | ...

Integration with FileIngestor

The most common pattern — ingest a directory then parse each source:

from semantica.ingest import FileIngestor
from semantica.parse import DoclingParser

ingestor = FileIngestor()
parser   = DoclingParser(extract_tables=True)

sources = ingestor.ingest("data/reports/")
for source in sources:
    parsed = parser.parse(source)
    # → parsed.text, parsed.tables, parsed.sections

Docling is an optional dependency. If `docling` is not installed, `DoclingParser` raises an `ImportError` with installation instructions. `DocumentParser` is always available and requires no extras. Load files before parsing. Chunk parsed text for embedding and extraction. Full Docling integration setup guide. Extract entities and relations from parsed text.