tax-doc-classifier

# tax-doc-classifier

A tax document classifier built with Jev.

We ingest thousands of tax documents using an LLM pipeline built last tax season. Jev classifies 100% of our tax document corpus at $0.001 per page — 34× cheaper and 6× faster than that LLM setup. This is the classifier, open sourced.

One request per page. The page's text goes to [Jev](https://docs.typesafe.ai), TypeSafe's decision model, which returns a probability over 261 IRS forms and 7 page kinds instead of text. No model is trained and nothing is hosted: the classifier is a JSON file describing each form, generated from the IRS's own PDFs.

```ts
import { classifyPage, jevBackend, pdfPageLines } from 'tax-doc-classifier'
import criteria from 'tax-doc-classifier/data/criteria.json' with { type: 'json' }

const lines = await pdfPageLines('return.pdf', 3)
const r = await classifyPage(lines, { backend: jevBackend(), criteria })
// r.form            'form-1040-schedule-a'
// r.kind            'form_page'
// r.formConfidence  0.99
// r.gated           true   (formConfidence >= 0.95)
```

No model is trained and nothing is hosted. The classifier is a JSON file of form descriptions (`data/criteria.json`) and a decision model that reads a page and picks from them. The decision model is [TypeSafe Jev](https://docs.typesafe.ai), a System One model that returns a probability over options instead of text.

## Setup

1. **Node 20+ and pnpm.**
2. **poppler** — provides `pdftotext` and `pdfinfo`, used to read PDF pages. Only `classifyPage` on lines of text works without it.
   - macOS: `brew install poppler`
   - Debian/Ubuntu: `apt install poppler-utils`
3. **A TypeSafe API key.** Get one at [typesafe.ai](https://typesafe.ai), then:
   ```
   export TYPESAFE_API_KEY=…
   ```
   or put it in a `.env` file (git-igno