kyotofin/tax-doc-classifier

What it solves

It provides a high-efficiency way to classify tax documents into specific IRS forms and page types. It replaces expensive and slow LLM-based classification pipelines with a decision-model approach that is significantly cheaper (34×) and faster (6×) while supporting a much larger library of forms (261 vs 30).

How it works

The system uses TypeSafe Jev, a decision model that returns probabilities over a set of options rather than generating text.

1. Text Extraction: PDF pages are converted to text using pdftotext (poppler).
2. Classification: The text is sent to Jev, which compares it against a JSON criteria file (criteria.json) containing descriptions of IRS forms generated directly from official IRS PDFs.
3. Hierarchical Logic: It first determines the page kind (e.g., form page, instructions, blank) and the form ID. For complex corporate or foreign forms, a second request is made to identify the specific schedule.
4. Confidence Gating: The system provides a formConfidence score; users can set a threshold (e.g., 0.95) to decide whether to trust the result or fall back to another method.

Who it’s for

Developers building tax software or financial document processing pipelines who need to accurately identify federal IRS forms at scale without the high cost and latency of general-purpose LLMs.

Highlights

• Cost and Speed: Reduces cost to approximately $0.001 per page and latency to ~0.5s per page.
• Extensive Coverage: Supports 261 IRS forms and 7 page kinds.
• Automated Criteria: The criteria.json file is automatically generated from official IRS XLSX and PDF sources.
• Model Agnostic: While it ships with jevBackend, the Backend interface allows for other models that can return calibrated probabilities over labeled options.