fix(tax): correct slabs to current law + single source of truth

- tax_rules.json: current new-regime slabs (0-4L..24L+), 87A rebate at 12L/60k
  with marginal relief, and special rates STCG 20% / LTCG 12.5% / 1.25L exemption
- app/core/tax_rules.py: single loader read by both calculators and the agent's
  retrieve_tax_rules_tool; removed duplicated hardcoded slab functions
- new-regime 87A marginal relief implemented (tax capped at income over the limit)
- README: Links + Team sections, honest "prepares a file-ready return" scope note
- frontend: drop year label, reframe overclaiming copy
- tests updated to current rates (174 passing)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: HR-coding

README.md

@@ -11,6 +11,19 @@ untrusted and can never tamper with tax data or leak personal information.
 
 > Architecture details: see **[SYSTEM_ARCHITECTURE.md](SYSTEM_ARCHITECTURE.md)**.
 
+## Links
+
+- **Live app:** https://taxassist-267786664719.asia-south1.run.app/
+- **Demo video (≤3 min):** <!-- TODO: paste the public YouTube/Vimeo URL here -->
+- **Partner track:** **MongoDB** — via the official MongoDB MCP server (see [MongoDB MCP integration](SYSTEM_ARCHITECTURE.md#mongodb-mcp-integration)).
+- **License:** [Apache-2.0](LICENSE) — also set in the GitHub repo's *About* sidebar.
+
+## Team
+
+<!-- TODO: list every team member (name — role / handle). All members must also be added on the submission form. -->
+- _Your Name_ — role
+- _Teammate_ — role
+
 ---
 
 ## What it does
@@ -19,12 +32,18 @@ untrusted and can never tamper with tax data or leak personal information.
   with Gemini 2.5-flash vision (handles dense tables and scans).
 - **Human-in-the-loop over email**: emails the user to confirm extracted values /
   approve computation; reads the replies and resumes — as durable, resumable runs.
-- **Deterministic tax engine**: ITR-1 & ITR-2 computed from gov slab rates (no LLM in
-  the math), old vs new regime comparison.
+- **Deterministic tax engine**: ITR-1 & ITR-2 computed from official slab rates (no LLM in
+  the math), old vs new regime comparison, with section 87A rebate and new-regime marginal
+  relief. All rates live in a **single source of truth** (`app/core/tax_rules.json`) that the
+  calculators and the agent's `retrieve_tax_rules_tool` both read — so they can never diverge.
 - **Google Workspace**: Gmail, Calendar (deadline reminders), Sheets (findings + result),
   Drive — per user.
 - **Multi-tenant**: one account → many profiles (e.g. self + spouse), each isolated.
 
+> **Scope:** TaxAssist prepares a **file-ready** return — it extracts, verifies, computes and
+> writes the results to your Google Sheet. It does **not** submit to the income-tax portal;
+> the final e-filing step stays with you. Surcharge on incomes above ₹50L is not yet modelled.
+
 ## Tech stack
 
 | Layer | Tech |

app/core/itr1_calculator.py

@@ -1,11 +1,14 @@
 """
-Deterministic ITR-1 tax calculator for FY 2025-26 (AY 2026-27).
-Source: https://www.incometaxindia.gov.in/
+Deterministic ITR-1 tax calculator.
+Slab rates, rebate and cess are loaded from the single source of truth
+(tax_rules.json via app.core.tax_rules), grounded in
+https://www.incometaxindia.gov.in/.
 
 Reads from the new array-based schema (schemas.jsonc).
 Supports both old and new tax regimes.
 """
 from app.core.field_calculator import _sum_list, _nf
+from app.core import tax_rules
 
 
 def calculate_itr1_tax(itr_doc: dict) -> dict:
@@ -29,7 +32,7 @@ def calculate_itr1_tax(itr_doc: dict) -> dict:
     if net_salary == 0.0:
         gross = _nf(si, "gross_salary")
         exempt = _nf(si, "exempt_allowances")
-        std_ded = 75000.0 if tax_regime == "NEW" else 50000.0
+        std_ded = tax_rules.standard_deduction(tax_regime)
         professional_tax = _nf(si, "professional_tax")
         net_salary = max(gross - exempt - std_ded - professional_tax, 0.0)
 
@@ -62,21 +65,11 @@ def calculate_itr1_tax(itr_doc: dict) -> dict:
 
     taxable_income = max(gross_total_income - total_deductions, 0.0)
 
-    # ── Tax slab computation ──────────────────────────────────────────────
-    if tax_regime == "OLD":
-        tax = _compute_old_regime_tax(taxable_income)
-        rebate_limit = 500000.0
-        rebate_max = 12500.0
-    else:
-        tax = _compute_new_regime_tax(taxable_income)
-        rebate_limit = 700000.0
-        rebate_max = 25000.0
-
-    # Section 87A rebate
-    if taxable_income <= rebate_limit:
-        tax = max(tax - min(tax, rebate_max), 0.0)
-
-    tax = round(tax * 1.04, 2)  # 4% cess
+    # ── Tax slab computation (rates from the single source of truth) ──────
+    tax = tax_rules.slab_tax(taxable_income, tax_regime)
+    # Section 87A rebate (+ new-regime marginal relief just above the limit)
+    tax = tax_rules.apply_rebate_and_relief(taxable_income, tax, tax_regime)
+    tax = round(tax * (1.0 + tax_rules.cess_rate(tax_regime)), 2)  # health & education cess
 
     # ── Taxes paid ────────────────────────────────────────────────────────
     tp = itr_doc.get("taxes_paid", {})
@@ -141,35 +134,3 @@ def calculate_itr1_with_comparison(itr_doc: dict, chosen: str = "NEW") -> dict:
         "new_regime_payable": new["net_tax_payable"],
         "old_regime_payable": old["net_tax_payable"],
     }
-
-
-def _compute_old_regime_tax(income: float) -> float:
-    tax = 0.0
-    if income > 1000000:
-        tax += (income - 1000000) * 0.30
-        income = 1000000.0
-    if income > 500000:
-        tax += (income - 500000) * 0.20
-        income = 500000.0
-    if income > 250000:
-        tax += (income - 250000) * 0.05
-    return tax
-
-
-def _compute_new_regime_tax(income: float) -> float:
-    tax = 0.0
-    if income > 1500000:
-        tax += (income - 1500000) * 0.30
-        income = 1500000.0
-    if income > 1200000:
-        tax += (income - 1200000) * 0.20
-        income = 1200000.0
-    if income > 900000:
-        tax += (income - 900000) * 0.15
-        income = 900000.0
-    if income > 600000:
-        tax += (income - 600000) * 0.10
-        income = 600000.0
-    if income > 300000:
-        tax += (income - 300000) * 0.05
-    return tax

app/core/itr2_calculator.py

@@ -1,10 +1,13 @@
 """
-Deterministic ITR-2 tax calculator for FY 2025-26 (AY 2026-27).
-Source: https://www.incometaxindia.gov.in/
+Deterministic ITR-2 tax calculator.
+Slab rates, rebate, cess and the capital-gains / VDA special rates are loaded
+from the single source of truth (tax_rules.json via app.core.tax_rules),
+grounded in https://www.incometaxindia.gov.in/.
 
 Reads from the new schema structure (schemas.jsonc).
 """
 from app.core.field_calculator import _sum_list, _sum_nf_list, _nf
+from app.core import tax_rules
 
 
 def calculate_itr2_tax(itr_doc: dict) -> dict:
@@ -49,8 +52,8 @@ def calculate_itr2_tax(itr_doc: dict) -> dict:
                 for i in cg.get("long_term_gains", [])
                 if isinstance(i, dict)
             )
