extract-tables

name	extract-tables
description	Use when you need to extract tables from a PDF into individual CSV files

Extract Tables

Detect and extract tables from a PDF document, saving each as a CSV file with a manifest index.

When to use

• PDF contains tables you need as data/spreadsheets
• Preparing structured data from a tabular PDF
• Converting tables to a format suitable for analysis or re-use
• User specifies camelot or tabula as the extraction engine

Inputs to gather

• PDF file path (required)
• Engine: --engine=camelot or --engine=tabula (optional; defaults to camelot with tabula fallback)
• Pages: --pages=all, or --pages=1,3,5-7 (optional; defaults to all pages)

Procedure

1. Activate the venv at $CLAUDE_USER_DATA/document-to-markdown/venv/.
2. Use the specified engine (camelot by default) to detect tables in the PDF. If a page range is given, limit detection to those pages.
3. If camelot fails on any table, fall back to tabula for that table without aborting the full job.
4. For each detected table:
   • Extract the table data
   • Attempt to find a nearby caption by scanning the PDF text around the table location for "Figure", "Table", or "Caption" markers
   • Fall back to a generic label (e.g., "table-3") if no caption is found
   • Generate a slug from the caption (kebab-case, sanitized)
5. Create output directory tables/ next to the source PDF.
6. Write each table to tables/NN-p<page>-<slug>.csv, where NN is a zero-padded sequence number, <page> is the page number, and <slug> is derived from the caption.
7. Create tables/index.toon manifest with one entry per table, fields: slug, page, caption, columns (list of column names), rows (row count), engine (camelot or tabula).

Output / side effects

• tables/ directory created next to source PDF
• One CSV file per detected table
• tables/index.toon manifest file with metadata per table
• Console output showing tables extracted and engines used

Safety / constraints

• Best-effort caption extraction; captions may be absent or imprecise
• Fallback to tabula is silent if camelot fails; report which engine was used per table in the manifest
• Do not overwrite existing CSV files without asking