Feat/checkbox radio field filling

[utkarshqz]

Description

Fixes silent failure when filling checkbox and radio button fields in output PDFs. Previously, any value the LLM extracted for a checkbox or radio button (e.g. "yes", "female") was written as a plain string directly into the PDF annotation. PDF viewers ignore plain strings on button fields — the checkbox stayed empty and the radio button stayed unselected with no error and no warning.

PDF checkboxes and radio buttons require named PDF values like /Yes, /Off, /Male, /On — the exact name varies per PDF and is defined in the annotation's own appearance stream (AP.N). The old code wrote "yes" (a string) where the PDF expected /Yes (a PdfName). The field appeared empty because the value never matched any valid state.

Three helper functions added to src/filler.py:

_get_field_type(annot) — reads FT and Ff flags to classify each field as text, checkbox, radio, dropdown, or pushbutton. Previously all fields were treated as text.

_resolve_checkbox_value(raw, annot) — converts LLM output ("yes", "true", "x", "1", "checked") to the correct PdfName. Reads the PDF's own AP.N keys to find the exact on-state name — some PDFs use /Yes, others /On or a custom label. Falls back to /Yes if AP is missing.

_fill_annotation(annot, raw_value) — single dispatch function routing each annotation to the correct filling logic. Handles parent radio groups with child kid annotations, plain checkboxes, text fields, and dropdowns. Pushbuttons (Reset/Submit) are explicitly skipped.

Also fixed a silent bug in both fill_form() and fill_form_with_data() — None values were previously written as the literal string "None" into text fields. Now they write "".

docs/SETUP.md updated with a supported field types section documenting checkbox and radio button behaviour.

Fixes #229

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

New test file tests/test_filler.py covering all field type detection and value resolution logic.

• Checkbox — "yes", "true", "x", "1", "checked" resolve to checked state
• Checkbox — "no", "false", "0", "", "none" resolve to /Off
• Checkbox — reads custom on-state name from AP.N (e.g. /On instead of /Yes)
• Checkbox — falls back to /Yes when AP is missing
• Radio — selected option resolves to correct named value from AP.N
• Radio — unselected resolves to /Off
• Field type detection — /Tx → text, /Btn Ff=0 → checkbox, /Btn Ff bit16 → radio, unknown → other

Test Configuration:

• Python: 3.11
• OS: Windows 11
• Hardware: Local machine, no PDF file required (mocked annotations)

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules