AGENT SKILL

pdftotext-fallback

Recover PDF text extraction when read_file returns binary data by using pdftotext via shell

使用场景文档处理
License 许可
MIT
最近更新
2026-04-16
Stars
★ 0
Forks
0

01 前言 Front Matter

name
pdftotext-fallback
description
Recover PDF text extraction when read_file returns binary data by using pdftotext via shell

02 资源文件 1

03 SKILL.md 正文

pdftotext Fallback for PDF Text Extraction

When to Use

Apply this pattern when:

  • read_file on a PDF returns binary/image data instead of readable text
  • Python-based PDF extraction (PyMuPDF, pdfplumber, etc.) in execute_code_sandbox fails or returns garbled content
  • You need reliable text extraction from PDF files as a recovery strategy

Why This Works

The pdftotext utility (from poppler-utils) is a mature, command-line tool that handles many PDF edge cases that confuse Python libraries or the read_file tool. It's pre-installed on most Linux systems and provides consistent, reliable text extraction.

Steps

Step 1: Detect the Failure

Recognize extraction failure when:

  • read_file returns binary content, image data, or garbled text
  • Error messages indicate encoding issues or unsupported formats
  • Python PDF libraries in sandbox fail with import errors or extraction failures

Step 2: Use pdftotext via run_shell

Extract to stdout (recommended for quick extraction):

pdftotext /path/to/file.pdf -

The - argument outputs directly to stdout for easy capture in your tool response.

Example:

run_shell("pdftotext document.pdf -")

Step 3: Handle Complex PDFs

Preserve layout (maintains original formatting):

pdftotext -layout /path/to/file.pdf -

Extract to a file (for large PDFs):

pdftotext /path/to/file.pdf /path/to/output.txt

Then read the output file with read_file.

Handle encoded text:

pdftotext -enc UTF-8 /path/to/file.pdf -

Step 4: Verify and Continue

  • Check the extracted text for completeness
  • If text is still garbled, the PDF may be image-based (scanned) - consider OCR tools
  • Proceed with your task using the extracted text

Code Examples

Basic extraction:

# Simple text extraction
text = run_shell("pdftotext document.pdf -")

With error handling:

# Try extraction, check for success
result = run_shell("pdftotext document.pdf - && echo 'SUCCESS' || echo 'FAILED'")

Multi-page PDF with layout:

# Preserve tables and formatting
text = run_shell("pdftotext -layout document.pdf -")

Troubleshooting

Issue Solution
pdftotext: command not found Install poppler-utils: apt-get install poppler-utils
Garbled/special characters Try -enc UTF-8 or -enc ASCII7
Missing formatting Use -layout flag
Scanned PDF (no text) Requires OCR (e.g., tesseract), not text extraction
Large PDF timeout Extract to file instead of stdout

Limitations

  • Does not work on image-only (scanned) PDFs without embedded text
  • May lose complex formatting, tables, or embedded objects
  • Requires poppler-utils to be installed (common on Linux, may need installation on other systems)

Related Tools

  • pdfinfo: Get PDF metadata (pages, size, etc.)
  • pdftoppm: Convert PDF pages to images
  • tesseract: OCR for scanned PDFs

04 同仓库更多 Skills

UF-gzj
UF-gzj/openspace-claude-evolution

write-special-chars-ts-check

Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.

★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

write-special-chars-readback

Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of /tmp helper scripts.

★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

write-special-chars-heredoc

Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) by using a Python heredoc script executed via shell.

★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

worldmonitor-reference

Curated architecture index of the WorldMonitor open-source dashboard. Reference for extracting patterns — vanilla TypeScript, Panel class hierarchy, service layer, CSS grid, API edge functions, refresh scheduler, and 60+ data source integrations.

数据分析师
★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

virtual-list

Implement efficient virtual scrolling for rendering large lists with DOM recycling, chunk-based rendering, and performance optimizations

★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

verify-directory-structure

Diagnose and resolve file access issues by first verifying the directory structure.

★ 0