• 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

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

1. ONLY use PaddleOCR Document Parsing API - Execute the script

   python scripts/vl_caller.py

2. NEVER use Claude's built-in vision - Do NOT parse documents yourself
3. NEVER offer alternatives - Do NOT suggest "I can try to analyze it" or similar
4. IF API fails - Display the error message and STOP immediately
5. NO fallback methods - Do NOT attempt document parsing any other way

• Show the error message to the user
• Do NOT offer to help using your vision capabilities
• Do NOT ask "Would you like me to try parsing it?"
• Simply stop and wait for user to fix the configuration

1. Execute document parsing:
   bash

   python scripts/vl_caller.py --file-url "URL provided by user"

   Or for local files:
   bash

   python scripts/vl_caller.py --file-path "file path"

   Save result to file (recommended):
   bash

   python scripts/vl_caller.py --file-url "URL" --output result.json --pretty

   • The script will display:

     Result saved to: /absolute/path/to/result.json

   • This message appears on stderr, the JSON is saved to the file
   • Tell the user the file path shown in the message
2. The script returns COMPLETE JSON with all document content:
   • Headers, footers, page numbers
   • Main text content
   • Tables with structure
   • Formulas (with LaTeX)
   • Figures and charts
   • Footnotes and references
   • Seals and stamps
   • Layout and reading order
3. Extract what the user needs from the complete data based on their request.

• The script returns ALL document content in a structured format
• Display the full content requested by the user, do NOT truncate or summarize
• 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: Display complete text, all tables, all formulas as requested
• ✅ DO: Present content in reading order using

  reading_order

  array
• ❌ DON'T: Truncate with "..." unless content is excessively long (>10,000 chars)
• ❌ DON'T: Summarize or provide excerpts when user asks for full content
• ❌ DON'T: Say "Here's a preview" when user expects complete output

User: "Extract all the text from this document"
Claude: 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)

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

{
  "ok": true,
  "text": "Full markdown/HTML text extracted from all pages",
  "result": [
    {
      "prunedResult": {
        "parsing_res_list": [
          {"block_label": "text", "block_content": "Paragraph text content here...", "block_bbox": [100, 200, 500, 230], "block_id": 3},
          {"block_label": "table", "block_content": "<table>...</table>", "block_bbox": [50, 300, 900, 600], "block_id": 5},
          {"block_label": "seal", "block_content": "<img .../>", "block_bbox": [400, 50, 600, 180], "block_id": 2}
        ]
      },
      "markdown": {
        "text": "Full page content in markdown/HTML format",
        "images": {"imgs/filename.jpg": "https://..."}
      }
    }
  ],
  "error": null
}

• text

  — extracted markdown text from all pages (use this for quick text display)

• result

  — raw API result array (one object per page), for detailed block-level access

• result[n].prunedResult.parsing_res_list

  — array of detected content blocks

• result[n].markdown.text

  — full page content in markdown/HTML

python scripts/vl_caller.py \
  --file-url "https://example.com/paper.pdf" \
  --pretty

• Include: text, table, formula, figure, footnote
• Exclude: header, footer, page_number

python scripts/vl_caller.py \
  --file-path "./financial_report.pdf" \
  --pretty

• Only keep regions where type="table"
• Present table content in markdown format

python scripts/vl_caller.py \
  --file-url "URL" \
  --pretty

text

Configuration error: API not configured. Get your API at: https://paddleocr.com

1. Show the exact error message to user (including the URL)
2. Tell user to provide credentials:

   Please visit the URL above to get your PADDLEOCR_DOC_PARSING_API_URL and PADDLEOCR_ACCESS_TOKEN.
   Once you have them, send them to me and I'll configure it automatically.

3. When user provides credentials (accept any format):

   • PADDLEOCR_DOC_PARSING_API_URL=https://xxx.com/layout-parsing, PADDLEOCR_ACCESS_TOKEN=abc123...

   • Here's my API: https://xxx and token: abc123

   • Copy-pasted code format
   • Any other reasonable format
4. Parse credentials from user's message:
   • Extract PADDLEOCR_DOC_PARSING_API_URL value (look for URLs)
   • Extract PADDLEOCR_ACCESS_TOKEN value (long alphanumeric string, usually 40+ chars)
5. Configure automatically:
   bash

   python scripts/configure.py --api-url "PARSED_URL" --token "PARSED_TOKEN"

6. If configuration succeeds:
   • Inform user: "Configuration complete! Parsing document now..."
   • Retry the original parsing task
7. If configuration fails:
   • Show the error
   • Ask user to verify the credentials

• The script NEVER filters content - It always returns complete data
• Claude decides what to present - Based on user's specific request
• All data is always available - Can be re-interpreted for different needs
• No information is lost - Complete document structure preserved

• references/output_schema.md

  - Output format specification

• references/provider_api.md

  - Provider API contract

Note: Model version and capabilities are determined by your API endpoint (PADDLEOCR_DOC_PARSING_API_URL).

• Debugging complex parsing issues
• Need to understand output format
• Working with provider API details