AILANG Parse

AILANG Parse

Universal document parsing and generation in AILANG. Extracts structured content from DOCX, PPTX, XLSX, PDF, and image files into JSON and markdown — and writes documents back out in 9 formats. To author a document, write Markdown and convert it; see Writing documents in Markdown.

Office formats (DOCX, PPTX, XLSX) use deterministic XML parsing — no AI, no cloud, instant results. PDFs default to the deterministic pdftotext backend (poppler) — also no AI, no cloud — with poppler (headings, lists, tables and header/footer from the same tools, no installs), docling and liteparse as local alternatives escalating automatically to local docling OCR for scanned/image-only PDFs. Pluggable AI (Gemini, Claude, local Ollama) is available via --pdf-backend ai but is never chosen automatically. Images delegate to whatever AI model you plug in. AILANG Parse is AI-agnostic: swap --pdf-backend/--ai to change the backend, zero code changes.

Install

Two routes; both put a docparse command on your PATH, and both write output next to the file you parse (--output-dir DIR or DOCPARSE_OUTPUT_DIR to change that).

Already have [AILANG](https://github.com/sunholo-data/ailang)? (0.42.0+ of this package, AILANG v0.40.0 dev or later)

ailang install sunholo/ailang_parse

docparse report.docx

The package's [bin] table gives you a shim in ~/.ailang/bin that runs straight out of the registry cache: parse one file, or --convert it. It is deliberately the thin path — describe/summarize, batch mode, PDF backends and --install-backends are not on it (see below). ailang bin list / ailang bin uninstall docparse manage it.

Otherwise, or for the full CLI:

curl -fsSL https://www.sunholo.com/ailang-parse/install.sh | sh

Fetches the published package (~400 KB), installs the AILANG runtime if you do not have it, and links the full docparse wrapper (plus docparse-audit and docparse-render) into ~/.local/bin. --version, --prefix and --uninstall are supported; re-running is a no-op. If you install both, ailang install tells you which one docparse resolves to.

That covers every deterministic format. PDF needs two more things, and they are easy to miss:

brew install poppler        # pdftotext, the default PDF backend

(apt install poppler-utils on Debian/Ubuntu)

docparse --install-backends # docling + liteparse, for scans and layout

--install-backends matters even if you never pass --pdf-backend: when pdftotext finds no text layer the parser escalates to docling on its own, so without it a scanned PDF fails on the default backend. AI backends authenticate with Google ADC (gcloud auth application-default login), not an API key.

Contributors: install from a clone instead

git clone https://github.com/sunholo-data/ailang-parse.git

ln -s "$(pwd)/ailang-parse/bin/docparse" /usr/local/bin/docparse

The wrapper finds the project root by walking up for docparse/main.ail, so it works from a clone, an installed prefix, or a symlink chain. Note that the CLI wrapper and the PDF adapter live under assets/ — the only path the AILANG publisher bundles verbatim — with symlinks at their historical locations.

SDKs

Use AILANG Parse from your language of choice:

pip install ailang-parse          # Python

npm install @ailang/parse # JavaScript/TypeScript go get github.com/sunholo-data/ailang-parse-go # Go

Quick Start

# Office documents (deterministic, no AI needed)

docparse report.docx docparse slides.pptx docparse spreadsheet.xlsx

PDF (deterministic pdftotext by default — no AI); images (AI auto-enabled)

docparse document.pdf docparse photo.png

Options

docparse report.docx describe # AI image descriptions docparse report.docx summarize # AI document summary docparse contract.pdf # PDF: deterministic pdftotext (default) docparse scan.pdf # Scanned PDF: escalates to local docling OCR docparse scan.pdf --pdf-backend ai --ai gemini-3.5-flash-lite # External AI (paid), opt-in only

Format conversion

docparse report.docx --convert output.html docparse data.csv --convert report.docx docparse notes.md --convert slides.pptx docparse notes.md --convert offer.docx --reference-doc letterhead.docx

AI document generation

ailang run --entry main --caps IO,FS,Env,AI --ai gemini-3.5-flash-lite \ docparse/main.ail --generate report.docx --prompt "Q1 sales report with tables"

Output

Every run produces, in the directory you ran from (--output-dir DIR or DOCPARSE_OUTPUT_DIR to change it):

• .json — Structured JSON with typed blocks
• .md — LLM-ready markdown

What AILANG Parse Extracts

OfficeDocBench v2 (87 files, 11 formats, 8 metrics): AILANG Parse PR #116 candidate 98.1% composite with 100.0% coverage. Ten adapters compared, including the hosted Extend (Parse 2.0, 53.3% coverage-adjusted) and LlamaParse (standard mode) APIs. Source-verified structural assertions now measure cell positions, comment targets, list depth, formatting, formulas, colours, and slide/notes relationships. Methodology and results.

Supported Formats

Parsing (16 formats): DOCX, PPTX, XLSX, ODT, ODP, ODS, HTML, Markdown, CSV, EPUB, EML, MBOX, TEX, RTF, PDF, images (JPG/PNG)

Generation (9 formats): DOCX, PPTX, XLSX, ODT, ODP, ODS, HTML, Markdown, QMD (Quarto)

Writing documents in Markdown

Markdown is the input an LLM can write, so it is the practical way to generate a document: write markdown, convert to any of the nine output formats.

docparse report.md --convert report.docx

What survives the trip: YAML front matter (title/author/date → document properties), bold/*italic*/code/~~strike~~ as real character formatting, links as real hyperlinks, images (local paths are read and embedded), fenced code blocks, blockquotes, nested lists, thematic breaks, and tables with alignment and column spans.

Headers, footers, comments and tracked changes have no Markdown syntax; those are preserved when converting from a document that already contains them.

Local document verification (v0.41.2+)

docparse-audit and docparse-render are AILANG companions to the CLI. AILANG Parse v0.41.2 requires AILANG 0.35.0 or newer. They run locally and require no hosted account. The installer links them when present in the installed release; in a checkout use ./bin/docparse-audit and ./bin/docparse-render.

docparse-audit report.docx --strict

docparse-render report.docx --output-dir qa/report docparse-render before.docx --compare after.docx --output-dir qa/comparison

The read-only DOCX audit emits JSON inventories and findings for table grids and headers, heading gaps, image descriptions, links, comments and fields. Exit codes are 0 for a completed audit, 1 for findings with --strict, and 2 for unreadable input. It is a bounded structural check; it does not certify accessibility or resolve arbitrary style inheritance.

Rendering supports .docx, .odt, .pptx, .xlsx and .pdf. Install LibreOffice and Poppler for Office input; PDF needs only Poppler. No new Python dependency is needed. Select tools with --soffice / --pdftoppm (or DOCPARSE_SOFFICE / DOCPARSE_PDFTOPPM). --dpi defaults to 144 and --timeout to 120 seconds per process. The output directory must be new. Each document gets a PDF and numbered PNG pages; the manifest records source hashes, tool paths and page directories. Comparison identifies changed/added/removed pages using uncompressed raster hashes. Inspect the two PNG sets side by side; no diff overlays are generated. visual_review: pending means page images still need inspection.

The implementation is in docparse/services/document_render.ail and docparse/services/docx_audit.ail; regression verification is AILANG too:

ailang run --entry main --caps IO,FS,Env,Process \

--process-allowlist "true,false,mktemp,mkdir,$(command -v soffice),$(command -v pdftoppm)" \ --process-timeout 120s scripts/verify_document_quality.ail -- \ /tmp/docparse-quality-new "$(command -v soffice)" "$(command -v pdftoppm)"

Styling a generated DOCX from a template

--reference-doc is the Quarto/Pandoc reference-doc feature: an existing .docx supplies the look, the Markdown supplies the content.

docparse annex.md --convert annex.docx --reference-doc letterhead.docx

Generated tables use the selected section's usable width, with bounded content weights for columns and repeating semantic headers. Merged-cell widths sum the columns they cover.

The template's styles.xml, numbering.xml, theme, embedded fonts, headers, footers and page setup are applied to the new content. Everything the merge does not regenerate is carried through byte-for-byte, so the letterhead, logo and licensed fonts come out exactly as they went in.

What comes from where:

Two consequences worth knowing:

• The template's headers and footers win. A source document's own headers are dropped rather than mixed with the letterhead. The page furniture all lives in the template's body , which is lifted whole.
• The template's comments are dropped along with its body, and so are commentsExtended.xml and people.xml. Comments in the *source* document still come through.

Two flags refine a multi-section template:

• --reference-section N picks which of the template's sections supplies the page setup, headers and footers — 1 is the first section, Word's numbering. The default is the last section (the body-level one, what the