PDF Form Filler

SKILL.md

---
name: pdf-form-filler
description: Fill PDF forms using AI (nano-pdf) with signature overlay. Retrieve forms from WhatsApp/Beeper, fill with data from Google Workspace, add signatures, and send back.
---

# PDF Form Filler Skill

Fill PDF forms intelligently using nano-pdf (AI-powered) and add signature overlays. Integrated with Beeper (WhatsApp) for receiving/sending forms.

## Prerequisites

- `nano-pdf` CLI installed (`pip install nano-pdf`)
- `tesseract-ocr` installed (`sudo apt-get install tesseract-ocr`)
- Gemini API key in `~/clawd/secrets/gemini-api-key.txt`
- Beeper Desktop running on Mac with API enabled
- Beeper API key in `~/clawd/secrets/beeper.json`

## Workflow

### 1. Retrieve PDF from WhatsApp (via Beeper)

```bash
# Search for chat
~/clawd/skills/beeper/scripts/search-chats.sh "Contact Name"

# Get recent messages with attachments
API_KEY=$(cat ~/clawd/secrets/beeper.json | jq -r '.api_key')
curl -s "http://100.86.150.96:23373/v1/chats/{chatID}/messages?limit=10" \
  -H "Authorization: Bearer $API_KEY" | jq '.items[] | select(.attachments)'
```

### 2. Download the PDF attachment

```bash
# File is stored locally on Mac at the srcURL path
# Copy via SSH:
ssh henrymascot@100.86.150.96 "cat '/path/to/attachment'" > /tmp/form.pdf
```

### 3. Fill the form with nano-pdf (AI-powered)

```bash
export GEMINI_API_KEY=$(cat ~/clawd/secrets/gemini-api-key.txt)

nano-pdf edit /tmp/form.pdf 1 "Fill the form with:
Name: Company Name Ltd
Address: 123 Street Address
City: Lagos
Country: Nigeria
Account number: 1234567890
Bank name: United Bank for Africa (UBA)
Date: 29/01/2026
Add a signature on the signature line." \
--output /tmp/form-filled.pdf
```

### 4. Add custom signature overlay (if needed)

nano-pdf adds a generic signature. To use a custom signature image:

```python
from pypdf import PdfReader, PdfWriter
from reportlab.pdfgen import canvas
from io import BytesIO

reader = PdfReader("/tmp/form-filled.pdf")
page = reader.pages[0]

page_width = float(page.mediabox.width)
page_height = float(page.mediabox.height)

packet = BytesIO()
can = canvas.Canvas(packet, pagesize=(page_width, page_height))

# Cover nano-pdf's signature with white rectangle
can.setFillColorRGB(1, 1, 1)
can.rect(58, 348, 145, 55, fill=1, stroke=0)  # Adjust coords as needed

# Add custom signature image
can.drawImage("/tmp/signature.jpg", 62, 352, width=100, height=45, mask='auto')

can.save()

packet.seek(0)
overlay_reader = PdfReader(packet)
overlay_page = overlay_reader.pages[0]

writer = PdfWriter()
page.merge_page(overlay_page)
writer.add_page(page)

with open("/tmp/form-final.pdf", "wb") as f:
    writer.write(f)
```

### 5. Send completed PDF via WhatsApp (Beeper)

```bash
API_KEY=$(cat ~/clawd/secrets/beeper.json | jq -r '.api_key')

# Copy PDF to Mac first
cat /tmp/form-final.pdf | ssh henrymascot@100.86.150.96 "cat > /tmp/form-final.pdf"

# Send via Beeper API (multipart upload)
ssh henrymascot@100.86.150.96 "curl -s -X POST 'http://localhost:23373/v1/chats/{chatID}/messages' \
  -H 'Authorization: Bearer $API_KEY' \
  -F 'file=@/tmp/form-final.pdf' \
  -F 'filename=Completed-Form.pdf'"
```

## Key Coordinates (for Stanbic IBTC Reference Form)

For the specific bank reference form (Page 07 of 22):

| Field | PDF Y-coord (from bottom) |
|-------|---------------------------|
| Name | ~640 |
| Address | ~608 |
| LGA/City | ~576 |
| Country | ~576 (x=500) |
| Telephone | ~544 |
| Account number | ~512 |
| Bank name | ~480 |
| Signature area | 348-403 |
| Date | ~355 (x=340) |

## Tips

1. **nano-pdf is magic** - Use natural language to describe what to fill. It uses Gemini vision to understand the form layout.

2. **Signature positioning** - nano-pdf adds a cursive "Signature" text. Cover it with a white rectangle and overlay the real signature image.

3. **PDF coordinates** - PDF origin is bottom-left. Use `pdftoppm` at 150 DPI to create images, then calculate:
   - `pdf_y = page_height - (image_y_from_top / 2.083)`

4. **Verify with images** - Always convert to PNG to verify positioning:
   ```bash
   pdftoppm form.pdf output -png -r 150
   ```

## Scripts

- `fill-form.sh` - Main script for common form filling
- `add-signature.py` - Add signature overlay to PDF
- `send-via-beeper.sh` - Send PDF via WhatsApp/Beeper

## Example: Bank Reference Form

```bash
# Full workflow
~/clawd/skills/pdf-form-filler/scripts/fill-bank-reference.sh \
  --input /tmp/reference-form.pdf \
  --company "Curacel Systems Ltd" \
  --address "19 Adeyemi Lawson, Ikoyi" \
  --city "Lagos" \
  --country "Nigeria" \
  --account "1020639292" \
  --bank "United Bank for Africa (UBA)" \
  --years "10" \
  --signature /tmp/signature.jpg \
  --output /tmp/completed.pdf \
  --send-to "+2348066383007"
```