# pi-pdf

PDF manipulation, processing, and management toolkit for [Pi coding agent](https://github.com/badlogic/pi-mono).

## Features

- **Extract text** from PDFs with layout preservation
- **Extract tables** as structured data
- **Merge** multiple PDFs into one
- **Split** PDFs into individual pages or ranges
- **Rotate** pages by 90°, 180°, or 270°
- **Add watermarks** (text overlay on all pages)
- **Encrypt** PDFs with password protection
- **Decrypt** password-protected PDFs
- **Fill PDF forms** (fillable fields and annotation-based)
- **Convert PDFs to images** for visual analysis
- **OCR** scanned PDFs (with pytesseract)
- **Get PDF metadata** (title, author, page count, encryption status)

## Installation

```bash
pi install npm:@joemccann/pi-pdf
```

Or for project-local installation:

```bash
pi install -l npm:@joemccann/pi-pdf
```

### Prerequisites

Requires Python 3.9+ with these packages:

```bash
pip install pypdf pdfplumber reportlab
```

Optional (for OCR and image conversion):

```bash
pip install pdf2image pytesseract pypdfium2 Pillow
```

Optional CLI tools:

```bash
# macOS
brew install poppler qpdf

# Ubuntu/Debian
apt install poppler-utils qpdf
```

Check all dependencies:

```bash
node scripts/check-deps.js
```

## What's Included

### Extension Tools (10 tools)

The LLM can call these tools directly:

| Tool | Description |
|------|-------------|
| `pdf_info` | Get metadata, page count, encryption & form-field status |
| `pdf_extract_text` | Extract text from pages with layout preservation |
| `pdf_extract_tables` | Extract structured table data |
| `pdf_merge` | Merge multiple PDFs into one |
| `pdf_split` | Split a PDF into pages or ranges |
| `pdf_rotate` | Rotate pages by 90/180/270 degrees |
| `pdf_encrypt` | Password-protect a PDF |
| `pdf_decrypt` | Remove password protection |
| `pdf_watermark` | Add text watermark overlay |
| `pdf_to_images` | Convert pages to PNG images |
| `pdf_form_fields` | Extract fillable form field info |
| `pdf_fill_form` | Fill in PDF form fields |

### Skill

The `pdf` skill provides comprehensive PDF processing guidance that the agent loads on-demand when working with PDF files. It covers:

- All Python libraries (pypdf, pdfplumber, reportlab, pypdfium2)
- JavaScript libraries (pdf-lib, pdfjs-dist)
- CLI tools (qpdf, pdftotext, pdftk)
- Form filling workflows (fillable and non-fillable PDFs)
- Advanced reference documentation

## Usage Examples

Just ask Pi to work with PDFs naturally:

```
"Extract the tables from invoice.pdf"
"Merge report1.pdf, report2.pdf and report3.pdf into combined.pdf"
"Split this 50-page PDF into chunks of 10 pages"
"Add a CONFIDENTIAL watermark to the document"
"Password-protect the contract PDF"
"Fill out this tax form with my information"
"How many pages are in this PDF?"
```

## Testing

```bash
# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration
```

## Project Structure

```
pi-pdf/
├── package.json              # Pi package manifest
├── README.md
├── LICENSE
├── extensions/
│   └── index.ts              # Extension tools (pdf_info, pdf_merge, etc.)
├── skills/
│   └── pdf/
│       ├── SKILL.md           # Main skill file with usage guide
│       ├── REFERENCE.md       # Advanced reference documentation
│       ├── FORMS.md           # Form filling workflow guide
│       └── scripts/           # Python helper scripts
│           ├── check_bounding_boxes.py
│           ├── check_fillable_fields.py
│           ├── convert_pdf_to_images.py
│           ├── create_validation_image.py
│           ├── extract_form_field_info.py
│           ├── extract_form_structure.py
│           ├── fill_fillable_fields.py
│           └── fill_pdf_form_with_annotations.py
├── scripts/
│   └── check-deps.js         # Dependency checker
└── tests/
    ├── fixtures/              # Test PDF files
    ├── unit/                  # Unit tests
    └── integration/           # Integration tests
```

## License

MIT