| name | extracting-pdf-tables |
| description | Use when extracting tables from PDF documents — works for digital and OCR'd PDFs, multi-column layouts, and rotated tables. Triggers on requests to "pull tables out of a PDF", "extract a table from a .pdf file", or after pdfplumber/Camelot return empty results. |
| license | MIT |
Extracting PDF Tables
Reliable table extraction from PDFs that simpler tools struggle with. Wraps pdfplumber for digital text and falls back to tabula-java plus OCR for scanned pages.
When to use
- A user wants tabular data from a PDF.
pdfplumber returned None for page.extract_tables().- The PDF is scanned, rotated, or uses multi-column page layouts.
Do NOT use for free-form text extraction (use a plain text extractor) or for forms with named fields (use a form-specific tool).
Workflow
- Inspect the PDF — confirm pages with tables and whether text is selectable.
- Run
scripts/extract.py <file.pdf> --pages <range> to attempt digital extraction.
- If output is empty for any page, re-run with
--ocr to fall through to OCR.
- Validate the output against
references/expected-shape.md before returning to the user.
Quick reference
| Need | Path |
|---|
| Run extraction | scripts/extract.py |
| Output shape spec | references/expected-shape.md |
Example
$ scripts/extract.py invoices.pdf --pages 2-5
extracting-pdf-tables: 4 pages, 6 tables found
invoices_p2_t0.csv (12 rows × 5 cols)
invoices_p3_t0.csv (8 rows × 5 cols)
invoices_p4_t0.csv (15 rows × 5 cols)
invoices_p4_t1.csv (3 rows × 2 cols)
...
Output contract
CSV per table, one file per (page, table_index). Filename pattern: STEM_pPAGE_tINDEX.csv.
