tenforty

Overview

tenforty is an open-source Python package designed to help demystify US federal and state tax computations. It offers an accessible way to explore tax scenarios, compare different tax situations, and understand how the inputs to a return affect what you owe. It's particularly useful for sensitivity analysis, what-if sweeps, and optimizing your taxes.

The package is built on top of Open Tax Solver (OTS) and tenforty's own backend, wrapping them into a Python library. The ideas behind it are discussed in a blog post here.

You can try tenforty out immediately in your browser via the included Colab notebook:

Features

• Compute US federal taxes and state taxes, back to the 2018 tax year.
• Explore how taxes vary as a function of income, state, filing status, and year.
• Evaluate "what if" tax scenarios efficiently and reproducibly, with results in a polars dataframe.
• Validated inputs with informative error messages, which make it a good tool-call target for a coding agent.

Disclaimer

tenforty is an open-source tool intended for informational and educational purposes only and does not provide tax advice. Known limitations are detailed in the Limitations section below.

Installation

pip install tenforty

Python 3.10–3.15 is supported on Linux and macOS. Windows is not supported; see Known Limitations for workarounds.

Building from source

pip install tenforty uses a prebuilt wheel where one matches your platform: CPython 3.10–3.15 on Linux x86_64 and aarch64 (glibc 2.28+ and musl) and on macOS arm64 and x86_64. Elsewhere it builds from the source distribution, and that build needs a Rust toolchain as well as a C++ compiler, because the graph backend is compiled from Rust. Without Rust the build stops and explains why; it no longer installs a package that lacks the graph backend.

Requiring Rust for a source build is an intermediate measure. The long-term answer is a prebuilt wheel for every platform, so that building from source is only the fallback for platforms without one.

To build the legacy OTS-only package instead, without Rust, set TENFORTY_WITHOUT_GRAPH=1:

TENFORTY_WITHOUT_GRAPH=1 pip install tenforty

That package has no graph backend: backend="ots" works, and any return routed to the graph backend raises an error instead of falling back to OTS.

Which Backend Computes Your Return

The default, backend="auto", picks the engine for each return before computing it:

• Graph scope. A 2024–2025 state goes to graph only when its known graph-side defects are closed and official values support it. The other states stay out for a named reason: an open defect, missing evidence, or a decision. Graph state scope has the reasons. MD, ME and NC wait on the itemized-deduction contract (tenforty-nuc6). Ohio stays on OTS by decision: graph Ohio Married/Joint requires the joint-credit state fact, which has no default, and since OTS already computes Ohio, routing it to graph would make calls that work today raise. Mississippi, which OTS doesn't cover, requires its facts instead of being unavailable.
• Mississippi needs facts. MS is in graph scope, conditional on state facts with no default. A Married/Joint return needs both spouses' actual Mississippi AGIs, state_facts.MS(taxpayer_adjusted_gross_income=..., spouse_adjusted_gross_income=...); a Widow(er) return needs MS(head_of_family_eligible=...) (Head_of_House defaults to the documented resident-dependent baseline). Without them the call raises UnsupportedInputError before computing. MS Married/Joint state and total-tax derivatives and solves over household income are unsupported, and a nonzero schedule_1_income, state_adjustment, dependent_exemptions, itemized_deductions, state_and_local_taxes or federal_itemized regular-tax amount is refused for MS: itemizing on MS is not supported through either itemized input.
• The earned income credit needs facts. eitc_eligible=False gives a determined 0, with no child count needed. eitc_eligible=True with num_eitc_children computes the credit. Otherwise it is None (not determined), and graph Missouri returns raise; eitc_eligible=False is accepted there. OTS always reports None.
• OTS is chosen by coverage, not as a retry. A state goes to OTS because it is outside graph scope and OTS computes it. A return that fails on the graph backend is not rerun on OTS.
• An explicit backend is never reinterpreted. backend="ots" computes on OTS and backend="graph" on graph, or the call raises before computing. backend="ots" gives the OTS results earlier releases defaulted to. It does not restore every earlier contract: the deduction election, the frame schema and the error behavior changed for both backends. See Migrating to the graph default.
• The OTS-only package (TENFORTY_WITHOUT_GRAPH=1) has no graph backend, so a return the default routes to graph raises BackendUnavailableError there.

Quick Start

The evaluate_return function computes the outputs for a single tax return given some inputs:

from tenforty import evaluate_return

