A working example of a governed AI layer for individual (Form 1040) tax prep: it reads a taxpayer's documents, proposes the treatment, and computes the return — without fabricating the math. Two independent open-source tax engines compute the return and cross-check each other. Built in a few hours by composing open-source software.
This is a reference example, not a finished product, and not tax advice. See what a full deployment adds below.
Real 1040 inputs are §6103-protected PII, so there's no public dataset of returns. We don't fabricate the tax owed — we compute it with a real tax engine and cross-validate against a second, independent one:
- Tax-Calculator (CC0 / public domain) — the primary engine; computes AGI, taxable income, and tax.
- PolicyEngine-US (AGPL-3.0) — independent engine used only to cross-validate. Agreement between two implementations of the tax code = correct-by-construction ground truth.
| Path | What |
|---|---|
engine/profiles.py |
Synthetic taxpayer profiles across 8 scenarios + their W-2/1099/1098 source documents |
engine/crossvalidate.py |
Runs each profile through both engines and compares AGI / taxable income / tax |
docs/MANUAL.md |
How the runtime is used, task by task, with the AI-does / you-do boundary and the regulatory limits |
data/PROVENANCE.md |
Every dataset, source, and license |
Result: 600 profiles, 0 errors, 583/600 = 97.2% exact agreement between the two
engines. The disagreements are all the student-loan-interest phase-out (bounded, sub-1% of
tax) — a genuine engine-modeling difference, kept labeled. Sample: data/ground-truth/sample.jsonl.
cd engine
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python taxcalc policyengine-us
COUNT=600 .venv/bin/python crossvalidate.py # -> ../data/ground-truth/returns.jsonlNo Docker — both engines are pip packages.
A FastAPI + MD3 dashboard over the computed returns — the review surface: KPI tiles, a review
queue, and per-return source documents → computed return (both engines side by side) →
agreement, with approve / amend / reject. Disagreements (e.g. the student-loan phase-out) are
surfaced, not hidden. Runs on the committed sample.jsonl out of the box.
cd ui && docker build -t personal-tax-ui . && docker run --rm -p 8301:8301 personal-tax-ui
# or: pip install -r ui/requirements.txt && python3 -m uvicorn app:app --port 8301 (from ui/)Then open http://localhost:8301.
This example is the foundation. A production deployment adds: production document
extraction (real W-2s/1099s), the console / review UI, human-in-the-loop workflows,
multi-tenant auth and SOC 2, e-file / MeF transmission (which requires an IRS Authorized
e-file Provider / EFIN — see docs/MANUAL.md), security and error handling at scale. We'd
love to help build that — redevops.io.
AGPL-3.0 with the section-13 network clause waived. Third-party components and data sources: LICENSES.md. Ship on Tax-Calculator (CC0); keep PolicyEngine (AGPL) internal.