-        # LTCG exemption: 1L under Sec 112A for listed shares
-        ltg_taxable = max(ltg - 100000.0, 0.0)
+        # LTCG exemption under Sec 112A for listed shares (rate from single source)
+        ltg_taxable = max(ltg - tax_rules.capital_gains_rates()["ltcg_exemption"], 0.0)
     else:
         stg = ltg_taxable = 0.0
 
@@ -91,30 +94,21 @@ def calculate_itr2_tax(itr_doc: dict) -> dict:
     regular_income = gross_salary + hp_income + other_income
     taxable_income = max(regular_income - total_deductions, 0.0)
 
-    # ── Tax slabs on regular income only ─────────────────────────────────
+    # ── Tax on regular slab income (rates from the single source of truth) ─
     tax_regime = itr_doc.get("tax_regime", "NEW").upper()
-    if tax_regime == "OLD":
-        tax = _compute_old_regime_tax(taxable_income)
-        rebate_limit = 500000.0
-        rebate_max = 12500.0
-    else:
-        tax = _compute_new_regime_tax(taxable_income)
-        rebate_limit = 700000.0
-        rebate_max = 25000.0
-
-    # STCG at 15% (Sec 111A), LTCG at 10% (Sec 112A), VDA at 30% — special flat rates
-    stg_tax = stg * 0.15
-    ltg_tax = ltg_taxable * 0.10
-    vda_tax = vda_income * 0.30
-    tax = tax + stg_tax + ltg_tax + vda_tax
+    regular_tax = tax_rules.slab_tax(taxable_income, tax_regime)
+    # Section 87A rebate / marginal relief applies only to regular slab tax,
+    # never to the special-rate capital-gains / VDA income.
+    regular_tax = tax_rules.apply_rebate_and_relief(taxable_income, regular_tax, tax_regime)
 
