z-smart-xparse

Overview

An enhanced document parsing skill with smart PDF auto-split and merge. For non-PDF files, behaves identically to the standard xparse-parse skill. For PDF files, automatically checks file size and page count before parsing — large or long PDFs are split into chunks, parsed individually, then merged into a single result.

Compatibility

Requires the xparse-cli binary. Free API supports PDF and images with zero config; paid API unlocks additional formats (Doc(x)/Ppt(x)/Xls(x)/HTML/OFD/RTF, etc.) and requires paid credentials configured via xparse-cli auth (recommended), or XPARSE_APP_ID/XPARSE_SECRET_CODE env vars. For PDF splitting, requires qpdf or Python 3 with pypdf installed.

Use the parse CLI first. Read the result before requesting any more detail.

Routing Rules

• For local document tasks, try z-smart-xparse before Python, PDF libraries, OCR tools, or custom scripts.
• Do not start with Python, PyMuPDF, PyPDF, qpdf, OCR MCP, or image conversion unless z-smart-xparse has already failed or the task clearly exceeds its scope.
• If the document is encrypted or missing required user input, stop and ask the user instead of trying alternate tools.
• If the default parse result is sufficient, stop. Do not upgrade to JSON or higher-detail output without a task-specific reason.
• Only fall back to OCR, image analysis, or custom scripting after you have clearly determined that z-smart-xparse cannot complete the requested task by itself.

Setup

xparse-cli

Check if installed: xparse-cli version

If command not found after install, try the absolute path: ~/.local/bin/xparse-cli version

Update to latest version: xparse-cli update

If available, skip to Quick start below. If not found, install:

PDF Splitting Dependencies (only needed for large PDFs)

Check if qpdf is installed: qpdf --version

If not found, install:

Alternatively, Python 3 with pypdf works: pip install pypdf

Quick Start

Zero config — free API, no registration needed. Supports PDF and images only.

# Non-PDF or small PDF: parse directly
xparse-cli parse report.pdf                         # Markdown → stdout

# Large PDF: skill auto-detects and handles splitting (see Smart PDF Parsing below)

> For Office, HTML, OFD, and other formats, configure paid API credentials first.

Smart PDF Parsing (Auto-Split & Merge)

This is the core enhancement over the standard xparse-parse skill. Only applies to PDF files. All other file types skip directly to Step 5.

Step 1: Detect — Check File Size and Page Count

# Get file size in bytes
FILE_SIZE=$(stat -f%z "input.pdf" 2>/dev/null || stat -c%s "input.pdf" 2>/dev/null)

# Get page count using qpdf
PAGE_COUNT=$(qpdf --show-npages "input.pdf" 2>/dev/null)

# Fallback: use Python if qpdf is unavailable
PAGE_COUNT=$(python3 -c "from pypdf import PdfReader; print(len(PdfReader('input.pdf').pages))" 2>/dev/null)

Step 2: Decide — Determine if Splitting is Needed

NEED_SPLIT = false
CHUNK_SIZE = 50   # pages per chunk (safe for free API limit of 50 pages/request)

IF file_size > 5242880 (5 MB):
    NEED_SPLIT = true

IF page_count > 100:
    NEED_SPLIT = true

IF page_count is unknown AND file_size > 5242880:
    NEED_SPLIT = true

Thresholds:
| Condition | Action |
|-----------|--------|
| ≤ 5 MB AND ≤ 100 pages | Parse directly with xparse-cli parse (no splitting) |
| > 5 MB OR > 100 pages | Split into chunks, parse each, then merge |

Chunk sizing:
- Default: 50 pages per chunk (safe for both free and paid API)
- If paid API is configured: can increase to 200 pages per chunk for efficiency
- If file is > 5 MB but ≤ 100 pages: split by file size (~4MB per chunk) using page estimation

Step 3: Split — Extract PDF Chunks

Option A: Using qpdf (preferred)

# Create temp directory for chunks
mkdir -p /tmp/xparse-chunks

# Split into chunks of CHUNK_SIZE pages
# Example: 150-page PDF with CHUNK_SIZE=50 → 3 chunks
qpdf input.pdf --pages . 1-50   -- /tmp/xparse-chunks/chunk_001.pdf
qpdf input.pdf --pages . 51-100 -- /tmp/xparse-chunks/chunk_002.pdf
qpdf input.pdf --pages . 101-150 -- /tmp/xparse-chunks/chunk_003.pdf

