Developer Tools

The Developer Tools in the Rosy Tax Processor project comprise a suite of utility scripts and command-line interfaces designed to facilitate the development, testing, and configuration of the tax processing pipeline. These tools allow developers to inspect PDF form structures, generate synthetic templates for local testing, and execute the processing logic without the overhead of the web-based frontend.

The primary scope of these tools is to bridge the gap between raw document ingestion and the final form-filling stage by providing transparency into PDF AcroForm fields and ensuring that the auto-mapper has valid targets for semantic field matching.
Sources: README.md:38-41, SETUP.md:73-75

PDF Inspection and Template Generation

These tools are critical for the Form Generation workflow, allowing developers to ensure that parsed tax data correctly maps to the physical fields of a PDF document.

PDF Field Inspector

The inspect_pdf_fields.py utility is used to extract and list all AcroForm field names within a given PDF file. This is essential for creating the 1040_fields.json reference file used by the mapping logic.

The diagram above illustrates the recursive logic used to traverse the PDF object tree to find terminal field names.
Sources: tools/inspect_pdf_fields.py:27-50

Synthetic Template Generator

To support local development without requiring official IRS forms, the generate_sample_1040_template.py script creates a "1040-like" PDF. This document contains standard AcroForm text fields such as YourFirstName, SSN, and Wages to verify the functionality of the pdfrw filling engine.
Sources: tools/generate_sample_1040_template.py:1-20

Command Line Interface (CLI)

The project provides a CLI runner for direct interaction with the parsing and classification engine. This tool is primarily used for rapid prototyping of regex-based extraction logic.

CLI Workflow

The CLI simulates the ingestion of OCR text by reading from local .txt files. It processes the text through the heuristic classifier and the template-based parser to output structured JSON data.

Testing and Verification Tools

The development environment is supported by a comprehensive test suite that verifies the integrity of the developer tools and the core processing pipeline.

Test Execution

Developers can run the full suite using pytest. Specific tests exist for the pipeline, tax calculations, and the auto-mapper.

• Pipeline Tests: Located in tests/test_pipeline.py, these verify that the end-to-end flow from text ingestion to field validation works correctly for W-2 and 1099 documents.
• Field Mapping Tests: Validate that the semantic similarity engine (using sentence-transformers) correctly identifies field associations between extracted data and PDF templates.

Sources: README.md:73-85, tests/test_pipeline.py:10-25

Summary

The Developer Tools provided in the Tax-Processor repository are instrumental for maintaining the robustness of the document processing pipeline. By providing scripts to inspect PDF internals (inspect_pdf_fields.py) and generate test environments (generate_sample_1040_template.py), the project ensures that the AI-powered mapping and extraction logic remains accurate and verifiable across different document formats.