evaluate_return(
    w2_income=100_000, state="CA", filing_status="Married/Joint", num_dependents=2
).model_dump()

This results in the following:

{'total_tax': 4476.0,
 'federal_adjusted_gross_income': 100000.0,
 'federal_effective_tax_rate': 4.884671532846715,
 'federal_tax_bracket': 12.0,
 'federal_taxable_income': 68500.0,
 'federal_qbi_deduction': 0.0,
 'federal_amt': 0.0,
 'federal_income_tax': 3346.0,
 'federal_se_tax': 0.0,
 'federal_niit': 0.0,
 'federal_additional_medicare_tax': 0.0,
 'federal_child_tax_credit': 4400.0,
 'federal_earned_income_credit': None,
 'federal_total_tax': 3346.0,
 'state_adjusted_gross_income': 100000.0,
 'state_taxable_income': 88588.0,
 'state_total_tax': 1130.0,
 'state_tax_bracket': 6.0,
 'state_effective_tax_rate': 1.2755677969928207,
 'assumptions': ()}

No year= argument was specified here, so the default year, 2025, was used. California is outside graph scope, so this return was computed on OTS. The output is a pydantic model, and we've called its .model_dump() method to show the result as a dictionary. Every argument and output field is listed in the API Reference.

Previewing Your Own Return with a Coding Agent

The most practical way to use tenforty on your own taxes today is to let a coding agent drive it, such as Claude Code, Codex, or an open-source agent like pi or OpenCode. You describe your situation in plain language, and the agent maps your figures onto tenforty's inputs, runs the return, and answers follow-up questions by changing inputs and re-running.

How much to trust the result depends on what your return contains. The evidence summary says, for each kind of return the default computes, what is checked against independent published values and what is only checked for agreement between the backends, against snapshots, or by property tests. Tax-Calculator serves as an independent federal model (differential audit). It's still a preview, not a filing: nothing is guaranteed, and the usual way it goes wrong is a figure from your documents that the agent maps to the wrong input or that tenforty doesn't model (see the API Reference and Known Limitations). It's well suited to "what will I owe, and why?" and "what happens if I sell this stock in December?" before you file with your usual software or preparer, and to cross-checking that software afterwards.

1. Decide where your data goes. Your return is about as sensitive as personal data gets, and everything you tell the agent is sent to whichever model provider it uses. That's a choice worth making deliberately, and it's yours to make:

• If you use a hosted agent from Anthropic, OpenAI, or another provider, read that provider's data-retention and training policies for the plan you're on.
• Open-source agents such as pi and OpenCode can point at other endpoints, including inference providers that offer zero data retention, such as DeepInfra or Together AI. Check their current terms yourself.
• For the most privacy, run a model locally with a tool like llama.cpp, Ollama, or LM Studio, so nothing leaves your machine.

2. Consider giving it numbers, not documents. Transcribing the figures you need (W-2 box 1, 1099-INT and 1099-DIV totals, net short- and long-term gains, and so on) shares far less than scans that carry your SSN and account numbers.

3. Work in a scratch directory and let the agent install tenforty there:

mkdir tax-preview && cd tax-preview
uv venv && uv pip install tenforty

4. Ask, and ask for the mapping back. For example:

Use the tenforty Python package (read its README for the inputs) to estimate my 2025 federal and California taxes. Married filing jointly, two kids. W-2 box 1: $182,400 and $64,100. 1099-INT: $1,150. 1099-DIV: $3,200 ordinary, $2,600 qualified. Long-term gains: $12,000. Before running anything, show me how you mapped each of my figures to a tenforty input, and list anything I gave you that tenforty can't represent.

The last instruction matters most. A figure the agent silently drops, or puts in the wrong input, is the most likely way to get a confidently wrong answer. One common trap: ordinary_dividends is the total (1099-DIV box 1a) and already includes qualified_dividends (box 1b).

Once the baseline matches your expectations, the follow-ups are where the package earns its keep: sweeps over a gain you haven't realized yet, or how close you are to AMT.

Examples

Here are some more examples of what you can do with tenforty:

Creating Tax Tables: Federal/State Tax Brackets as a Function of W2 Income

The evaluate_returns method sweeps out a grid over any input arguments that are provided as lists, allowing you to evaluate a wide array of tax scenarios. Here we make a simple tax table by varying W2 income:

from tenforty import evaluate_returns

