claude-code-templates 1.21.13 → 1.21.14

package/cli-tool/components/skills/document-processing/pdf-anthropic/scripts/fill_pdf_form_with_annotations.py

@@ -0,0 +1,108 @@
+import json
+import sys
+
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import FreeText
+
+
+# Fills a PDF by adding text annotations defined in `fields.json`. See forms.md.
+
+
+def transform_coordinates(bbox, image_width, image_height, pdf_width, pdf_height):
+    """Transform bounding box from image coordinates to PDF coordinates"""
+    # Image coordinates: origin at top-left, y increases downward
+    # PDF coordinates: origin at bottom-left, y increases upward
+    x_scale = pdf_width / image_width
+    y_scale = pdf_height / image_height
+    
+    left = bbox[0] * x_scale
+    right = bbox[2] * x_scale
+    
+    # Flip Y coordinates for PDF
+    top = pdf_height - (bbox[1] * y_scale)
+    bottom = pdf_height - (bbox[3] * y_scale)
+    
+    return left, bottom, right, top
+
+
+def fill_pdf_form(input_pdf_path, fields_json_path, output_pdf_path):
+    """Fill the PDF form with data from fields.json"""
+    
+    # `fields.json` format described in forms.md.
+    with open(fields_json_path, "r") as f:
+        fields_data = json.load(f)
+    
+    # Open the PDF
+    reader = PdfReader(input_pdf_path)
+    writer = PdfWriter()
+    
+    # Copy all pages to writer
+    writer.append(reader)
+    
+    # Get PDF dimensions for each page
+    pdf_dimensions = {}
+    for i, page in enumerate(reader.pages):
+        mediabox = page.mediabox
+        pdf_dimensions[i + 1] = [mediabox.width, mediabox.height]
+    
+    # Process each form field
+    annotations = []
+    for field in fields_data["form_fields"]:
+        page_num = field["page_number"]
+        
+        # Get page dimensions and transform coordinates.
+        page_info = next(p for p in fields_data["pages"] if p["page_number"] == page_num)
+        image_width = page_info["image_width"]
+        image_height = page_info["image_height"]
+        pdf_width, pdf_height = pdf_dimensions[page_num]
+        
+        transformed_entry_box = transform_coordinates(
+            field["entry_bounding_box"],
+            image_width, image_height,
+            pdf_width, pdf_height
+        )
+        
+        # Skip empty fields
+        if "entry_text" not in field or "text" not in field["entry_text"]:
+            continue
+        entry_text = field["entry_text"]
+        text = entry_text["text"]
+        if not text:
+            continue
+        
+        font_name = entry_text.get("font", "Arial")
+        font_size = str(entry_text.get("font_size", 14)) + "pt"
+        font_color = entry_text.get("font_color", "000000")
+
+        # Font size/color seems to not work reliably across viewers:
+        # https://github.com/py-pdf/pypdf/issues/2084
+        annotation = FreeText(
+            text=text,
+            rect=transformed_entry_box,
+            font=font_name,
+            font_size=font_size,
+            font_color=font_color,
+            border_color=None,
+            background_color=None,
+        )
+        annotations.append(annotation)
+        # page_number is 0-based for pypdf
+        writer.add_annotation(page_number=page_num - 1, annotation=annotation)
+        
+    # Save the filled PDF
+    with open(output_pdf_path, "wb") as output:
+        writer.write(output)
+    
+    print(f"Successfully filled PDF form and saved to {output_pdf_path}")
+    print(f"Added {len(annotations)} text annotations")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 4:
+        print("Usage: fill_pdf_form_with_annotations.py [input pdf] [fields.json] [output pdf]")
+        sys.exit(1)
+    input_pdf = sys.argv[1]
+    fields_json = sys.argv[2]
+    output_pdf = sys.argv[3]
+    
+    fill_pdf_form(input_pdf, fields_json, output_pdf)

package/cli-tool/components/skills/document-processing/pdf-processing/FORMS.md

