Paddleocr Doc Parsing

PaddleOCR Document Parsing Skill

When to Use This Skill

Trigger keywords (routing): Bilingual trigger terms (Chinese and English) are listed in the YAML description above—use that field for discovery and routing.

Use this skill for:

• Documents with tables (invoices, financial reports, spreadsheets)
• Documents with mathematical formulas (academic papers, scientific documents)
• Documents with charts and diagrams
• Multi-column layouts (newspapers, magazines, brochures)
• Complex document structures requiring layout analysis
• Any document requiring structured understanding

Do not use for:

• Simple text-only extraction
• Quick OCR tasks where speed is critical
• Screenshots or simple images with clear text

Installation

Scripts declare their dependencies inline (PEP 723). No separate install step is needed — uv resolves dependencies automatically:

uv run scripts/layout_caller.py --help

How to Use This Skill

Working directory: All uv run scripts/... commands below should be run from this skill's root directory (the directory containing this SKILL.md file).

Basic Workflow

1. Identify the input source:

• User provides URL: Use the --file-url parameter
• User provides local file path: Use the --file-path parameter

1. Execute document parsing:

   uv run scripts/layout_caller.py --file-url "URL provided by user" --pretty

Or for local files:

   uv run scripts/layout_caller.py --file-path "file path" --pretty

Optional: explicitly set file type:

   uv run scripts/layout_caller.py --file-url "URL provided by user" --file-type 0 --pretty

• --file-type 0: PDF
• --file-type 1: image
• If omitted, the type is auto-detected from the file extension. For local files, a recognized extension (.pdf, .png, .jpg, .jpeg, .bmp, .tiff, .tif, .webp) is required; otherwise pass --file-type explicitly. For URLs with unrecognized extensions, the service attempts inference.

Performance note: Parsing time scales with document complexity. Single-page images typically complete in 1-5 seconds; large PDFs (50+ pages) may take several minutes. Allow adequate time before assuming a timeout.

Default behavior: save raw JSON to a temp file:

• If --output is omitted, the script saves automatically under the system temp directory
• Default path pattern: <system-temp>/paddleocr/doc-parsing/results/result_<timestamp>_<id>.json
• If --output is provided, it overrides the default temp-file destination
• If --stdout is provided, JSON is printed to stdout and no file is saved
• In save mode, the script prints the absolute saved path on stderr: Result saved to: /absolute/path/...
• In default/custom save mode, read and parse the saved JSON file before responding
• Use --stdout only when you explicitly want to skip file persistence

1. Parse JSON response:

• Check the ok field: true means success, false means error
• The output contains complete document data: text, tables, formulas (LaTeX), figures, seals, headers/footers, and reading order
• Use the appropriate field based on what the user needs:
• text — full document text across all pages
• result.result.layoutParsingResults[n].markdown.text — page-level markdown
• result.result.layoutParsingResults[n].prunedResult — structured layout data with positions and confidence
• Handle errors: If ok is false, display error.message

1. Present results to user:

• Display content based on what the user requested (see "Complete Output Display" below)
• If the content is empty, the document may contain no extractable text
• In save mode, always tell the user the saved file path and that full raw JSON is available there

What to Do After Parsing

Common next steps once you have the structured output:

• Save as Markdown: Write the text field to a .md file — tables, headings, and formulas are preserved
• Extract specific tables: Navigate result.result.layoutParsingResults[n].prunedResult to access individual layout elements with position and confidence data
• Feed to RAG / search pipeline: The text field is structured markdown, ready for chunking and indexing
• Poor results: See "Tips for Better Results" below before retrying

Complete Output Display

Display the COMPLETE extracted content based on what the user asked for. The parsed output is only useful if the user receives all of it — truncation silently drops data.

• If user asks for "all text", show the entire text field
• If user asks for "tables", show ALL tables in the document
• If user asks for "main content", filter out headers/footers but show ALL body text
• Do not truncate with "..." unless content is excessively long (>10,000 chars)
• Do not say "Here's a preview" when user expects complete output

Example - Correct:

User: "Extract all the text from this document"
Agent: I've parsed the complete document. Here's all the extracted text:

[Display entire text field or concatenated regions in reading order]

Document Statistics:
- Total regions: 25
- Text blocks: 15
- Tables: 3
- Formulas: 2
Quality: Excellent (confidence: 0.92)

Example - Incorrect:

User: "Extract all the text"
Agent: "I found a document with multiple sections. Here's the beginning:
'Introduction...' (content truncated for brevity)"

Understanding the Output

The script returns an envelope with ok, text, result, and error. Use text for the full document content; navigate result.result.layoutParsingResults[n] for per-page structured data.

For the complete schema and field-level details, see references/output_schema.md.

Raw result location (default): the temp-file path printed by the script on stderr

Alternative: paddleocr CLI

This mirror keeps the bundled scripts/layout_caller.py as the default path. The upstream PaddleOCR project (since PR #18090, 2026-06-03) also ships an official CLI that calls the same API directly. If the paddleocr package is installed, you can use it as a drop-in alternative — no uv run or local scripts required.

Install (one-time):

pip install "paddleocr>=3.7.0"

Environment: the CLI only needs PADDLEOCR_ACCESS_TOKEN. It resolves the API endpoint internally, so PADDLEOCR_DOC_PARSING_API_URL is not required when using the CLI (the URL is still required by the script).

Basic document parsing:

# From URL
paddleocr api --model_type doc_parsing --file_url "https://example.com/report.pdf"

# From local file
paddleocr api --model_type doc_parsing --file_path "./document.pdf"

Common options:

# Specific model
paddleocr api --model_type doc_parsing --model PP-StructureV3 --file_path "./report.pdf"

# Disable preprocessing (faster, for flat/well-oriented images)
paddleocr api --model_type doc_parsing --file_path "./document.pdf" \
  --use_doc_unwarping False --use_doc_orientation_classify False

# Page ranges (replaces split_pdf.py for most cases)
paddleocr api --model_type doc_parsing --file_path "./large.pdf" --page_ranges "1-5,10,15-20"

# Save result and extracted resources (images)
paddleocr api --model_type doc_parsing --file_url "https://..." \
  --output result.json --save_resources ./resources

# Prettify markdown output
paddleocr api --model_type doc_parsing --file_path "./document.pdf" --prettify_markdown True

CLI output format — different from the script envelope:

{
  "jobId": "job-xxx",
  "pages": [
    {
      "markdownText": "# Title\n\nContent...",
      "markdownImages": { "img1": "https://...", "img2": "https://..." },
      "outputImages": { "layout1": "https://..." }
    }
  ]
}