-    # Section 87A rebate applies only to regular slab tax (not CG/VDA)
-    if taxable_income <= rebate_limit:
-        regular_tax = tax - stg_tax - ltg_tax - vda_tax
-        rebate = min(regular_tax, rebate_max)
-        tax = max(tax - rebate, 0.0)
+    # Special flat rates: STCG (Sec 111A), LTCG (Sec 112A), VDA (Sec 115BBH)
+    rates = tax_rules.capital_gains_rates()
+    stg_tax = stg * rates["stcg_rate"]
+    ltg_tax = ltg_taxable * rates["ltcg_rate"]
+    vda_tax = vda_income * rates["vda_rate"]
+    tax = regular_tax + stg_tax + ltg_tax + vda_tax
 
-    tax = round(tax * 1.04, 2)  # 4% cess
+    tax = round(tax * (1.0 + tax_rules.cess_rate(tax_regime)), 2)  # health & education cess
 
     # ── Taxes paid ────────────────────────────────────────────────────────
     tp = itr_doc.get("taxes_paid", {})
@@ -145,35 +139,3 @@ def calculate_itr2_tax(itr_doc: dict) -> dict:
         "refund_due": round(refund_due, 2),
         "tax_regime": tax_regime
     }
-
-
-def _compute_old_regime_tax(income: float) -> float:
-    tax = 0.0
-    if income > 1000000:
-        tax += (income - 1000000) * 0.30
-        income = 1000000.0
-    if income > 500000:
-        tax += (income - 500000) * 0.20
-        income = 500000.0
-    if income > 250000:
-        tax += (income - 250000) * 0.05
-    return tax
-
-
-def _compute_new_regime_tax(income: float) -> float:
-    tax = 0.0
-    if income > 1500000:
-        tax += (income - 1500000) * 0.30
-        income = 1500000.0
-    if income > 1200000:
-        tax += (income - 1200000) * 0.20
-        income = 1200000.0
-    if income > 900000:
-        tax += (income - 900000) * 0.15
-        income = 900000.0
-    if income > 600000:
-        tax += (income - 600000) * 0.10
-        income = 600000.0
-    if income > 300000:
-        tax += (income - 300000) * 0.05
-    return tax

