AGENT SKILL

pdf-text-extraction-9424c5

Extract text from PDF files using pdftotext when read_file returns binary data

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

01 前言 Front Matter

name
pdf-text-extraction-9424c5
description
Extract text from PDF files using pdftotext when read_file returns binary data

02 资源文件 1

03 SKILL.md 正文

PDF Text Extraction via pdftotext

Problem

When using read_file on PDF documents, the function may return binary image data or garbled content instead of readable text. This occurs because PDFs can contain scanned images or complex binary structures that read_file cannot properly parse as text.

Solution

Use the pdftotext command-line utility via run_shell to extract clean text content from PDF files.

Steps

1. Verify PDF file exists

import os

pdf_path = "path/to/document.pdf"
if not os.path.exists(pdf_path):
    raise FileNotFoundError(f"PDF not found: {pdf_path}")

2. Extract text using pdftotext

from tools import run_shell

# Extract text to stdout
result = run_shell(command=f"pdftotext '{pdf_path}' -", timeout=60)
pdf_text = result.stdout

# Alternative: extract to a temporary file
temp_txt = "/tmp/extracted.txt"
run_shell(command=f"pdftotext '{pdf_path}' '{temp_txt}'", timeout=60)
with open(temp_txt, 'r') as f:
    pdf_text = f.read()

3. Handle parameter naming carefully

When calling read_file, be aware of the parameter name:

  • Use filetype="pdf" (not file_type)
  • Some tool implementations may use different parameter names
# Correct parameter usage
content = read_file(file_path="doc.pdf", filetype="pdf")

# If this returns binary/garbled data, fall back to pdftotext

Common pdftotext Options

Option Description
- Output to stdout
-layout Maintain original layout
-f <n> Start from page n
-l <n> End at page n
-q Quiet mode

Example with options:

result = run_shell(command=f"pdftotext -layout -q '{pdf_path}' -", timeout=60)

Error Handling

from tools import run_shell

def extract_pdf_text(pdf_path):
    """Extract text from PDF using pdftotext with error handling."""
    import os
    
    if not os.path.exists(pdf_path):
        raise FileNotFoundError(f"PDF not found: {pdf_path}")
    
    result = run_shell(command=f"pdftotext '{pdf_path}' -", timeout=60)
    
    if result.returncode != 0:
        raise RuntimeError(f"pdftotext failed: {result.stderr}")
    
    return result.stdout.strip()

When to Use This Pattern

  • read_file returns binary data, garbled text, or image content for a PDF
  • You need searchable/processable text from PDF documents
  • The PDF contains text (not just scanned images - for those, consider OCR tools)

Prerequisites

  • pdftotext must be installed (part of poppler-utils on Debian/Ubuntu, poppler on macOS via Homebrew)
  • Verify availability: run_shell(command="which pdftotext")

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