Form Templates & Definitions

Relevant source files

The following files were used as context for generating this wiki page:

• templates/1040_fields.json
• tools/generate_sample_1040_template.py
• forms.py
• utils/auto_mapper.py
• tools/inspect_pdf_fields.py
• templates/README.md

The "Form Templates & Definitions" system provides the structural foundation for transforming extracted tax data into official document formats. This module manages the definitions of PDF AcroForm fields, the generation of synthetic test templates, and the intelligent mapping logic required to bridge raw parsed fields with specific form locations.

The system supports two primary output modes: a high-fidelity mode that fills existing PDF templates (1040_fillable.pdf) and a fallback mode that generates simplified ReportLab-based drafts if templates are unavailable. This architecture ensures that the tax processor can maintain functionality even in environments where standard IRS fillable forms are missing.
Sources: forms.py:102-120, templates/README.md

Form Architecture & Data Flow

The form generation logic follows a hierarchical flow where the system attempts the most complex mapping (AcroForm filling) before falling back to simpler text or basic PDF generation.

This diagram illustrates the decision logic within generate_1040_draft, showing how data flows through exact mapping or auto-mapping into the final PDF generation phase.
Sources: forms.py:122-192

Core Components

1. Template Definitions (1040_fields.json)

The system relies on a standardized set of field identifiers corresponding to the IRS Form 1040. These fields are defined as AcroForm keys.

Field Name	Description	Related Tax Data
YourFirstName	Taxpayer first name	first_name
YourLastName	Taxpayer last name	last_name
SSN	Social Security Number	ssn
Wages	Total Wages (Box 1)	wages
FederalIncomeTaxWithheld	Total Withholding	withholding
AdjustedGrossIncome	Computed AGI	tax_result['agi']
TaxDue	Final amount owed or refund	tax_result['tax_due']

Sources: templates/1040_fields.json:1-17, forms.py:32-55

2. Synthetic Template Generation

For development and testing, the project includes a tool to generate a "Synthetic" 1040 PDF. This tool uses reportlab to create a file containing specific AcroForm text fields.

• File Path: tools/generate_sample_1040_template.py
• Mechanism: Uses canvas.acroForm.textfield() to register valid interactive regions.
• Field Layout: Organizes fields into primary tax info and a "Summary" section including Summary_AGI and Summary_TotalTax.

Sources: tools/generate_sample_1040_template.py:23-64

3. Smart Field Mapping (Auto-Mapper)

The auto_mapper.py utility provides the logic to connect inconsistently named parsed fields to strict template field names.

• Primary Strategy: Uses sentence-transformers (specifically the all-MiniLM-L6-v2 model) to compute semantic similarity between parsed keys and template labels.
• Fallback Strategy: Uses difflib.SequenceMatcher for normalized string similarity if ML libraries are missing.
• Confidence Threshold: The system typically accepts mappings with a score of 0.4 or higher when performing fallback operations.

Sources: utils/auto_mapper.py:39-72, forms.py:165-175

Field Inspection and Maintenance

To maintain compatibility with real-world PDF forms, the system includes an inspection utility that extracts metadata from PDF files.

The inspection tool ensures that developers can accurately identify the /T (Title) keys required by the pdfrw library for form filling.
Sources: tools/inspect_pdf_fields.py:18-47, templates/README.md

Implementation Details

Currency Formatting

All numeric tax values are passed through a formatting helper before being injected into the form. This ensures values like 75000 appear as 75,000.00.
Sources: forms.py:17-25

PDF Filling Logic

The function fill_fillable_1040 performs the following operations:

1. Iterates through all pages and annotations (Annots).
2. Filters for /Widget subtypes with a name (/T).
3. Assigns the value (/V) formatted as a PDF string (%s).
4. Sets NeedAppearances=True in the AcroForm dictionary to ensure PDF viewers render the new values correctly.

Sources: forms.py:84-118

Summary

The "Form Templates & Definitions" module enables a robust document generation pipeline. By combining exact mapping for known synthetic templates with an AI-powered auto-mapper for third-party forms, the system achieves a high degree of flexibility. The inclusion of the inspection and generation tools allows the system to adapt to various versions of tax forms while maintaining a consistent data structure defined in 1040_fields.json. Assistant: