pdf-text-extraction-fallback
Extract text from PDFs using pdftotext when read_file returns binary data
- License 许可
- MIT
- 所属仓库
- HKUDS/AgentPilot
- 最近更新
- 2026-11-12
- Stars
- ★ 8.0k
- Forks
- 944
01 前言 Front Matter
- name
- pdf-text-extraction-fallback
- description
- Extract text from PDFs using pdftotext when read_file returns binary data
02 资源文件 1
- 其他.skill_id42 B
03 SKILL.md 正文
PDF Text Extraction Fallback
When to Use This Skill
Use this skill when read_file with filetype="pdf" returns binary/image data instead of readable text content. This is a common issue with PDF files that contain embedded images or complex formatting.
Steps
1. Validate Parameters First
Before attempting extraction, ensure you're using the correct parameter name:
- Use
filetype(notfile_type) for theread_filefunction - Incorrect parameter names can cause silent failures
# Correct
read_file(filetype="pdf", file_path="document.pdf")
# Incorrect - may fail silently
read_file(file_type="pdf", file_path="document.pdf")
2. Detect Binary Data Issue
After calling read_file, check if the result contains:
- Garbled/binary characters
- Image data representations (e.g.,
b'...'byte strings with non-text content) - Unreadable or corrupted-looking content
If yes, proceed with the pdftotext workaround.
3. Extract Text via pdftotext
Use run_shell to call pdftotext, which extracts text directly from PDF files:
# Extract text to stdout
result = run_shell(command="pdftotext /path/to/document.pdf -")
text_content = result.stdout
The - flag tells pdftotext to output to stdout instead of creating a file.
4. Handle Output and Errors
result = run_shell(command="pdftotext /path/to/document.pdf -")
if result.stderr:
# Check for errors like "pdftotext not found"
# May need to install poppler-utils
pass
text_content = result.stdout
# text_content now contains the extracted text
Example Workflow
# Step 1: Try normal read with correct parameters
content = read_file(filetype="pdf", file_path="reference.pdf")
# Step 2: Check if content is readable
if not content or looks_like_binary(content):
# Step 3: Fall back to pdftotext
result = run_shell(command="pdftotext reference.pdf -")
text_content = result.stdout
# Step 4: Verify extraction succeeded
if result.stderr:
# Handle error (e.g., install pdftotext)
pass
Installation Notes
pdftotext is part of the poppler-utils package:
- Debian/Ubuntu:
apt-get install poppler-utils - macOS:
brew install poppler - Many Linux environments: Pre-installed
Alternative: Output to File
If stdout approach has issues, output to a temporary file:
run_shell(command="pdftotext /path/to/document.pdf /tmp/output.txt")
text_content = read_file(filetype="txt", file_path="/tmp/output.txt")
Best Practices
- Always validate the
filetypeparameter spelling before troubleshooting - Check both stdout and stderr from pdftotext
- For multi-page PDFs, pdftotext preserves page breaks with form feeds
- This method works better for text-based PDFs than image-scanned PDFs
04 同仓库更多 Skills
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.
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.
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.
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.
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.
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.