@@ -0,0 +1,143 @@
+# PDF Form Filling Guide
+
+## Overview
+
+This guide covers filling PDF forms programmatically using PyPDF2 and pdfrw libraries.
+
+## Analyzing form fields
+
+First, identify all fillable fields in a PDF:
+
+```python
+from pypdf import PdfReader
+
+reader = PdfReader("form.pdf")
+fields = reader.get_fields()
+
+for field_name, field_info in fields.items():
+    print(f"Field: {field_name}")
+    print(f"  Type: {field_info.get('/FT')}")
+    print(f"  Value: {field_info.get('/V')}")
+    print()
+```
+
+## Filling form fields
+
+Fill fields with values:
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("form.pdf")
+writer = PdfWriter()
+
+writer.append_pages_from_reader(reader)
+
+# Fill form fields
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {
+        "name": "John Doe",
+        "email": "john@example.com",
+        "address": "123 Main St"
+    }
+)
+
+with open("filled_form.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Flattening forms
+
+Remove form fields after filling (make non-editable):
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("filled_form.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    writer.add_page(page)
+
+# Flatten all form fields
+writer.flatten_form_fields()
+
+with open("flattened.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Validation
+
+Validate field values before filling:
+
+```python
+def validate_email(email):
+    return "@" in email and "." in email
+
+def validate_form_data(data, required_fields):
+    errors = []
+
+    for field in required_fields:
+        if field not in data or not data[field]:
+            errors.append(f"Missing required field: {field}")
+
+    if "email" in data and not validate_email(data["email"]):
+        errors.append("Invalid email format")
+
+    return errors
+
+# Usage
+data = {"name": "John Doe", "email": "john@example.com"}
+required = ["name", "email", "address"]
+
+errors = validate_form_data(data, required)
+if errors:
+    print("Validation errors:")
+    for error in errors:
+        print(f"  - {error}")
+else:
+    # Proceed with filling
+    pass
+```
+
+## Common field types
+
+**Text fields:**
+```python
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {"text_field": "Some text"}
+)
+```
+
+**Checkboxes:**
+```python
+# Check a checkbox
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {"checkbox_field": "/Yes"}
+)
+
+# Uncheck a checkbox
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {"checkbox_field": "/Off"}
+)
+```
+
+**Radio buttons:**
+```python
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {"radio_group": "/Option1"}
+)
+```
+
+## Best practices
+
+1. **Always validate** input data before filling
+2. **Check field names** match exactly (case-sensitive)
+3. **Test with small files** first
+4. **Keep originals** - work on copies
+5. **Flatten after filling** for distribution

package/cli-tool/components/skills/document-processing/pdf-processing/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: PDF Processing
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+---
+
+# PDF Processing
+
+## Quick start
+
+Use pdfplumber to extract text from PDFs:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+    print(text)
+```
+
+## Extracting tables
+
+Extract tables from PDFs with automatic detection:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("report.pdf") as pdf:
+    page = pdf.pages[0]
+    tables = page.extract_tables()
+
+    for table in tables:
+        for row in table:
+            print(row)
+```
+
+## Extracting all pages
+
+Process multi-page documents efficiently:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    full_text = ""
+    for page in pdf.pages:
+        full_text += page.extract_text() + "\n\n"
+
+    print(full_text)
+```
+
+## Form filling
+
+For PDF form filling, see [FORMS.md](FORMS.md) for the complete guide including field analysis and validation.
+
+## Merging PDFs
+
+Combine multiple PDF files:
+
+```python
+from pypdf import PdfMerger
+
+merger = PdfMerger()
+
+for pdf in ["file1.pdf", "file2.pdf", "file3.pdf"]:
+    merger.append(pdf)
+
+merger.write("merged.pdf")
+merger.close()
+```
+
+## Splitting PDFs
+
+Extract specific pages or ranges:
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+# Extract pages 2-5
+for page_num in range(1, 5):
+    writer.add_page(reader.pages[page_num])
+
+with open("output.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Available packages
+
+- **pdfplumber** - Text and table extraction (recommended)
+- **pypdf** - PDF manipulation, merging, splitting
+- **pdf2image** - Convert PDFs to images (requires poppler)
+- **pytesseract** - OCR for scanned PDFs (requires tesseract)
+
+## Common patterns
+
+**Extract and save text:**
+```python
+import pdfplumber
+
+with pdfplumber.open("input.pdf") as pdf:
+    text = "\n\n".join(page.extract_text() for page in pdf.pages)
+
+with open("output.txt", "w") as f:
+    f.write(text)
+```
+
+**Extract tables to CSV:**
+```python
+import pdfplumber
+import csv
+
+with pdfplumber.open("tables.pdf") as pdf:
+    tables = pdf.pages[0].extract_tables()
+
+    with open("output.csv", "w", newline="") as f:
+        writer = csv.writer(f)
+        for table in tables:
+            writer.writerows(table)
+```
+
+## Error handling
+
+Handle common PDF issues:
+
+```python
+import pdfplumber
+
+try:
+    with pdfplumber.open("document.pdf") as pdf:
+        if len(pdf.pages) == 0:
+            print("PDF has no pages")
+        else:
+            text = pdf.pages[0].extract_text()
+            if text is None or text.strip() == "":
+                print("Page contains no extractable text (might be scanned)")
+            else:
+                print(text)
+except Exception as e:
+    print(f"Error processing PDF: {e}")
+```
+
+## Performance tips
+
+- Process pages in batches for large PDFs
+- Use multiprocessing for multiple files
+- Extract only needed pages rather than entire document
+- Close PDF objects after use