evaluate_returns(
    w2_income=list(range(50_000, 250_001, 50_000)),
    state="CA",
    filing_status="Married/Joint",
    num_dependents=2,
)[
    [
        "w2_income",
        "federal_effective_tax_rate",
        "federal_tax_bracket",
        "state_effective_tax_rate",
        "state_tax_bracket",
    ]
]

This results in a polars.DataFrame (use .to_pandas() if you need pandas compatibility). The rates are percentages, shown here to two decimals. The effective rates divide by taxable income:

Plot: Federal Tax as a Function of W2 Income

Since the output is a dataframe, one may readily use any of numerous visualization tools to make plots. The plots here use seaborn, which takes a pandas frame, so they need pip install seaborn pyarrow and call .to_pandas(). Here we revisit the example above, evaluating a wider range of W2 incomes at finer resolution than before.

import seaborn.objects as so

df = evaluate_returns(w2_income=list(range(0, 250_001, 1_000)))

(
    so.Plot(df.to_pandas(), x="w2_income", y="total_tax")
    .add(so.Line())
    .label(
        x="W2 Income", y="Federal Tax", title="Federal Tax as a Function of W2 Income"
    )
)

Plot: Federal Tax Over Time

One can just as easily vary the year as any other parameter. tenforty supports back to the 2018 tax year; under the default, 2018–2023 are computed on OTS (whose authors have published an edition every year for over two decades) and 2024–2025 on the graph backend. Here we show the federal tax on $100K of W2 income for each supported year.

import polars as pl

df = evaluate_returns(
    year=[2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025], w2_income=100_000
).cast({"year": pl.Utf8})

(
    so.Plot(df.to_pandas(), x="year", y="total_tax")
    .add(so.Line())
    .add(so.Dot())
    .label(
        x="Year",
        y="Federal Tax",
        title="Federal Tax on $100K W2 Income Over Time",
    )
)

This one's a little melodramatic because we don't make the y-axis go to zero; it's only about a 3% drop over the years.

Plot: Impact of Long-Term Capital Gains

Both backends compute short- and long-term capital gains -- although, see the Limitations section below -- so you can ask questions about the impact on your taxes of selling some appreciated stock this year, and show the breakdown between state and federal taxes:

import polars as pl

df = (
    evaluate_returns(
        w2_income=75_000,
        state="CA",
        long_term_capital_gains=list(range(0, 125_001, 5000)),
    )
    .select(["long_term_capital_gains", "state_total_tax", "federal_total_tax"])
    .unpivot(index="long_term_capital_gains", variable_name="Type", value_name="tax")
    .with_columns(
        pl.col("Type").replace(
            {"state_total_tax": "State", "federal_total_tax": "Federal"}
        )
    )
)

(
    so.Plot(df.to_pandas(), x="long_term_capital_gains", y="tax", color="Type").add(
        so.Area(alpha=0.7), so.Stack()
    )
    .label(
        x="Long-Term Capital Gains",
        y="Total Tax",
        title="Impact of LTCG on Total Tax for California Resident",
    )
)

Plot: Will I Incur Alternative Minimum Tax (AMT)?

Employees at tech companies are commonly issued incentive stock options, the exercise of which can put them in a situation where they need to pay actual money in taxes on paper gains, via the alternative minimum tax. With tenforty's help you can see it coming at least: ;)

federal_total_tax already includes the AMT, so the stack below splits it into the tax excluding AMT and the AMT itself; the two layers sum to the total.

import polars as pl

df = (
    evaluate_returns(
        w2_income=100_000, incentive_stock_option_gains=list(range(0, 100_001, 2500))
    )
    .with_columns(
        excluding_amt=pl.col("federal_total_tax") - pl.col("federal_amt")
    )
    .select(["incentive_stock_option_gains", "excluding_amt", "federal_amt"])
    .unpivot(index="incentive_stock_option_gains", variable_name="Type", value_name="tax")
    .with_columns(
        pl.col("Type").replace(
            {"federal_amt": "AMT", "excluding_amt": "Tax excluding AMT"}
        )
    )
)

(
    so.Plot(df.to_pandas(), x="incentive_stock_option_gains", y="tax", color="Type")
    .add(so.Area(alpha=0.7), so.Stack())
    .label(
        x="Incentive Stock Option Gains",
        y="Total Federal Tax",
        title="Effect of ISO Gains on Federal Alternative Minimum Tax\nGiven $100K W2 Income",
    )
)

API Reference

