---
name: pdf_fillable_form_rungs
description: "Create a one-page PDF form with labeled text boxes and a checkbox that people can type into and check right in their PDF viewer. pdf_fillable_form_rungs: reportlab helpers for a one-page fillable AcroForm PDF: drawn title, labelled real text-field widgets with exact names, and a real checkbox widget"
---

# pdf_fillable_form_rungs (a Neruva verified skill for `pdf`)

Create a one-page PDF form with labeled text boxes and a checkbox that people can type into and check right in their PDF viewer.

Verified helper code for `pdf`, python. Entry points: `create_form_canvas`, `draw_title`, `draw_label`, `add_text_field`, `add_checkbox_field`, `save_form`, `build_one_page_form`.
Code hash sha256 `56711152a527374451c086569617afb98cccb2eb6f75e6b55fc77bc38db69d92`, signed (ed25519). Banked by `legacy-dev`.

## One call

Call `build(**args)` with an object matching this schema. You do not have to write code or match the helper signatures below.

```json
{
  "type": "object",
  "properties": {
    "output_path": {
      "type": "string",
      "description": "Path to write the resulting fillable PDF form to."
    },
    "title": {
      "type": "string",
      "description": "Title text drawn at the top of the page."
    },
    "text_fields": {
      "type": "array",
      "description": "List of text field definitions, each rendered as a label plus a real AcroForm text field widget.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Exact AcroForm field name (required)."
          },
          "label": {
            "type": "string",
            "description": "Visible label text drawn next to the field (required)."
          },
          "x": {
            "type": "number",
            "description": "Optional x coordinate override (label position); defaults to auto layout using left_margin."
          },
          "y": {
            "type": "number",
            "description": "Optional y coordinate override (row position); defaults to auto layout descending by row_height."
          },
          "width": {
            "type": "number",
            "description": "Optional field width in points; defaults to field_width."
          },
          "height": {
            "type": "number",
            "description": "Optional field height in points; defaults to field_height."
          }
        },
        "required": [
          "name",
          "label"
        ]
      }
    },
    "checkbox_fields": {
      "type": "array",
      "description": "Optional list of checkbox field definitions.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Exact AcroForm field name (required)."
          },
          "label": {
            "type": "string",
            "description": "Optional visible label text drawn to the right of the checkbox."
          },
          "x": {
            "type": "number",
            "description": "Optional x coordinate override; defaults to auto layout."
          },
          "y": {
            "type": "number",
            "description": "Optional y coordinate override; defaults to auto layout."
          },
          "size": {
            "type": "number",
            "description": "Optional checkbox size in points; defaults to 14."
          },
          "checked": {
            "type": "boolean",
            "description": "Optional initial checked state; defaults to false."
          }
        },
        "required": [
          "name"
        ]
      }
    },
    "page_size": {
      "type": "array",
      "description": "Optional [width, height] in points for the page; defaults to US Letter.",
      "items": {
        "type": "number"
      },
      "minItems": 2,
      "maxItems": 2
    },
    "left_margin": {
      "type": "number",
      "description": "Left margin in points; defaults to 72."
    },
    "top_margin": {
      "type": "number",
      "description": "Distance from top of page to the title baseline in points; defaults to 72."
    },
    "row_height": {
      "type": "number",
      "description": "Vertical spacing between auto-laid-out rows in points; defaults to 40."
    },
    "label_width": {
      "type": "number",
      "description": "Horizontal space reserved for each label before its field, in points; defaults to 140."
    },
    "field_width": {
      "type": "number",
      "description": "Default text field width in points; defaults to 250."
    },
    "field_height": {
      "type": "number",
      "description": "Default text field height in points; defaults to 20."
    },
    "title_font": {
      "type": "string",
      "description": "Font name for the title; defaults to Helvetica-Bold."
    },
    "title_size": {
      "type": "number",
      "description": "Font size for the title; defaults to 20."
    },
    "label_font": {
      "type": "string",
      "description": "Font name for labels and field text; defaults to Helvetica."
    },
    "label_size": {
      "type": "number",
      "description": "Font size for labels and field text; defaults to 12."
    }
  },
  "required": [
    "output_path",
    "title",
    "text_fields"
  ]
}
```

Example arguments:

```json
{
  "output_path": "intake_form.pdf",
  "title": "Employee Intake Form",
  "text_fields": [
    {
      "name": "full_name",
      "label": "Full Name:"
    },
    {
      "name": "employee_id",
      "label": "Employee ID:"
    },
    {
      "name": "email",
      "label": "Email:"
    }
  ],
  "checkbox_fields": [
    {
      "name": "agree_terms",
      "label": "I agree to the terms",
      "checked": false
    }
  ],
  "left_margin": 72,
  "top_margin": 72,
  "row_height": 40
}
```

