z-parser

Python SDK for the z-parser document-extraction service: bytes in, RAG-ready Markdown out. Scanned PDFs (SOTA OCR + vision escalation), Office, spreadsheets, images, charts, manuscripts, EPUB, e-mail, audio/video transcription — one client.

pip install z-parser-sdk       # the import stays `z_parser`, the CLI stays `z-parser`

from z_parser import ZParser

zp = ZParser("http://localhost:4056")     # or export Z_PARSER_URL
doc = zp.parse("rapport.pdf")             # path, or bytes + filename=
print(doc.parser, doc.num_chars)          # e.g. "mistral-ocr+figures(2)" 48213
doc.save("rapport.md")

pdf = zp.render_pdf("deck.pptx")          # Office → viewable PDF (page N = slide N)
figs = zp.images("catalogue.pdf", mode="artwork")   # per-figure crops + captions

CLI:

z-parser contract.pdf -o contract.md

Pick your provider and quality levers from the client — Mistral, Ollama (100 % local), vLLM, Hugging Face, Gemini or any OpenAI-compatible vision endpoint, per client or per call:

# Mistral vision in one word (openai dialect on api.mistral.ai, server key applies)
zp = ZParser(vision_provider="mistral", vision_model="mistral-small-latest")

# 100 % local with Ollama — no data leaves your machine
zp = ZParser(vision_provider="openai",
             vision_base_url="http://host.docker.internal:11434/v1",  # seen FROM the server
             vision_model="llama3.2-vision",
             doc_vision=True)      # PDFs through local vision too → fully offline

# Quality levers (mirror the server's .env):
doc = zp.parse("dossier.pdf",
               ocr_escalate=True,       # weak OCR pages re-read by vision (manuscripts)
               describe_figures=True)   # embedded charts/diagrams described on their page

One runnable example per provider ships in examples/ (with sample files), plus 09_formats_sweep.py — a QA battery (PDF, image, Excel, HTML, XML, LaTeX, CSV) that checks Markdown structure and writes a browsable results/ gallery. Safety contract: a caller-chosen vision_base_url never receives the server's own API keys (api_key is an alias for vision_api_key). With no params, the server's configuration applies.

Errors are explicit: ZParserError carries the service's status (unsupported / error) and message. Timeouts default to 15 minutes — large OCR jobs are slow by nature; pass timeout= to change.

The service itself (Docker, one container) and its ground-truth benchmark live in the main repository.