Metadata-Version: 2.4
Name: taxbrainai-compute
Version: 0.1.0
Summary: Deterministic, citation-backed Indian income-tax computation (Decimal, property-tested).
Project-URL: Homepage, https://github.com/harshil-projects/taxbrainai-compute
Project-URL: Source, https://github.com/harshil-projects/taxbrainai-compute
Project-URL: Issues, https://github.com/harshil-projects/taxbrainai-compute/issues
Author: Harshil
License: MIT
License-File: LICENSE
Keywords: 115BAC,capital-gains,decimal,finance,income-tax,india,tax
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://taxbrainai.harshilprojects.com) —
an LLM agent should *call* this for any number, never hallucinate one.

```python
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

```bash
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`](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.