```python
def build(**kwargs):
    output_path = kwargs["output_path"]
    title = kwargs["title"]
    text_fields = kwargs["text_fields"]
    checkbox_fields = kwargs.get("checkbox_fields")
    page_size = kwargs.get("page_size")
    left_margin = kwargs.get("left_margin", 72)
    top_margin = kwargs.get("top_margin", 72)
    row_height = kwargs.get("row_height", 40)
    label_width = kwargs.get("label_width", 140)
    field_width = kwargs.get("field_width", 250)
    field_height = kwargs.get("field_height", 20)
    title_font = kwargs.get("title_font", "Helvetica-Bold")
    title_size = kwargs.get("title_size", 20)
    label_font = kwargs.get("label_font", "Helvetica")
    label_size = kwargs.get("label_size", 12)

    if page_size is not None:
        page_size = tuple(page_size)

    build_one_page_form(
        output_path,
        title=title,
        text_fields=text_fields,
        checkbox_fields=checkbox_fields,
        page_size=page_size,
        left_margin=left_margin,
        top_margin=top_margin,
        row_height=row_height,
        label_width=label_width,
        field_width=field_width,
        field_height=field_height,
        title_font=title_font,
        title_size=title_size,
        label_font=label_font,
        label_size=label_size,
    )
    return output_path
```

## How to use it

HELPER FUNCTIONS REFERENCE

1. create_form_canvas(output_path, page_size=None)
   Returns: (canvas.Canvas, width, height) — a reportlab canvas ready for AcroForm widgets.
   Example:
     c, w, h = create_form_canvas("out.pdf")

2. draw_title(c, text, x, y, font="Helvetica-Bold", size=18)
   Draws a title string on the canvas at (x, y).
   Returns: y (float), the same y passed in (for layout chaining).
   Example:
     draw_title(c, "Intake Form", 72, 720)

3. draw_label(c, text, x, y, font="Helvetica", size=12)
   Draws a plain text label (e.g. next to a field) on the canvas.
   Returns: y (float).
   Example:
     draw_label(c, "Email:", 72, 650)

4. add_text_field(c, name, x, y, width, height, value="", font="Helvetica", font_size=12, border=True, tooltip=None)
   Adds a real fillable AcroForm text-field widget named exactly `name`.
   Returns: None (mutates the canvas/PDF).
   Example:
     add_text_field(c, "email", 220, 645, 250, 20)

5. add_checkbox_field(c, name, x, y, size=12, checked=False, tooltip=None, border=True)
   Adds a real fillable AcroForm checkbox widget named exactly `name`.
   Returns: None.
   Example:
     add_checkbox_field(c, "agree_terms", 72, 550, size=14)

6. save_form(c)
   Finalizes and writes the PDF to disk.
   Returns: None.
   Example:
     save_form(c)

7. build_one_page_form(output_path, title, text_fields, checkbox_fields=None, page_size=None, left_margin=72, top_margin=72, row_height=40, label_width=140, field_width=250, field_height=20, title_font="Helvetica-Bold", title_size=20, label_font="Helvetica", label_size=12)
   High-level builder: draws a title, then auto-lays-out a column of labelled text fields (list of dicts with 'name' and 'label', optional 'x'/'y'/'width'/'height' overrides), then any checkbox fields (list of dicts with 'name', optional 'label'/'x'/'y'/'size'/'checked'). Writes the finished PDF to output_path.
   Returns: None. Writes PDF to output_path.
   Example:
     build_one_page_form(
         "out.pdf",
         title="Intake Form",
         text_fields=[{"name": "employee_id", "label": "Employee ID:"}],
         checkbox_fields=[{"name": "agree_terms", "label": "I agree"}],
     )


## Evidence (corpus named)

- held-out 16 form specs, best-of-2: deepseek-chat cold 0.438 -> 1.000 with rung (CI +0.375..+0.750), 0.15c/form vs Sonnet cold 1.000 at 2.92c; forged by Sonnet in one round for $0.97 incl. generality checks

## Files

- `scripts/skill.py`: the verified code (GET /v1/commons/rungs/rec_0b825e5402a34e4da7f7c044b7d1e56d/code)
- verify: POST /v1/commons/verify {"id": "rec_0b825e5402a34e4da7f7c044b7d1e56d"}