PDF Parsing API

PDFs Have No Semantic Structure

A PDF encodes where to draw glyphs on a page. It has no concept of "heading", "paragraph", or "table cell". Extracting document structure from PDF requires visual understanding — recognizing that larger bold text at the top of a page is a heading, that aligned columns of text form a table, that reading order flows left-to-right then top-to-bottom.

AILANG Parse delegates this visual understanding to the AI provider of your choice, then normalizes the output into the same Block ADT used for DOCX, XLSX, and PPTX parsing. Your downstream code handles all formats identically.

How It Works

AILANG Parse sends the PDF to the configured AI provider with a structured extraction prompt. The AI returns content in a normalized format, which AILANG Parse validates and converts into typed blocks. The result is the same Block ADT — headings, text, tables, images — regardless of which AI provider performed the extraction.

Switch providers with a single flag. No code changes, no output format differences.

# Gemini (fastest, most cost-effective)
ailang run --entry main --caps IO,FS,Env,AI --ai gemini-2.5-flash \
  docparse/main.ail document.pdf

# Claude
ailang run --entry main --caps IO,FS,Env,AI --ai claude-sonnet-4-5-20250514 \
  docparse/main.ail document.pdf

# Ollama (fully local)
ailang run --entry main --caps IO,FS,Env,AI --ai ollama/llama3.2-vision \
  docparse/main.ail document.pdf

AI Providers

Local Deterministic Backends v0.19+

As of v0.19.0, the CLI can dispatch PDF parsing to local backends instead of an AI provider. Two options ship today:

Both run as Python subprocesses dispatched from inside AILANG via the sunholo/external_backend package, with typed error handling and stderr capture. Selection is per call — there's no global config to drift.

Install

The ai backend works out of the box. The local backends need their Python package installed in the same Python environment your CLI uses:

# Docling (see docling-project/docling for the full install matrix)
uv pip install docling

# LiteParse (see run-llama/liteparse)
uv pip install liteparse

# Or both
uv pip install docling liteparse

No service to run, no daemon to start — both adapters launch on demand when you pass --pdf-backend docling or --pdf-backend liteparse. If the package isn't installed, the adapter exits non-zero and AILANG surfaces a typed NonZeroExit error with the underlying ImportError captured from stderr.

Usage

# AI (default — unchanged behavior)
./bin/docparse paper.pdf --pdf-backend ai --ai gemini-2.5-flash

# Docling — local, structural, ~5× faster than Gemini
./bin/docparse paper.pdf --pdf-backend docling

# LiteParse — local, fastest text extraction (~40× faster than AI end-to-end)
./bin/docparse paper.pdf --pdf-backend liteparse

Output is the same Block ADT — your pipeline code doesn't change when you switch backend. When --pdf-backend is anything other than ai, AILANG drops the AI capability and swaps in Process — no API key required, no network calls.

Which Backend to Pick

What Gets Extracted

Local Processing with Ollama

For sensitive documents that can't leave your network, use Ollama as the AI backend. Install Ollama, pull a vision-capable model, and point AILANG Parse at it. Zero cloud calls.

# Install Ollama and pull a vision model
ollama pull llama3.2-vision

# Parse PDF fully locally
ailang run --entry main --caps IO,FS,Env,AI \
  --ai ollama/llama3.2-vision \
  docparse/main.ail confidential-report.pdf

The output format is identical to cloud providers. You can develop locally with Ollama and deploy to production with Gemini or Claude — same code, same output structure.

Use Cases

Try It

CLI

# Parse with Gemini (set GOOGLE_API_KEY)
GOOGLE_API_KEY="your-key" ailang run --entry main \
  --caps IO,FS,Env,AI --ai gemini-2.5-flash \
  docparse/main.ail report.pdf

# Parse with Ollama (fully local)
ailang run --entry main --caps IO,FS,Env,AI \
  --ai ollama/llama3.2-vision \
  docparse/main.ail report.pdf

API

curl -X POST https://docparse.ailang.sunholo.com/api/v1/parse \
  -H "Content-Type: application/json" \
  -d '{"filepath":"sample_pdf","outputFormat":"markdown","apiKey":"YOUR_API_KEY","ai":"gemini-2.5-flash"}'

Python SDK

from ailang_parse import DocParse

client = DocParse(api_key="YOUR_API_KEY")

# Parse with AI provider
result = client.parse("report.pdf", output_format="json", ai="gemini-2.5-flash")

# Same Block ADT as Office formats
for block in result.blocks:
    if block.type == "table":
        print(f"Table: {len(block.rows)} rows")
    if block.type == "heading":
        print(f"H{block.level}: {block.text}")

Parse in Browser    API Reference