mag-parse

One parse() for every document. PDFs go to mag-pdf; everything else goes to mag-file-handler.

from mag_parse import parse

r = parse("invoice.pdf")                      # quality="fast" (default)
r = parse("report.pdf", quality="accurate")   # table structure
r = parse("deck.pptx")                        # quality does not apply
r = parse(pdf_bytes, filename="report.pdf")   # bytes work too

r.markdown        # always populated
r.text            # always populated
r.format          # "pdf" | "docx" | "xlsx" | "eml" | ...
r.engine          # which engine actually ran
r.ok, r.error, r.warnings

The facade itself has zero required dependencies. Both engines are extras, and that is not tidiness — see Install.

Routing

Decided by magic bytes, never the extension. A .docx renamed to .pdf does not reach the PDF engine, and a PDF with no extension does.

parse(file, quality=...)
        │
   sniff %PDF
        │
   ┌────┴─────┐
 PDF        not PDF
   │            │
mag-pdf   mag-file-handler
   │            │
   └────┬───────┘
        ▼
    one Result

quality is a PDF-only knob

For every other format quality is accepted and ignored, so a caller never has to branch on file type. Result.quality is "" there — the knob did not default, it does not exist.

"accurate" selects mag-pdf's profile="tables", leaving table_mode at its default. Those are two different fast/accurate axes: the profile picks the pipeline, table_mode picks TableFormer's weights. The heavier weights measured 27.6 s against 16.1 s for one additional table row, so they are not what "accurate" buys — the table pipeline is.

Markdown, and how honest it is

Both .markdown and .text are always populated, on every path including failure. They are not equally structured, and structured_markdown says which you got:

Measured on generated fixtures with known content: every format above recovers 100% of its title, prose, table cells and numeric values, and seven of the eight produce pipe tables a chunker can find. Plain text is the exception, and correctly so — there is no table in it to preserve.

Read result.structured, not the raw structured_markdown field. The property additionally requires that an extraction succeeded and that the markdown really does contain a heading or a table; the raw field is set by the engine adapter and reported True even for an error result carrying no markdown at all.

Errors

A bad document is a Result, never an exception — check .ok / .error. Only two things raise, and both are the caller's to fix:

Result.status is "ok", "empty" or "error". empty is a failure — an extraction that returns nothing while reporting success is the silent failure both engines guard against, and the facade does not launder it.

HTTP server

pip install 'mag-parse[http,pdf,office]'
mag-parse-http --host 0.0.0.0 --port 8080

curl -sf -F file=@invoice.pdf -F quality=accurate localhost:8080/v1/parse
curl -sf -F file=@notes.docx localhost:8080/v1/parse -H 'Accept: text/markdown'
curl -s localhost:8080/readyz

A bad document is 200 with ok: false; a bad server is 4xx/5xx as application/problem+json. X-Request-Id is echoed if you send one, minted if you do not.

Set MAGPARSE_FAIL_ON_EMPTY=true to turn an extraction that produced no content into a 422 rather than a 200 nobody notices.

Install

pip install 'mag-parse[pdf]'        # PDFs; one dependency, Tesseract bundled
pip install 'mag-parse[office]'     # docx, xlsx, pptx, eml, html, md, txt, csv
pip install 'mag-parse[all]'        # both of the above
pip install 'mag-parse[tables]'     # adds quality="accurate" (~2 GB: torch)
pip install 'mag-parse[all,http]'   # + the HTTP server (`mag-parse-http`)

serve carries no engine on purpose - it is composed with whichever of the above you need, so a PDF-only sidecar does not inherit the office stack's platform limits.

The engines are extras rather than dependencies because extractous (under mag-file-handler) publishes no Linux ARM64 wheel and declares requires-python <3.14, while liteparse (under mag-pdf) has neither limit. Making the office side required would impose both constraints on PDF-only users:

Python 3.10+. Apache-2.0.