The two functions evaluate_return and evaluate_returns are the main interface to tenforty. They take exactly the same arguments, except that any of the arguments to evaluate_returns may either be a single value, or a list of values. evaluate_return evaluates one single return, and evaluate_returns evaluates all combinations of inputs subtended by the provided values and collects the results into a dataframe.

The inputs to either function are validated, and if for example a filing status is misspelled, you'll get an informative error message along with a list of the valid options. Error Handling describes the on_error policies and exception types.

Arguments

state_adjustment (deprecated)

state_adjustment is a legacy escape hatch with no single meaning, and a nonzero value emits a DeprecationWarning. We recommend against new use; named single-meaning inputs will replace it (tenforty-tj2.1, tenforty-tj2.2). CA and AL stay out of backend="auto" graph scope while it means different things on the two backends (tenforty-yu51).

The evaluate_returns frame

Every frame has the same columns, in the same order, with the same dtypes, whichever backend computed it and whether the batch is empty, succeeded, partly failed, or mixed engines under backend="auto":

• the inputs, in the order of the evaluate_returns signature (year through spouse_65_or_older, then the keyword-only num_ctc_dependents, tax_exempt_interest, num_eitc_children, eitc_eligible, federal_itemized_regular_tax, federal_itemized_amt and state_facts), then the return fields of InterpretedTaxReturn;
• year, num_dependents and num_ctc_dependents are Int64; num_eitc_children is a nullable Int64, eitc_eligible a nullable Boolean, and the two federal_itemized_* echoes nullable Float64 (null when not supplied); state, filing_status, standard_or_itemized and state_facts are String (state is null for a federal-only return, state_facts the canonical JSON of the model for the row's state, or null); boolean inputs are Boolean; float inputs and every numeric output are Float64, even when you pass whole numbers; assumptions is List(String), each element one record's JSON;
• the four rate columns (federal_tax_bracket, federal_effective_tax_rate, state_tax_bracket, state_effective_tax_rate) are null where the rate is not defined. A failed row has NaN in every numeric output and a null assumptions.

The input columns echo your request, after broadcasting: they identify which return a row answers, not the values the engine used. For example, an ordinary_dividends below qualified_dividends is lifted before computing, but the frame shows the value you passed.

In mode="cross" the rows are the Cartesian product of the inputs, taken in signature order (the first argument varies slowest). In mode="zip" row i answers the i-th element of each list.

The three qbi_ inputs describe one trade or business, or businesses the taxpayer has validly aggregated for section 199A. They are not totals across unrelated businesses, because Form 8995-A applies its wage and UBIA limitation per business or valid aggregation. Their defaults model a non-SSTB business with no business W-2 wages or qualified property. The OTS backend uses OTS's Form 8995 for the independent QBI base and taxable-income ceiling, then applies the missing Form 8995-A wage, property, and SSTB limitation in tenforty's orchestration layer before rerunning Form 1040.

Outputs

The bracket fields are the rate schedule's own bracket, not marginal_rate(), which is the graph's planning sensitivity (see Marginal Rates for Every Input). The graph reports state brackets for CA, NJ, NY, OH, OR and VA at full precision; OTS prints its bracket to 0.1%, so the two can differ in the last digit (NY 6.85% is 6.9 on OTS).

The Graph Backend

The graph backend computes the default's 2024–2025 federal returns and its graph-scope states (see Which backend computes your return). Tax forms are written in a Haskell DSL (tenforty-spec/), compiled to JSON graphs, and evaluated by a Rust runtime exposed to Python. Because the whole return is one differentiable graph, it can report planning sensitivities and solve for inputs, which OTS can't. It is included in the published wheels.

To force one backend, pass it explicitly. backend="graph" computes any state the graph covers, in scope or not; Migrating to the graph default lists every difference to expect between "ots" and "auto":

evaluate_return(year=2025, state="CO", w2_income=100_000, backend="graph")
evaluate_return(year=2025, w2_income=100_000, backend="ots")

Compared with the OTS backend:

• It covers the 2024 and 2025 tax years only.
• It supports many more states: in addition to the OTS states, AL, AR, CO, CT, DC, DE, GA, HI, IA, ID, IL, IN, KS, KY, LA, MD, ME, MN, MO, MS, MT, ND, NE, NH, NM, OK, RI, SC, UT, VT, WI, and WV.
• Not every input is mapped for every state. It raises on an input it can't represent rather than dropping it.
• It takes dependent_exemptions, state exemption dollars (not a count), for the states that use them. OTS has no such input and refuses a nonzero value.

Two function families exist only on this backend and take the same return arguments as evaluate_return:

• marginal_rates(...) gives the planning sensitivity of an output to every continuous input at once; marginal_rate(..., wrt=...) does one input.
• solve_for_income(target_tax, ..., for_input="w2_income") finds the value of one input that produces a target output.

Marginal Rates for Every Input

marginal_rates reports how a selected output responds to every continuous public input at once:

from tenforty import marginal_rates

rates = marginal_rates(
    year=2024,
    state="CA",
    filing_status="Single",
    w2_income=100_000,
)

rates["w2_income"]

The returned dictionary uses the same natural input names as evaluate_return. It includes federal inputs and any continuous inputs mapped by the selected state; discrete choices such as filing status and number of dependents are omitted. The existing marginal_rate(..., wrt="w2_income") function remains available for one input at a time.

Tax calculations are piecewise functions. At a bracket, phase-out, or other active boundary, both marginal-rate APIs report the composed function's right-hand derivative: the change implied by adding a small amount to that input. Smooth entries in marginal_rates share one reverse-mode traversal per resolved output.

These are planning sensitivities, not always the literal derivative of the tax you file. Below $100,000 of taxable income the federal tax comes from the Tax Table, a staircase of $50 rows (and some states use similar tables): the literal slope is zero inside a row and a jump at its edge. There the graph reports the planning slope, the rate at the table row's midpoint: the bracket rate the rows step through, not the zero inside a row. Some comparisons of nearly equal amounts can also take the wrong side of a tie in floating point, which is tracked as tenforty-msj2.

The reproducible autodiff planning examples show a full next-dollar table, the interaction between wages and long-term-gain stacking, and a bounded ordinary-income sizing exercise. They also measure where forward simulation remains competitive and explain why derivatives alone cannot find true tax cliffs.

Known Limitations

• Currently does not support Windows. The Colab notebook linked above, or using WSL are workarounds. Attempts have been made to get Windows builds working, but runtime crashes persist due to compiler interoperability challenges; see Windows Build Research for details.
• Net Investment Income Tax (Form 8960) and Additional Medicare Tax (Form 8959) are computed for the 2024 and 2025 tax years only. For earlier years they are reported as zero, so if they apply to your situation the total tax will be underestimated.
• Evidence is uneven across states and income types; the evidence summary says what is independently checked for each kind of return the default computes.

Related Projects

A few excellent open-source projects approach US tax computation from different angles. They are research tools, built for economists modeling policy and populations, and for that work one of them may fit better:

• Tax-Calculator (Policy Simulation Library) is a federal income and payroll tax microsimulation model with a long pedigree in the policy-economics world. Its special power is counterfactual law: every rate, bracket, and phase-out is a reformable parameter, so it can answer "what would this filer (or the whole country) pay under a proposed reform?" It models per-spouse income attribution and has been validated against NBER's TAXSIM for years. If your question is about policy analysis, revenue estimation, or distributional effects, start there. tenforty runs a differential test of its own federal results against Tax-Calculator — see docs/taxcalc-differential-audit.md.
• TAXSIM (NBER) is the long-standing academic reference model for US federal and state income taxes, callable remotely.
• PolicyEngine-US models federal and many state taxes alongside benefit programs, with a policy-reform focus similar to Tax-Calculator's.

tenforty is built for a different use case: evaluating an individual return, what it comes to and what would happen if something changed, without clicking back through five screens of tax software to find out. That is its express purpose, not a side use. It's a library first: one function call, plainly named inputs (w2_income, long_term_capital_gains), validated arguments with error messages that tell you (or your agent) what to fix, federal and state computed together, and a dataframe out when you sweep a grid of scenarios. The research models above can evaluate a single return too, but you or your agent have to learn their input conventions first. With tenforty that work is already done; on the graph backend it also gives planning sensitivities and an input solver.

Development & Contributing

Contributions are welcome! See our Contributing Guidelines for the development process and coding standards.

Documentation for developers:

• Development Guide - Package internals, Cython extensions, and environment setup
• Error Handling - Configuring on_error policies and exception types
• Evidence summary - What is independently evidenced, per kind of return
• IRS Validation - Historical record of the official-source test methodology

License

tenforty is released under the MIT License.

Acknowledgments

This project relies on the Open Tax Solver project for the underlying tax computation logic.