app/core/tax_rules.json

@@ -1,11 +1,12 @@
 {
-  "_comment": "Indian Income Tax Rules FY 2025-26 (AY 2026-27). Source: https://www.incometaxindia.gov.in/",
+  "_comment": "Indian Income Tax slab rates and limits — single source of truth, grounded in https://www.incometaxindia.gov.in/. The applicable assessment year is not hardcoded in product copy.",
 
   "new_regime": {
-    "_note": "Default regime from FY 2023-24. No chapter VIA deductions except 80CCD(2) and 80CCH.",
+    "_note": "Default regime. No chapter VIA deductions except 80CCD(2) and 80CCH. Income up to the 87A rebate limit is fully rebated; marginal relief applies just above it.",
     "standard_deduction": 75000,
-    "rebate_87a_limit": 700000,
-    "rebate_87a_amount": 25000,
+    "rebate_87a_limit": 1200000,
+    "rebate_87a_amount": 60000,
+    "rebate_87a_marginal_relief": true,
     "surcharge_rates": [
       {"above": 5000000,  "rate": 0.10},
       {"above": 10000000, "rate": 0.15},
@@ -14,12 +15,13 @@
     ],
     "cess_rate": 0.04,
     "tax_slabs": [
-      {"from": 0,       "to": 300000,   "rate": 0.00, "label": "0–3L: 0%"},
-      {"from": 300000,  "to": 600000,   "rate": 0.05, "label": "3L–6L: 5%"},
-      {"from": 600000,  "to": 900000,   "rate": 0.10, "label": "6L–9L: 10%"},
-      {"from": 900000,  "to": 1200000,  "rate": 0.15, "label": "9L–12L: 15%"},
-      {"from": 1200000, "to": 1500000,  "rate": 0.20, "label": "12L–15L: 20%"},
-      {"from": 1500000, "to": null,     "rate": 0.30, "label": "15L+: 30%"}
+      {"from": 0,       "to": 400000,   "rate": 0.00, "label": "0–4L: 0%"},
+      {"from": 400000,  "to": 800000,   "rate": 0.05, "label": "4L–8L: 5%"},
+      {"from": 800000,  "to": 1200000,  "rate": 0.10, "label": "8L–12L: 10%"},
+      {"from": 1200000, "to": 1600000,  "rate": 0.15, "label": "12L–16L: 15%"},
+      {"from": 1600000, "to": 2000000,  "rate": 0.20, "label": "16L–20L: 20%"},
+      {"from": 2000000, "to": 2400000,  "rate": 0.25, "label": "20L–24L: 25%"},
+      {"from": 2400000, "to": null,     "rate": 0.30, "label": "24L+: 30%"}
     ]
   },
 
@@ -86,8 +88,9 @@
       "schedule_foreign_assets": "PENDING",
       "schedule_via_deductions": "PENDING"
     },
-    "stcg_rate": 0.15,
-    "ltcg_rate": 0.10,
-    "ltcg_exemption": 100000
+    "stcg_rate": 0.20,
+    "ltcg_rate": 0.125,
+    "ltcg_exemption": 125000,
+    "vda_rate": 0.30
   }
 }

app/core/tax_rules.py

