CLI Usage
Relevant source files
The following files were used as context for generating this wiki page:
The Command Line Interface (CLI) in the Tax-Processor project serves as a primary tool for developers and users to interact with the tax document processing pipeline without needing a web browser. It facilitates local testing, document classification, field extraction, and PDF template management.
The CLI ecosystem consists of a main runner (cli.py) for processing simulated OCR text, an orchestration script (pipeline.py) for full-system execution, and specialized utility tools located in the tools/ directory for managing PDF form fields and templates.
Sources: cli.py:1-5, README.md:65-71, README_old.md:8-14
Core Processing CLI
The main CLI entry point simulates the document processing workflow by reading text files (representing OCR output) and executing the detection, extraction, and validation logic.
Primary Command Line Interface
The cli.py script is designed for quick verification of the parsing logic. It utilizes three primary functions from the parsing module:
detect_document_type: Identifies if the text corresponds to a W-2 or 1099 form.extract_fields: Pulls relevant tax data (wages, EIN, SSN) based on the detected type.validate_fields: Checks the extracted data for numeric sanity and required presence.
The diagram shows the sequential flow of data from raw text input to validated console output.
Sources: cli.py:9-32, README_old.md:8-14
Pipeline Execution
For more complex operations involving multiple files and directory outputs, the project provides a CLI interface through pipeline.py. This interface orchestrates the entire lifecycle from ingestion to tax calculation and PDF generation.
| Command Component | Description | Example Value |
|---|---|---|
| Script Name | The Python orchestration script | pipeline.py |
| Output Directory | Path where results and PDFs are saved | ./output/ |
| Input Path(s) | One or more paths to text/image files | samples/sample_w2.txt |
Sources: pipeline.py:101-108, README.md:120-128
Development and PDF Tools
The project includes specialized CLI tools for managing the PDF templates and inspecting form data.
PDF Field Inspection
The tools/inspect_pdf_fields.py utility allows developers to identify the internal AcroForm field names of a PDF. This is critical for the auto_mapper system to correctly fill out tax forms.
Usage Pattern:
python tools/inspect_pdf_fields.py path/to/form.pdf -o fields.json
Sources: README.md:68-71, templates/README.md:5-10
Synthetic Template Generation
The tools/generate_sample_1040_template.py script generates a mock fillable PDF. This tool is used to create a test environment for the forms.py module to practice field mapping.
This sequence illustrates the creation of a synthetic tax form for development purposes.
Sources: tools/generate_sample_1040_template.py:11-30
Command Reference Table
| Tool | Purpose | Usage Example |
|---|---|---|
cli.py | Basic parsing and validation test | python cli.py samples/sample_w2.txt |
pipeline.py | Full orchestration (Extraction + Tax + PDF) | python pipeline.py ./out input.txt |
inspect_pdf_fields.py | Extract AcroForm field names | python tools/inspect_pdf_fields.py template.pdf |
generate_sample_1040_template.py | Create a mock 1040 for testing | python tools/generate_sample_1040_template.py |
pytest | Run the full automated test suite | python -m pytest |
Sources: README.md:65-80, README_old.md:16-24, pipeline.py:103-104
Summary
The CLI tools provide a robust interface for local document processing, allowing for rapid iteration of parsing rules and template mapping. While the web interface is preferred for end-users, the cli.py and pipeline.py scripts remain essential for developers to verify document classification and extraction accuracy against raw text inputs.
Sources: README_old.md:27-31, README.md:154-162