AGENT SKILL

pdftotext-fallback

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

使用场景文档处理
License 许可
MIT
所属仓库
HKUDS/AgentPilot
最近更新
2026-11-12
Stars
★ 8.0k
Forks
944

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

HKUDS
HKUDS/AgentPilot

agentpilot

Set up AgentPilot and use its single entry to prepare missing inputs and run configured RSI experiments. Use when the user requests AgentPilot installation or work with AgentPilot.

★ 8.0k
HKUDS
HKUDS/AgentPilot

remember

Review auto-memory entries and propose promotions to OPENSPACE.md, OPENSPACE.local.md, or retained auto-memory topics; detect duplicates, stale facts, conflicts, and ambiguous entries before making changes.

★ 8.0k
HKUDS
HKUDS/AgentPilot

skill-discovery

Search reusable OpenSpace skills locally, and browse cloud packages step by step when a cloud skill may help. Reusing proven skills saves tokens, improves reliability, and extends your capabilities beyond built-in tools.

Skill与智能体开发
★ 8.0k
HKUDS
HKUDS/AgentPilot

delegate-task

Delegate tasks to OpenSpace — a full-stack autonomous worker for coding, DevOps, web research, and desktop automation, backed by an extensive MCP tool and skill library. Skills auto-improve through use, reducing token consumption over time. A cloud community lets agents share and collectively evolve reusable skills.

Skill与智能体开发
★ 8.0k
HKUDS
HKUDS/AgentPilot

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.

★ 8.0k
HKUDS
HKUDS/AgentPilot

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.

★ 8.0k