taxbrainai-compute 0.1.0

Deterministic, citation-backed Indian income-tax computation (Decimal, property-tested).

taxbrainai-compute

Deterministic, citation-backed Indian income-tax computation. A small, dependency-free Python library that computes income-tax for resident individuals / HUFs using Decimal arithmetic, with every rate pinned to its primary statutory source and stamped by assessment year so it can never silently compute the wrong year.

This is the deterministic compute core behind TaxBrainAI — an LLM agent should call this for any number, never hallucinate one.

from taxbrainai_compute import compute, TaxInput, Regime

# Salaried, gross ₹12,75,000, let the engine pick the cheaper regime
res = compute(TaxInput(salary_income=1275000), regime=Regime.AUTO)
print(res.recommended_regime)   # "new"
print(res.chosen.total_tax)     # Decimal('0')  -> ₹12L taxable is fully rebated under Section 87A

Why it exists

LLMs are unreliable at arithmetic and at remembering year-specific rates. taxbrainai-compute moves the math out of the model: deterministic, auditable, unit-tested. Each Breakdown carries the section citations and human-readable notes (e.g. "Section 87A marginal relief applied (new regime; total income just above Rs.12,00,000)."), so an answer can show its working.

What it computes (AY 2026-27 / FY 2025-26)

• Both regimes — new (Section 115BAC(1A)(iii)) and old (Finance Act 2025, First Schedule Part III), with Regime.AUTO returning the cheaper one plus both breakdowns.
• Standard deduction Section 16(ia) — ₹75,000 (new) / ₹50,000 (old) for salaried.
• Section 87A rebate — ₹60,000 / ₹12L (new) and ₹12,500 / ₹5L (old), including new-regime marginal relief (proviso (b)) when income just crosses ₹12L.
• Capital gains (transfer on/after 23-Jul-2024): Section 111A STCG @ 20%, Section 112A LTCG @ 12.5% over the ₹1,25,000 aggregate exemption, Section 112 LTCG @ 12.5% — with the land/building lower-of (12.5% unindexed vs 20% indexed) option for assets acquired before 23-Jul-2024 (CII indexation).
• Basic-exemption absorption — a resident's unused basic exemption is set off against special-rate capital gains (provisos to Section 111A/112/112A).
• Surcharge with marginal relief at ₹50L/₹1Cr/₹2Cr/₹5Cr, the 15% cap on capital-gains/dividend surcharge (FA 2022), and the 25% cap under the new regime.
• Health & Education Cess @ 4%.
• Virtual digital assets - Section 115BBH flat 30% (only cost of acquisition deductible; no loss set-off, no rebate, no basic-exemption absorption).
• Statutory rounding — Section 288A (total income) and Section 288B (tax) to the nearest ₹10.
• Presumptive income — Section 44AD (6% digital / 8% cash), Section 44ADA (50%), Section 44AE (per-vehicle) helpers for ITR-4; the deemed income flows into the normal computation.
• AMT (Section 115JC) — Alternative Minimum Tax for deduction-heavy ITR-3 cases (old regime): 18.5% of adjusted total income, payable as max(regular, AMT), with Section 115JD credit reported.

Install

pip install taxbrainai-compute            # runtime has zero dependencies
pip install "taxbrainai-compute[dev]"     # adds pytest, hypothesis, and ruff

Accuracy & scope (read before relying on it)

• Scope: resident individuals / HUF, AY 2026-27, covering the four personal-tax returns ITR-1 / 2 / 3 / 4. The tax computation is shared across all four (it applies to total income regardless of form). Regular business net profit (ITR-3) flows through at slab rates; presumptive income (ITR-4) is computed via the Section 44AD/ADA/AE helpers; AMT (Section 115JC) is computed for deduction-heavy ITR-3 cases (old regime; the higher of regular tax or AMT is payable). Out of scope: ITR-5/6/7 (firms/companies/trusts), GST, full non-resident provisions, loss set-off/carry-forward, advance-tax interest (234A/B/C), and clubbing.
• Interpretive choices are documented in notes. Two genuinely contested areas are handled conservatively and flagged: (1) under the new regime, Section 87A rebate is applied to slab tax only (not to special-rate capital gains), matching the post-2024 e-filing utility position; (2) basic-exemption absorption order is highest-rate-first (most beneficial to the assessee). Both are cited in code.
• Known data gap: the Cost Inflation Index table is encoded from the CBDT-notified figures (the live corpus scrape of the CII page returned the site shell); it is used only for the Section 112 land/building indexed option.
• Import side effect: the library sets the global decimal context precision to 34 significant digits (ample for rupee arithmetic; noted for embedders).
• Validated: 139 tests at 100% statement coverage, including 20 Hypothesis property invariants (~10,000 generated scenarios/run). Cross-checked against all four official Income-Tax Dept ITR utilities (AY 2026-27), an independent reference grid, and three oracles — one of which caught a real AMT-surcharge bug, since fixed. See VALIDATION.md.
• Not professional advice. This is software for estimation, provided "as is" without warranty of any kind; it is not tax, legal, or financial advice. Verify against the official e-filing utility and a qualified professional before filing or relying on any figure.

Primary sources

Income-tax Act 1961 (as amended by Finance Act 2025 and Finance Act 2026), Section 115BAC, Section 87A, Section 16, Section 111A, Section 112, Section 112A, Section 115BBH, Section 288A, Section 288B; Finance Act 2025 First Schedule Part III; Finance (No. 2) Act 2024 (23-Jul-2024 capital-gains cutover). Section text in rates.py::CITATIONS.

License

MIT.