Parsing Documents

Parsing documents with gaik

pip install "gaik[parser]"              # PyMuPDF, python-docx, Docling
pip install "gaik[multimodal-parser]"   # multi-provider vision parsing
# Add llm-google for shared Google/Vertex configs, or llm-litellm for LiteLLM.

Choose by what must survive, not by file type

A parse that returns fluent, plausible text can still have destroyed the one thing the task needed. Decide first what has to still be true afterwards, then pick:

Escalate only when a check fails — start at the cheapest row that could plausibly work, verify (below), and move down one row if it did not. When the text is headed for a search index, the searching-documents skill picks up from here.

Why the cheap path scores zero on tables

Measured on a public benchmark's table split (40 documents, GriTS and TEDS scored against ground-truth HTML table trees):

The zeros are not "much worse" — they are structurally unable to score, and that is the transferable point. The output format decides what can survive. A markdown pipe table has no way to express a merged cell or a two-row header, so a document containing one comes back looking clean and quietly wrong. Plain text loses column boundaries entirely.

So the rule is not "always use vision". It is: if the tables carry merged cells or stacked headers, the parser must emit HTML — and among the paths that do, vision-LLM parsing led the specialized parser, with the gap widest on the messiest layouts.

Treat those numbers as a dated snapshot on one corpus, not a constant. What generalizes is the format argument; re-measure the ranking on documents that look like yours.

Parsing quality is usually a traceability decision, not an accuracy one

The expensive counterexample, measured on an extraction task: feeding the model the native PDF, plain extracted text, or model-produced HTML gave the same F1. Parsing cost 22–25× the wall time and was 93% of total spend, and bought no accuracy at all.

What it did buy was bounding boxes. When the parser returns coordinates for each element, a citation can be matched to a box afterwards, and a human reviewer clicks a highlighted region on the page. The model cannot invent that, and both halves stay independently checkable.

Decide on that basis:

• The deliverable is a reviewer clicking a highlighted box → pay for the rich parse.
• Page-level evidence is enough, or nothing is reviewed by hand → do not. Feed the model the document and skip the parsing bill.

Use the API correctly

The class method and the module-level function of the same name do not return the same type, which is the easiest mistake to make here:

from gaik.software_components.parsers import PyMuPDFParser, parse_pdf

text = PyMuPDFParser().parse_pdf("doc.pdf")     # -> str
result = parse_pdf("doc.pdf")                   # -> dict
text = result["text_content"]

Every parse_document returns a dict, and the key differs by parser:

from gaik.software_components.parsers import (
    DocxParser, DoclingParser, VisionParser, VisionPlusParser, MultimodalParser,
)
from gaik.software_components.llm import get_llm_config

DocxParser().parse_docx("doc.docx")                             # -> str
DoclingParser().parse_document("scan.pdf")["text_content"]      # OCR
config = get_llm_config("azure")                               # explicit provider
VisionPlusParser(vision_config=config).parse_document(
    "doc.pdf"
)["parsed_markdown"]                                            # note: different key
VisionParser(openai_config=config).convert_image("page.jpg")    # -> str
MultimodalParser(api_config=config).parse("doc.pdf")             # -> ParseResult

VisionPlusParser and DoclingApiClientParser take required keyword arguments — vision_config=, and api_base= plus password= — and a bare constructor call fails.

MultimodalParser takes keyword arguments only. Use api_config=get_llm_config(...) for the shared provider interface; the legacy model_provider flags read credentials from the environment. It has no config parameter. VisionParser uses openai_config and VisionPlusParser uses vision_config for the same shared dictionary. Choose native openai, azure, google, vertex, anthropic, anthropic_foundry, aitta, openai_compatible, or optional litellm through get_llm_config. The configured model must accept images. Shared multimodal parsing renders PDF pages as PNG images, so native PDF uploads are not required.

ParseResult is a plain dataclass with raw_markdown, clean_markdown, html (populated only when create_html=True) and usage; it has no save() method, so write the files yourself. DoclingParser has no parse() method.

Set merge_table=True when a table runs across a page break — it instructs the model to stitch the halves back together, which no local parser can do.

For which environment variables each provider needs, read references/parser-selection.md.