@@ -0,0 +1,90 @@
+"""
+Single source of truth for Indian income-tax slab rates, rebates and special
+rates.
+
+Every number used by the deterministic calculators (slabs, standard deduction,
+87A rebate, cess, and the capital-gains / VDA special rates) is loaded from
+``tax_rules.json`` — grounded in https://www.incometaxindia.gov.in/. No other
+module hardcodes slab numbers, so the rates are updated in exactly one place and
+the agent's ``retrieve_tax_rules_tool`` and the calculators can never diverge.
+
+All functions here are pure and deterministic — no LLM, no network.
+"""
+import os
+import json
+import functools
+
+_PATH = os.path.join(os.path.dirname(__file__), "tax_rules.json")
+
+
+@functools.lru_cache(maxsize=1)
+def load_rules() -> dict:
+    with open(_PATH, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def regime_rules(regime: str) -> dict:
+    rules = load_rules()
+    key = (regime or "new").lower() + "_regime"
+    return rules.get(key, rules["new_regime"])
+
+
+def standard_deduction(regime: str) -> float:
+    return float(regime_rules(regime).get("standard_deduction", 0.0))
+
+
+def cess_rate(regime: str) -> float:
+    return float(regime_rules(regime).get("cess_rate", 0.04))
+
+
+def rebate_87a(regime: str):
+    """Return (income_limit, max_rebate) for the section 87A rebate."""
+    r = regime_rules(regime)
+    return (float(r.get("rebate_87a_limit", 0.0)),
+            float(r.get("rebate_87a_amount", 0.0)))
+
+
+def has_marginal_relief(regime: str) -> bool:
+    return bool(regime_rules(regime).get("rebate_87a_marginal_relief", False))
+
+
+def slab_tax(taxable: float, regime: str) -> float:
+    """Progressive slab tax computed from the JSON slab table for the regime."""
+    tax = 0.0
+    for slab in regime_rules(regime).get("tax_slabs", []):
+        lo = float(slab.get("from", 0) or 0)
+        hi = slab.get("to")
+        rate = float(slab.get("rate", 0) or 0)
+        if taxable > lo:
+            upper = taxable if hi is None else min(taxable, float(hi))
+            tax += (upper - lo) * rate
+    return tax
+
+
+def apply_rebate_and_relief(taxable: float, slab_tax_amount: float, regime: str) -> float:
+    """
+    Apply the section 87A rebate and (where applicable) marginal relief to the
+    *slab* tax for a regime.
+
+    - At or below the rebate income limit: the rebate (capped at the configured
+      max) reduces the tax, fully wiping it out when the limit equals the tax.
+    - Just above the limit (new-regime marginal relief): the tax can never
+      exceed the amount by which income crosses the limit.
+    """
+    limit, max_rebate = rebate_87a(regime)
+    if taxable <= limit:
+        return max(slab_tax_amount - min(slab_tax_amount, max_rebate), 0.0)
+    if has_marginal_relief(regime):
+        return min(slab_tax_amount, taxable - limit)
+    return slab_tax_amount
+
+
+def capital_gains_rates() -> dict:
+    """Special flat rates for ITR-2 (capital gains and virtual digital assets)."""
+    itr2 = load_rules().get("ITR2", {})
+    return {
+        "stcg_rate": float(itr2.get("stcg_rate", 0.20)),
+        "ltcg_rate": float(itr2.get("ltcg_rate", 0.125)),
+        "ltcg_exemption": float(itr2.get("ltcg_exemption", 125000.0)),
+        "vda_rate": float(itr2.get("vda_rate", 0.30)),
+    }

app/tests/integration/test_endpoints.py

@@ -154,11 +154,12 @@ def test_new_user_no_prereqs_halts(self):
         self.assertTrue(len(result["unmet_dependencies"]) > 0)
 
     def test_prereqs_done_no_doc_calculates_if_checklist_clear(self):
-        # All checklist VERIFIED, milestones done → tax should calculate
+        # All checklist VERIFIED, milestones done → tax should calculate.
+        # Income is above the 12L new-regime 87A rebate limit, so tax is payable.
         itr_doc = {
             "itr_type": "ITR1", "tax_regime": "NEW",
-            "salary_income": {"gross_salary": {"value": 1000000},
-                              "net_salary_income": {"value": 925000}},
+            "salary_income": {"gross_salary": {"value": 1500000},
+                              "net_salary_income": {"value": 1425000}},
             "house_property": {"net_house_property_income": {"value": 0}},
             "other_sources": {"net_other_sources_income": {"value": 0}},
             "deductions": {"total_chapter_via_deductions": {"value": 0}},