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)

# 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

# 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)

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:

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)

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):

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:

   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

# 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"