Tax Calculation Engine

Relevant source files

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

• taxcalc.py
• pipeline.py
• backend.py
• forms.py
• tests/test_taxcalc.py

The Tax Calculation Engine is a core analytical module within the Rosy Tax Processor responsible for transforming raw extracted financial data into actionable federal tax estimates. It computes Adjusted Gross Income (AGI), applies standard deductions based on filing status, and calculates progressive tax liabilities using configurable tax brackets.

This engine serves as the bridge between the Document Processing Pipeline and the Form Generation System, ensuring that the values populated in the final Form 1040 are mathematically accurate based on the provided inputs.
Sources: README.md:12-16, taxcalc.py:59-66

Architecture and Logic Flow

The engine operates as a stateless utility that accepts aggregated financial fields and returns a structured dictionary of tax results. It utilizes a progressive taxation model where income is distributed across specific percentage tiers (brackets).

Data Flow Diagram

The following diagram illustrates how financial data moves from ingestion to the final tax estimate calculation.

Key Components

1. Tax Bracket Management

The engine dynamically loads tax brackets from an external configuration file. If the file is missing, it reverts to a hardcoded fallback set of 2023-style brackets for "Single" and "Married" filing statuses.

Component	Logic	Reference
_load_brackets()	Attempts to read tax_brackets.json; falls back to built-in dict.	taxcalc.py:17-42
STANDARD_DEDUCTIONS	Hardcoded values: Single ($13,850) and Married ($27,700).	taxcalc.py:10-14

2. Progressive Tax Calculation

Taxation is calculated using the _compute_progressive_tax_for_brackets function, which iterates through income tiers. For income exceeding the defined brackets, a flat demo rate of 32% is applied to the remainder.

# Simplified logic from taxcalc.py:45-56
for b in brackets:
    upper = float(b['upto'])
    rate = float(b['rate'])
    taxable_in_bracket = min(taxable, upper) - lower
    if taxable_in_bracket > 0:
        tax += taxable_in_bracket * rate
    lower = upper

Sources: taxcalc.py:45-57

Data Structures

Input Parameters

The primary entry point is compute_tax_estimate, which processes the following data:

Parameter	Type	Description
extracted_fields	Dict[str, Any]	Map containing keys like 'wages' or 'amount' (parsed from W-2/1099).
filing_status	str	Either 'single' or 'married'.
withholding	float	Total tax already paid/withheld.

Output Schema

The engine returns a standardized dictionary used for UI display and PDF generation:

Field	Type	Description
agi	float	Total sum of all income sources.
standard_deduction	float	Deduction amount based on status.
taxable_income	float	AGI minus deduction (minimum 0.0).
gross_tax	float	Calculated tax before withholding.
tax_due	float	Final amount (Positive = Owed, Negative = Refund).

Sources: taxcalc.py:59-99, backend.py:115-127

Integration with Pipeline

The engine is integrated into the pipeline.py orchestration layer. The pipeline aggregates income from multiple files (e.g., multiple W-2s) before invoking the calculation.

Validation and Testing

The engine's accuracy is verified via tests/test_taxcalc.py, ensuring correct standard deduction application and tax due results for both Single and Married filing statuses.

• Test Single: Validates AGI of $50,000 results in taxable income of $36,150.
• Test Married: Validates AGI of $120,000 results in taxable income of $92,300.

Sources: tests/test_taxcalc.py:4-22

Summary

The Tax Calculation Engine provides a robust, bracket-based computation system that handles the financial logic of the Rosy Tax Processor. By separating income aggregation, deduction application, and progressive tier calculation, it ensures a modular approach to federal tax estimation that can be easily updated via the tax_brackets.json configuration.