robust-pdf-read
Reliably extract text from PDFs using pdftotext when standard file reading fails.
- License 许可
- MIT
- 最近更新
- 2026-04-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- robust-pdf-read
- category
- tool_guide
- description
- Reliably extract text from PDFs using pdftotext when standard file reading fails.
02 资源文件 1
- 其他.skill_id29 B
03 SKILL.md 正文
Robust PDF Text Extraction
Problem
Standard file reading tools (e.g., read_file) often fail to extract text from PDF documents. Instead of returning parsed text, they may return:
- Raw binary data
- Base64 encoded images
- Garbled characters or null bytes
This occurs because PDFs are complex binary formats, not plain text files. Attempts to parse them using general-purpose Python libraries (like PyMuPDF) in sandboxed environments may also fail due to missing dependencies or environment restrictions.
Solution
Use the pdftotext command-line utility (part of poppler-utils) via run_shell. This tool is commonly pre-installed in Linux environments and reliably extracts text content from PDFs.
Procedure
1. Detect Extraction Failure
When attempting to read a PDF:
- Check the content returned by
read_file. - If the content contains null bytes (
\x00), appears as base64, or is clearly binary/garbled, assume standard reading has failed.
2. Execute pdftotext
Run the following shell command using run_shell:
pdftotext -layout -nopgbrk <file_path> -
-layout: Maintains the physical layout of the text (optional but recommended).-nopgbrk: Prevents inserting form feed characters between pages.-: Outputs content to stdout instead of creating a new file.
3. Parse Output
Capture the stdout from the shell command. This string is the extracted text.
Example Usage
Scenario: You need to read document.pdf.
Step 1: Attempt standard read
content = read_file("document.pdf")
if "\x00" in content or not content.strip():
# Fallback needed
pass
Step 2: Fallback to shell
result = run_shell("pdftotext -layout -nopgbrk document.pdf -")
text = result.stdout
Prerequisites
- The environment must have
pdftotextinstalled (usually viapoppler-utils). - If
pdftotextis not found, attempt to install it (apt-get install poppler-utils) if permissions allow, or notify the user.
Benefits
- Reliability: Bypasses Python library dependency issues in sandboxes.
- Speed: Command-line tools are often faster than loading heavy Python libraries.
- Compatibility: Works consistently across most Linux-based agent environments.
04 同仓库更多 Skills
zip-export-deliverable
Ensures codebase deliverables are properly exported as ZIP archives through a dedicated finalization step
zip-deliverable-finalization
Ensure codebase deliverables are properly packaged as ZIP exports in a dedicated final step
zero-iteration-failure-analysis
Identify and handle agent failures with 0 iterations as pre-execution system issues
write-file-fallback-report
Generate professional documents using write_file when primary data sources fail, leveraging embedded domain knowledge instead of external retrieval
fallback-doc-with-delegation
Generate professional documents after tool failures using shell_agent for complex formats or write_file for simple text/markdown
context-anchored-fallback-report
Generate documents with write_file when retrieval tools fail, with explicit guardrails against task context drift