pdf-reader

Files (2)

• SKILL.md
• extract.py · scripts/

SKILL.md (first lines)

# PDF Reader

Extract content from PDF files using `pdftotext` (Poppler) for text and
`pdfplumber` (Python) for tables and structured extraction.

## Quick Reference

| Task | Tool | Command |
|------|------|---------|
| Full text | pdftotext | `pdftotext file.pdf -` |
| Text with layout | pdftotext | `pdftotext -layout file.pdf -` |
| Specific pages | pdftotext | `pdftotext -f 3 -l 5 file.pdf -` |
| Tables | pdfplumber | `python3 scripts/extract.py tables file.pdf` |
| Metadata | pdfinfo | `pdfinfo file.pdf` |
| Page count | pdfinfo | `pdfinfo file.pdf \| grep Pages` |
| Images | pdfimages | `pdfimages -list file.pdf` |
| Fonts | pdffonts | `pdffonts file.pdf` |
| OCR (scanned PDF) | tesseract | `python3 scripts/extract.py ocr file.pdf` |
| Smart text + OCR | extract.py | `python3 scripts/extract.py text file.pdf` |
| Quick survey | extract.py | `python3 scripts/extract.py scan file.pdf` |

## Workflow

### Step 1: Get the PDF

If the user provides a URL, download it first:

```bash
curl -sL "URL" -o /tmp/document.pdf
```

Verify it's a valid PDF:

```bash
file /tmp/document.pdf  # should say "PDF document"
pdfinfo /tmp/document.pdf  # metadata + page count
```

### Step 2: Choose Extraction Method

**Plain text (most cases):**

```bash
pdftotext file.pdf -
```

This pipes output to stdout. For large PDFs, use page ranges:

```bash
pdftotext -f 1 -l 10 file.pdf -    # pages 1-10
```

**Layout-preserving text (columns, formatted docs):**

```bash
pdftotext -layout file.pdf -
```

Use `-layout` when the PDF has multi-column layouts, tables rendered as text,
or precise spacing that matters.

**Tables (structured data):**

```bash
python3 scripts/extract.py tables file.pdf
```

Or inline with pdfplumber:

```python
import pdfplumber

pdf = pdfplumber.open("file.pdf")
for i, page in enumerate(pdf.pages):
    tables = page.extract_tables()
    for table in tables:
        print(f"\n--- Table on page {i+1} ---")
        for row in table:
            print(" | ".join(str(cell or "") for cell in row))
pdf.close()
```

**Metadata only:**

```bash
pdfinfo file.pdf
```

Returns: title, author, creator, producer, page count, page size, dates.

### Step 3: Handle Large PDFs

For PDFs over ~50 pages, don't dump everything at once:

1. Get page count: `pdfinfo file.pdf | grep Pages`
2. Extract in chunks: `pdftotext -f 1 -l 20 file.pdf -`
3. Process chunk, then continue: `pdftotext -f 21 -l 40 file.pdf -`

For targeted extraction (searching for specific content):

```bash
# Extract all text, grep for relevant sections
pdftotext file.pdf - | grep -n -i "keyword"

# Then extract the specific page range
pdftotext -f PAGE -l PAGE file.pdf -
```

### Step 4: Handle Scanned PDFs (OCR)

If `pdftotext` returns empty or garbled output, the PDF is likely scanned.

**Detection:**
```bash
python3 scripts/extract.py scan file.pdf   # reports scanned pages
pdffonts file.pdf                           # empty = image-based
```

**Smart extraction (auto-fallback):**

From espennilsen/pi, MIT.

More from espennilsen/pi