uniparser-tools

name

uniparser-tools

description

Parse PDFs, document images, and public PDF URLs into structured Markdown via UniParser (https://uniparser.dp.tech/) — tables, equations as LaTeX, figures, and reading order. Use when the user wants to parse or extract a document, paper, patent, report, or PDF/image/URL into Markdown. Trigger terms: UniParser, uniparser_tools, 文档解析, PDF解析, 论文解析, 专利解析, PDF转Markdown, 表格提取, 公式识别, 化学分子, scientific paper, layout extraction, dp.tech, document parsing.

UniParser-Tools Skill

Parse local PDFs, document images, and public PDF URLs into Markdown and structured layout JSON via UniParser. Agents use the installed uniparser CLI—do not hand-write SDK code for the default workflow.

Installation

Requires Python 3.11+. Install into the same Python environment that runs uniparser:

pip install "git+https://github.com/dptech-corp/UniParser-Tools.git"

PyPI is not published yet; use the git install above (no automatic pip install—if missing, exit with this command).

Verify:

uniparser --help
uniparser version

If uniparser is not found, the package is not installed in the active environment (no automatic pip install—exit with install guidance).

Configuration

All requests use https://uniparser.dp.tech/. An API key is mandatory (HTTP header X-API-Key).

Key sources (highest priority first):

1. uniparser --api-key YOUR_KEY … (one-off)
2. Environment variable UNIPARSER_API_KEY
3. ~/.uniparser/config.yaml (written by uniparser auth)

Interactive setup (user machines)

uniparser auth

Apply for a key at https://uniparser.dp.tech/ if needed. Prefer not pasting keys into chat.

Agent pre-check

Before parsing, verify a key is configured:

uniparser auth --verify

• Exit code 0 → continue.
• Exit code 1 → stop; guide the user to uniparser auth or set UNIPARSER_API_KEY, then restart the terminal or Cursor.

Alternative (env only):

python3 -c "import os, sys; sys.exit(0 if os.getenv('UNIPARSER_API_KEY') else 1)"

macOS / Linux:

export UNIPARSER_API_KEY="your-api-key"

Windows (PowerShell):

$env:UNIPARSER_API_KEY="your-api-key"

Usage

CLI reference

Pipeline: submit → poll get_result until success → fetch pages_tree + Markdown → save. Default sync=true (trigger blocks until server done; CLI still polls and fetches). --async uses sync=false on submit only.

Input: one positional INPUT per run—the CLI detects type by path suffix or http(s):// URL:

• Local PDF → uniparser parse "/path/to/document.pdf"
• Local image (.png, .jpg, …) → uniparser parse "/path/to/figure.png"
• Public PDF URL → uniparser parse "https://example.com/paper.pdf"

uniparser parse "/path/to/document.pdf"
uniparser parse "/path/to/figure.png"
uniparser parse "https://example.com/paper.pdf"

Optional flags:

uniparser parse "./paper.pdf" -o "./results"
uniparser parse "./paper.pdf" --async
uniparser parse "./paper.pdf" --overwrite

Recovery (existing server job—see Common issues):

uniparser fetch --token "TASK_TOKEN_FROM_PRIOR_RUN"

Token sources: stdout JSON from a prior uniparser --json parse …, trigger_meta.json under the output directory, or the token field in a failed parse stderr JSON.

Default output for fetch (when -o / --output-dir is omitted): ~/Uni-Parser-Skill/token_<prefix>/, where <prefix> is the first 8 characters of the token (e.g. ~/Uni-Parser-Skill/token_a1b2c3d4/token_a1b2c3d4.md). To write into the same directory as a prior parse, pass -o explicitly (e.g. -o ~/Uni-Parser-Skill/paper/).

Default output for parse (when -o / --output-dir is omitted): ~/Uni-Parser-Skill/<source_stem>/

<source_stem> = local file stem (paper.pdf → paper); for URLs, the last path segment with only .pdf/image suffix removed (…/2606.05847 → 2606.05847, not 2606).

Files written on success:

• pages_tree.json — structured layout tree
• {stem}.md — full document Markdown
• formatted_meta.json — metadata without full content
• trigger_meta.json — task token and trigger_kwargs (for uniparser fetch recovery)

Deliver to user: open {stem}.md for full text; give the user the path and/or content. Mention pages_tree.json when layout structure matters. For reliable path extraction, prefer machine-readable output:

uniparser --json parse "/path/to/document.pdf"

Then read stdout JSON fields markdown_path, pages_tree_path, output_dir, and token.

Parse options (CLI flags; defaults match scientific-paper preset):

Field	Flag	Default
Text	--textual	ocr-hq
Equation	--equation	ocr-hq
Table	--table	ocr-hq
Chart	--chart	base64
Figure	--figure	base64
Chemical expression	--expression	base64
Molecule	--molecule	ocr-fast

Choices: disable, ocr-fast, ocr-hq, digital (textual only), base64. sync=true by default (--async for sync=false).

Example:

uniparser parse paper.pdf --textual digital --molecule disable

I/O contract

Outcome	Exit code	stdout	stderr
Success (human mode)	0	Human-readable paths	Progress (Parsing... filename)
Success (--json)	0	Single JSON object (ok: true)	Progress (same as above)
Failure	1	(empty or unused)	Single JSON line (ok: false, error.code, error.message)

--json must appear before the subcommand:

uniparser --json parse paper.pdf    # correct
uniparser parse paper.pdf --json    # wrong

parse success JSON fields (uniparser --json parse INPUT):

Field	Meaning
ok	true on success
output_dir	Result directory (absolute path)
markdown_path	Main Markdown file
pages_tree_path	Layout tree JSON
content_chars	Markdown body length
token	Task token for uniparser fetch --token
input_type	file / image / url
trigger_meta_path	Path to trigger_meta.json

Common error codes (stderr JSON): CONFIG_ERROR, INPUT_ERROR, DIR_EXISTS, PARSE_ERROR.

Common issues

On failure, show stderr JSON error.message. Do not substitute vision-only reading for UniParser output.

Problem	Cause	Solution
CONFIG_ERROR	No API key or uniparser not installed	Configuration + pip install "git+https://github.com/dptech-corp/UniParser-Tools.git"; uniparser auth --verify
DIR_EXISTS	Output directory already exists	Ask user; re-run with --overwrite if they agree
Token is duplicated	Job for this API key + exact input already exists	Do not re-run uniparser parse. Read token from stderr JSON or trigger_meta.json; run uniparser fetch --token TOKEN
Job not done / long wait / CLI interrupted / processing / poll timeout	Sync or poll still running; or local process stopped while server job continues	Wait; do not start a second uniparser parse for the same input. Use saved token with uniparser fetch --token TOKEN; files appear only after exit 0
502 Bad Gateway on URL input	Server failed fetching or processing remote PDF	Retry uniparser parse "same url" once; or download and uniparser parse local.pdf; or uniparser fetch --token TOKEN if a prior job exists
PARSE_ERROR	Server status: error at trigger / poll / fetch	Read error.message and stage; match rows above; check trigger_error.json / pages_tree_error.json / formatted_error.json under output dir if present

Limits: large PDFs may take 10–20+ minutes; public service ≤5 concurrent requests (Important notes); PDF URLs must be publicly accessible. Save token from success JSON or trigger_meta.json for recovery after interrupt or duplicate-token errors.

Advanced

For callbacks, custom ParseMode, or SDK examples, see Common patterns and API reference.

Full CLI reference (flags, examples, JSON details): CLI README in this repository.

Optional MCP server setup is in the UniParser-Tools GitHub repo; it is separate from this CLI workflow.

Reference documents

Topic	File
API reference	api-reference.md
Common patterns	patterns.md
Data classes	data-classes.md
Layout types	layout-types.md
Utilities	utilities.md
Important notes	notes.md