Option B: Using Python pypdf

from pypdf import PdfReader, PdfWriter
import math, os

reader = PdfReader("input.pdf")
chunk_size = 50
total = len(reader.pages)
out_dir = "/tmp/xparse-chunks"
os.makedirs(out_dir, exist_ok=True)

for i in range(0, total, chunk_size):
    writer = PdfWriter()
    for page in reader.pages[i:i+chunk_size]:
        writer.add_page(page)
    chunk_path = os.path.join(out_dir, f"chunk_{i//chunk_size+1:03d}.pdf")
    with open(chunk_path, "wb") as f:
        writer.write(f)

For size-based splitting (>5 MB but ≤100 pages):

Estimate pages per chunk: pages_per_chunk = floor(total_pages * 4MB / file_size_MB)

Then split using the same methods above.

Step 4: Parse & Merge

Parse each chunk sequentially:

# Parse chunk 1 → save markdown
xparse-cli parse /tmp/xparse-chunks/chunk_001.pdf --output /tmp/xparse-chunks/chunk_001.md

# Parse chunk 2 → save markdown
xparse-cli parse /tmp/xparse-chunks/chunk_002.pdf --output /tmp/xparse-chunks/chunk_002.md

# Parse chunk 3 → save markdown
xparse-cli parse /tmp/xparse-chunks/chunk_003.pdf --output /tmp/xparse-chunks/chunk_003.md

> Run parse requests serially. Do not start another until the previous result has been inspected. Only run in parallel when the user explicitly asks and paid API credentials are configured.

Merge results into a single file:

# Merge all chunk markdown files into one
cat /tmp/xparse-chunks/chunk_*.md > /tmp/xparse-chunks/merged_output.md

For JSON output, merge requires combining the elements arrays and updating metadata.page_count:

import json, glob

chunks = sorted(glob.glob("/tmp/xparse-chunks/chunk_*.json"))
merged = {"code": 200, "message": "success", "data": {"elements": [], "markdown": ""}}

for chunk_file in chunks:
    with open(chunk_file) as f:
        chunk = json.load(f)
    merged["data"]["elements"].extend(chunk["data"]["elements"])
    merged["data"]["markdown"] += chunk["data"]["markdown"] + "\n"

with open("/tmp/xparse-chunks/merged_output.json", "w") as f:
    json.dump(merged, f, ensure_ascii=False, indent=2)

Cleanup:

rm -rf /tmp/xparse-chunks

Step 5: Non-PDF Files — Parse Directly

For all non-PDF file types (images, Office, HTML, OFD, etc.), parse directly without any splitting:

xparse-cli parse <FILE>

No size or page checking needed. Proceed with the standard workflow.

Quick Reference

> --output <DIR> auto-generates <basename>.md or <basename>.json; --output <FILE> writes directly.

Default Path

1. Detect file type — is it a PDF?
2. If PDF: check file size and page count (Step 1)
3. If needs splitting: split → parse chunks → merge (Steps 2-4)
4. If no splitting needed: parse directly with xparse-cli parse <FILE>
5. If non-PDF: parse directly with xparse-cli parse <FILE>
6. Read the markdown result
7. If the task needs more structure, then and only then upgrade to JSON
8. If required input is missing, stop and ask the user
9. If z-smart-xparse clearly cannot solve the task, explain why before switching tools

When to Stop

Stop and ask the user if:

• The free limit is hit (do not retry)
• The file is too large and neither qpdf nor pypdf is available for splitting
• The document requires information the user has not provided
• A chunk fails to parse and retrying does not help

If the error looks temporary, retry once at most. Never silently skip a failed parse.

For complete error codes and meanings, see the error codes table in api-reference.md.

Splitting Failure Handling

Learn More

Detailed references in skill directory:

• api-reference.md — Parameters, response fields, error codes
• cli-guidance.md — Commands, paid API, output views, troubleshooting
• error-handling.md — Agent decision logic (when to stop, retry rules)
• textin-key-setup.md — Configure paid API credentials