Multi-stage fallback strategy for PDF/document extraction using sequential tool alternatives
73%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./benchmarks/gdpval/skills/pdf-extraction-fallback/SKILL.mdWhen processing documents (especially PDFs), initial extraction attempts may fail due to formatting, encryption, or tool limitations. This skill provides a systematic fallback approach that tries multiple extraction methods before declaring failure.
Never declare completion after a single tool failure. Instead, iterate through a hierarchy of extraction methods, each with different capabilities and limitations.
Attempt extraction methods in this order:
Try native PDF libraries first (fastest, preserves structure):
import PyPDF2
from pypdf import PdfReader
def extract_with_pypdf(pdf_path):
reader = PdfReader(pdf_path)
text = ""
for page in reader.pages:
text += page.extract_text() or ""
return textIf Stage 1 fails, use system tools:
# Install if needed: apt-get install poppler-utils
pdftotext -layout input.pdf output.txt
pdftotext -raw input.pdf output.txt # Alternative layoutimport subprocess
def extract_with_pdftotext(pdf_path):
result = subprocess.run(
['pdftotext', '-layout', pdf_path, '-'],
capture_output=True, text=True
)
if result.returncode == 0:
return result.stdout
raise Exception("pdftotext failed")Try different Python libraries with varying capabilities:
# pdfplumber - better for tables
import pdfplumber
def extract_with_pdfplumber(pdf_path):
text = ""
with pdfplumber.open(pdf_path) as pdf:
for page in pdf.pages:
text += page.extract_text() or ""
return text
# pdfminer - handles complex layouts
from pdfminer.high_level import extract_text
def extract_with_pdfminer(pdf_path):
return extract_text(pdf_path)For scanned images or when text extraction fails:
# Using tesseract
convert input.pdf output-%d.png # Convert to images first
tesseract output-0.png result --psm 6# Using pytesseract
from pdf2image import convert_from_path
import pytesseract
def extract_with_ocr(pdf_path):
images = convert_from_path(pdf_path, dpi=300)
text = ""
for image in images:
text += pytesseract.image_to_string(image)
return textdef robust_pdf_extraction(pdf_path):
"""Try multiple extraction methods until one succeeds."""
extraction_methods = [
("PyPDF2", extract_with_pypdf),
("pdftotext", extract_with_pdftotext),
("pdfplumber", extract_with_pdfplumber),
("pdfminer", extract_with_pdfminer),
("OCR", extract_with_ocr),
]
errors = []
for method_name, method_func in extraction_methods:
try:
print(f"Trying {method_name}...")
text = method_func(pdf_path)
if text and text.strip():
print(f"Success with {method_name}")
return text
else:
errors.append(f"{method_name}: empty result")
except Exception as e:
errors.append(f"{method_name}: {str(e)}")
print(f"{method_name} failed: {e}")
continue
# All methods failed
raise Exception(f"All extraction methods failed:\n" + "\n".join(errors))A method is considered successful when:
| Symptom | Likely Cause | Best Fallback |
|---|---|---|
| Empty pages | Image-based PDF | OCR (Stage 4) |
| Garbled text | Encoding issues | pdftotext (Stage 2) |
| Missing tables | Simple parser | pdfplumber (Stage 3) |
| Permission errors | Encrypted PDF | Check password/permissions first |
| Layout lost | Complex formatting | pdftotext -layout or pdfplumber |
HKUDS/OpenSpace
3827781
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.