itr-tool 1.0.0__tar.gz

itr_tool-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kailash Chandrasekaran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

itr_tool-1.0.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+# Package data files
+recursive-include itr_tool/rules *.json
+recursive-include itr_tool/output/templates *.html
+recursive-include itr_tool/parsers/vestwise_data *.csv *.ini
+
+# Exclude sensitive/test data
+exclude *.pdf *.xlsx *.xls
+prune tests/golden
+prune itr_tool/web/frontend/node_modules
+prune itr_tool/web/frontend/dist

itr_tool-1.0.0/PKG-INFO

@@ -0,0 +1,548 @@
+Metadata-Version: 2.4
+Name: itr-tool
+Version: 1.0.0
+Summary: Offline Indian Income Tax computation tool for salaried individuals with ESOP/ESPP/RSU
+Author: Kailash Chandrasekaran
+License-Expression: MIT
+Keywords: income-tax,india,itr,tax,esop,espp,form16,ais
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pdfplumber>=0.10
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.31
+Requires-Dist: jinja2>=3.1
+Requires-Dist: form16x>=2.0
+Requires-Dist: itd-aisparser>=0.1
+Requires-Dist: yfinance>=0.2
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == "web"
+Requires-Dist: uvicorn>=0.27; extra == "web"
+Requires-Dist: python-multipart>=0.0.9; extra == "web"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# itr-tool
+
+**Offline Indian Income Tax computation tool for salaried individuals with ESOP/ESPP/RSU.**
+
+Privacy-first, fully offline CLI. Parses Form 16, AIS, 26AS, E-Trade exports, broker P&L, and mutual fund reports. Computes tax under both old and new regimes, generates ITR-1/ITR-2 JSON, Statement of Total Income (STI), and PDF computation sheets.
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Quick Start](#quick-start)
+3. [Folder Structure](#folder-structure)
+4. [Supported File Types](#supported-file-types)
+5. [config.yaml Reference](#configyaml-reference)
+6. [Commands](#commands)
+7. [Interactive Config Wizard](#interactive-config-wizard)
+8. [Encrypted Files & Passwords](#encrypted-files--passwords)
+9. [Vestwise ESOP/ESPP Workbook](#vestwise-esopespp-workbook)
+10. [Outputs](#outputs)
+11. [Multi-Year Usage](#multi-year-usage)
+12. [FAQ](#faq)
+
+---
+
+## Installation
+
+```bash
+# Clone and install
+git clone <repo-url>
+cd itr-tool
+pip install -e .
+
+# Verify
+itr-tool --version
+itr-tool --help
+```
+
+**Requirements:** Python 3.11+
+
+**Key dependencies** (installed automatically):
+- `form16x` — Form 16 PDF parser
+- `itd-aisparser` — AIS JSON decryptor
+- `pdfplumber` — PDF text extraction (fallback for encrypted/unusual PDFs)
+- `yfinance` — Stock price lookup for ESOP sale price resolution
+- `openpyxl` — Excel workbook generation
+- `rich` — Beautiful CLI output
+
+---
+
+## Quick Start
+
+```bash
+# 1. Organize your documents (see Folder Structure below)
+# 2. Run the tool — it will guide you through config interactively
+itr-tool compute "C:\Users\Me\IT\2026-27"
+
+# Or skip the interactive wizard if config.yaml already exists
+itr-tool compute "C:\Users\Me\IT\2026-27" --no-wizard
+
+# Just create/update config.yaml without computing
+itr-tool init "C:\Users\Me\IT\2026-27"
+```
+
+---
+
+## Folder Structure
+
+Create **one folder per assessment year** (AY = FY + 1). The folder name should be the AY (e.g. `2026-27` for FY 2025-26).
+
+```
+IT/
+└── 2026-27/                          # Assessment Year folder
+    ├── config.yaml                   # Personal details, deductions, bank accounts
+    │
+    ├── Form 16/                      # Employer Form 16 PDFs
+    │   ├── Employer1_Form16.pdf      #   (any naming works)
+    │   └── Employer2_Form16B.pdf     #   supports Part A + Part B splits
+    │
+    ├── Employer/                     # Employer perquisite workings
+    │   └── perquisite.pdf            #   ESOP perquisite rate extraction
+    │
+    ├── E-Trade/                      # E-Trade exports for ESOP/ESPP
+    │   ├── BenefitHistory.xlsx       #   ★ REQUIRED for Vestwise workbook
+    │   ├── G&L_Expanded_*.xlsx       #   Gains & Losses — STCG/LTCG
+    │   └── (can have multiple year files)
+    │
+    ├── Stocks/                       # Brokerage & MF reports
+    │   ├── taxpnl-*.xlsx             #   Broker tax P&L (Zerodha/Groww)
+    │   └── *Capital_Gains*.xlsx      #   Mutual fund CG report
+    │
+    ├── IT/                           # Income Tax department documents
+    │   ├── *_AIS*.json               #   AIS JSON (encrypted)
+    │   ├── *_AIS*.pdf                #   AIS PDF
+    │   ├── *_TIS*.pdf                #   TIS PDF
+    │   ├── *-26AS*.pdf               #   Form 26AS
+    │   └── Form16*.pdf               #   Form 16 from IT portal
+    │
+    ├── Bank/                         # Bank statements (optional)
+    │   └── *.pdf / *.csv
+    │
+    └── output/                       # ← Generated automatically
+        ├── STI_2025-26_Name.txt      #   Statement of Total Income
+        ├── ITR2_AY202627.json        #   ITR-2 JSON (or ITR1_*)
+        ├── TaxComputation_2025-26.pdf#   PDF computation sheet
+        └── ESOP_Summary_2025-26.xlsx #   Vestwise ESOP workbook
+```
+
+### Accepted subfolder names
+
+The tool scans for these folder name variants (case-sensitive on Linux, case-insensitive on Windows):
+
+| Category | Accepted folder names |
+|---|---|
+| **Form 16** | `Form 16`, `form16`, `Form16`, `form 16`, `To Send` |
+| **E-Trade** | `E-Trade`, `etrade`, `e-trade`, `ESOP ESPP`, `ESOP` |
+| **Employer perq** | `Employer`, `employer` |
+| **Brokerage** | `Stocks`, `stocks`, `broker`, `MF Stocks`, `mf`, `MF` |
+| **IT dept** | `IT`, `it` |
+| **Bank** | `Bank`, `bank`, `Bank Statements` |
+
+Files in the **root** of the AY folder are also scanned (e.g. `Form16B.pdf` at root level).
+
+---
+
+## Supported File Types
+
+| Type | Format | Auto-detected by | What it extracts |
+|---|---|---|---|
+| **Form 16** | PDF | Folder name or `form16` in filename | Salary, TDS, perquisites, employer details |
+| **AIS JSON** | JSON | `ais` in filename, `.json` extension | Interest, dividends, TDS credits |
+| **AIS PDF** | PDF | `ais` in filename, `.pdf` extension | (metadata only — used for verification) |
+| **26AS** | PDF | `26as` or `form26` in filename | (metadata only) |
+| **E-Trade G&L** | XLSX | `G&L_Expanded` in filename | ESOP sale transactions, STCG/LTCG |
+| **E-Trade Benefit** | XLSX | `BenefitHistory` in filename | Grant vesting history, Schedule FA |
+| **Employer Perq** | PDF | Perquisite workings filename pattern | Perquisite exchange rates for ESOP valuation |
+| **Broker P&L** | XLSX | `taxpnl` in filename | Dividends, equity trades |
+| **MF CG Report** | XLSX | `capital_gains` in filename | Mutual fund capital gains |
+| **Bank Statement** | PDF/CSV | In `bank/` folder | Interest income extraction |
+
+---
+
+## config.yaml Reference
+
+The `config.yaml` file contains data that **cannot be auto-extracted** from documents — personal details, deductions, property info, and bank accounts. The interactive wizard helps you create this file.
+
+```yaml
+# ─── Personal Details ───
+pan: ABCDE1234F
+name: Your Full Name
+father_name: Father Name
+dob: 1990-01-15                    # YYYY-MM-DD format
+address: "123, Example Street"
+city: Mumbai
+state: Maharashtra
+pincode: "400001"
+email: taxpayer@example.com
+phone: "9800000000"
+aadhaar: "XXXX XXXX XXXX"          # optional
+
+# ─── Financial Year ───
+financial_year: "2025-26"
+assessment_year: "2026-27"         # auto-derived if omitted
+regime: both                       # old | new | both
+
+# ─── AIS Password ───
+ais_password: ABCDE1234F15011990   # PAN + DOB(DDMMYYYY)
+
+# ─── Deductions (Chapter VI-A) — Old Regime Only ───
+deductions:
+  80c:
+    epf: 150000                    # Employee PF contribution
+    ppf: 0                         # Public Provident Fund
+    elss: 50000                    # ELSS mutual funds
+    lic: 0                         # LIC premium
+    tuition_fees: 0                # Children tuition fees
+    housing_principal: 0           # Housing loan principal
+    fd_5year: 0                    # 5-year tax saver FD
+    other: 0
+  80d:
+    self_premium: 25000            # Medical insurance — self/family
+    parents_premium: 25000         # Medical insurance — parents
+    preventive_checkup: 5000       # Health checkup (max 5K)
+  80ccd:
+    employee_nps: 0                # NPS employee contribution (80CCD1)
+    additional_nps: 50000          # Additional NPS (80CCD1B, max 50K)
+    employer_nps: 0                # Employer NPS (80CCD2, new regime eligible)
+  80e: 0                           # Education loan interest (no limit)
+  80g: 0                           # Donations
+  80gg: 0                          # Rent paid (if no HRA from employer)
+
+# ─── HRA Exemption ───
+hra:
+  rent_paid_annual: 360000         # Total rent paid in the FY
+  is_metro: true                   # Delhi/Mumbai/Kolkata/Chennai
+
+# ─── House Property ───
+house_property:
+  - type: self_occupied            # self_occupied | let_out
+    loan_interest: 200000          # Annual housing loan interest
+  # - type: let_out
+  #   rent_received: 240000
+  #   municipal_taxes: 12000
+  #   loan_interest: 180000
+
+# ─── Property Capital Gains ───
+property_transactions: []
+  # - description: "Apartment in Chennai"
+  #   purchase_date: "2010-06-15"
+  #   sale_date: "2025-09-10"
+  #   purchase_cost: 3600000
+  #   improvement_cost: 200000
+  #   sale_consideration: 8500000
+  #   stamp_duty_value: 8200000    # for S.50C check
+  #   tds_buyer: 85000             # TDS u/s 194IA
+  #   exemption_54: 5000000        # Reinvestment in new house
+  #   exemption_54f: 0
+
+# ─── Prior Year Losses (Brought Forward) ───
+prior_year_losses:
+  hp_loss_bf: 50000                # House property loss B/F
+  stcg_loss_bf: 10000              # Short-term CG loss B/F
+  ltcg_loss_bf: 25000              # Long-term CG loss B/F
+  source_ay: "2025-26"
+
+# ─── Bank Accounts (for refund) ───
+banks:
+  - name: Example Bank
+    ifsc: EXAM0001234
+    account: "123456789012"
+    type: savings                  # savings | current
+  - name: Another Bank
+    ifsc: ANOT0005678
+    account: "987654321098"
+    type: savings
+```
+
+### What's auto-extracted (no config needed)
+
+| Data | Source | Auto-detected |
+|---|---|---|
+| Salary (gross, 17(1), 17(2), 17(3)) | Form 16 | Yes |
+| TDS on salary | Form 16 | Yes |
+| Employer name & TAN | Form 16 | Yes |
+| ESOP perquisite details | Form 12BA / Employer perquisite PDF | Yes |
+| ESOP/ESPP STCG & LTCG | E-Trade G&L Expanded | Yes |
+| Bank interest | AIS JSON | Yes |
+| Dividends | AIS JSON / Broker P&L | Yes |
+| TDS on interest/dividends | AIS JSON | Yes |
+| MF capital gains | MF CG report | Yes |
+| SBI TTBR exchange rates | Downloaded from GitHub | Yes |
+
+### What you must enter in config.yaml
+
+| Data | Why |
+|---|---|
+| PAN, name, DOB, address | Not reliably in all Form 16 formats |
+| Deductions (80C/D/CCD/E/G) | Not in any document — only you know |
+| HRA details | Rent receipts aren't parsed |
+| House property info | Loan interest certificate not parsed |
+| Property sale transactions | Sale deed details not in standard docs |
+| Prior year losses | From previous year's ITR acknowledgment |
+| Bank accounts | For refund credit — IFSC, account number |
+
+---
+
+## Commands
+
+### `itr-tool compute <FOLDER>`
+
+Main command — full pipeline: parse → wizard → compute → generate reports.
+
+```bash
+itr-tool compute "C:\Users\Me\IT\2026-27"
+
+# Options:
+  --regime old|new|both    # Default: both (compare and recommend)
+  --fy 2025-26             # Auto-detected from config.yaml
+  --ais-password PAN+DOB   # Or set in config.yaml
+  --output /path/to/out    # Default: <FOLDER>/output/
+  --no-wizard              # Skip interactive config wizard
+```
+
+### `itr-tool init <FOLDER>`
+
+Just run the config wizard — scan documents, auto-fill, prompt, save `config.yaml`. No tax computation.
+
+```bash
+itr-tool init "C:\Users\Me\IT\2026-27"
+```
+
+### `itr-tool parse <TYPE> <FILE>`
+
+Parse a single document and display structured JSON output.
+
+```bash
+itr-tool parse form16 "Form 16.pdf"
+itr-tool parse ais "AIS.json" --password ABCDE1234F15011990
+itr-tool parse auto "some_file.xlsx"   # auto-detect type
+```
+
+### `itr-tool verify <FOLDER>`
+
+Cross-verify Form 16 vs AIS vs 26AS for discrepancies before filing.
+
+```bash
+itr-tool verify "C:\Users\Me\IT\2026-27"
+```
+
+### `itr-tool formats`
+
+Display supported file types and expected folder structure.
+
+---
+
+## Interactive Config Wizard
+
+When you run `itr-tool compute` (without `--no-wizard`), or `itr-tool init`, the tool:
+
+1. **Scans** all subfolders and detects parseable files
+2. **Parses** Form 16, AIS, E-Trade, etc. to auto-detect PAN, salary, TDS
+3. **Shows auto-detected salary** (read-only, from Form 16)
+4. **Walks through each config section** interactively:
+
+```
+┌─ Configuration Wizard ────────────────────────────────┐
+│ Press Enter to accept the shown value,                │
+│ or type a new value.                                  │
+│ Values in [brackets] are auto-detected or existing.   │
+└───────────────────────────────────────────────────────┘
+
+── 1. Personal Details ──
+  Financial Year [2025-26]:
+  PAN [ABCDE1234F]:
+  Full Name [Your Name]:
+  ...
+
+── 2. Salary (auto-detected from Form 16) ──
+  Employer 1: ACME TECH PVT LTD  TAN: DELA12345B  Gross: 22,50,000  TDS: 5,20,000
+  (not editable in config — extracted from documents)
+
+── 3. Deductions (Chapter VI-A) ──
+  Section 80C (limit Rs.1,50,000):
+    EPF contribution [1,50,000]:
+    ELSS mutual funds [50,000]:
+    ...
+
+── 4. HRA Exemption ──
+── 5. House Property Income ──
+── 6. Property Capital Gains ──
+── 7. Prior Year Losses ──
+── 8. Bank Accounts ──
+
+┌─ Configuration Summary ──────────────┐
+│ Personal  │ PAN: ABCDE1234F  FY: ... │
+│ Deductions│ 80C: 1,50,000  80D: ...  │
+│ ...       │                          │
+└───────────────────────────────────────┘
+Save this configuration? [Y/n]:
+```
+
+After saving, the tool reloads the config and proceeds with tax computation.
+
+---
+
+## Encrypted Files & Passwords
+
+### Password-protected files the tool handles:
+
+| File | Common password | How the tool handles it |
+|---|---|---|
+| **AIS JSON** | PAN + DOB (`ABCDE1234F15011990`) | Set `ais_password` in config.yaml, or prompted |
+| **Form 16 PDF** | Varies by employer (DOB, employee ID) | Prompted interactively with 3 retries |
+| **26AS PDF** | Usually PAN lowercase + DOB | Not parsed yet (metadata only) |
+
+### Password prompt behavior:
+
+```
+🔒 Form 16 PDF file is encrypted: Employer_Form16B.pdf
+Type password and press Enter. Type 'skip' to skip this file.
+Password (attempt 1/3): ********
+✗ Wrong password. 2 attempt(s) remaining.
+Password (attempt 2/3): ********
+✓ Password accepted
+```
+
+- **3 attempts** per file — wrong/empty counts as a failed attempt
+- **Type `skip`** to skip a file immediately
+- **Password is hidden** while typing (like sudo)
+- **Password cache** — once a password works for one Form 16, it's auto-tried for the next Form 16
+- **AIS password** — set it in `config.yaml` to avoid prompts every run
+
+---
+
+## Vestwise ESOP/ESPP Workbook
+
+If an `E-Trade/BenefitHistory.xlsx` file is found in any subfolder, the tool automatically runs **Vestwise** to generate a detailed ESOP/ESPP tax workbook.
+
+### Required input
+
+| File | Where to get it | Location |
+|---|---|---|
+| **BenefitHistory.xlsx** | E-Trade → My Account → Benefits → Export to Excel | `E-Trade/BenefitHistory.xlsx` |
+
+### What Vestwise generates
+
+The output is a multi-sheet Excel workbook (`ESOP_Summary_YYYY-YY.xlsx`) with:
+
+| Sheet | Contents |
+|---|---|
+| **Grant Summary** | All grants, vested/unvested/sold quantities, current status |
+| **Sales History** | Every sale transaction with acquisition cost, sale proceeds, STCG/LTCG |
+| **Year-wise Tax Summary** | Capital gains aggregated by FY with subtotals |
+| **Schedule FA (Table A3)** | Foreign asset disclosure — shares held on Dec 31 each year |
+| **Validation** | Cross-checks against E-Trade data, flags discrepancies |
+
+### Key features
+
+- **SBI TTBR rates** — Rule 115 compliant USD→INR conversion (auto-downloaded from GitHub)
+- **Sale price resolution** — priority: override file → E-Trade xlsx → yfinance closing price
+- **STCG vs LTCG classification** — 24-month holding period for unlisted/foreign shares
+- **Tax rate calculation** — LTCG 12.5%, STCG at slab rate (30%)
+- **Sale price overrides** — persisted in `vestwise_data/sale_price_overrides.csv` for accuracy
+
+### Note
+
+Vestwise runs automatically as Phase 4 when `BenefitHistory.xlsx` is detected. No additional config needed.
+
+---
+
+## Outputs
+
+All outputs go to `<FOLDER>/output/`:
+
+| File | Description |
+|---|---|
+| `STI_YYYY-YY_Name.txt` | Statement of Total Income — full text report with 7 annexures |
+| `ITR2_AY*.json` or `ITR1_AY*.json` | ITR JSON ready for upload to IT portal (auto-selects form) |
+| `TaxComputation_YYYY-YY.pdf` | PDF computation sheet |
+| `ESOP_Summary_YYYY-YY.xlsx` | Vestwise ESOP workbook (if BenefitHistory.xlsx found) |
+
+### ITR Form Auto-Selection
+
+The tool automatically determines whether to generate **ITR-1 (Sahaj)** or **ITR-2**:
+
+| Condition | Form |
+|---|---|
+| Salary + interest only, ≤ 50L, no CG, no foreign assets, ≤ 1 HP | **ITR-1** |
+| Has ESOP/equity capital gains | **ITR-2** |
+| Has property capital gains | **ITR-2** |
+| Has foreign assets (ESOP shares) | **ITR-2** |
+| Multiple house properties | **ITR-2** |
+| Total income > 50L | **ITR-2** |
+
+---
+
+## Multi-Year Usage
+
+The tool supports running against multiple financial years. Create separate AY folders:
+
+```
+IT/
+├── 2021-22/    # FY 2020-21
+├── 2022-23/    # FY 2021-22
+├── 2023-24/    # FY 2022-23
+├── 2024-25/    # FY 2023-24
+├── 2025-26/    # FY 2024-25
+└── 2026-27/    # FY 2025-26
+```
+
+Each folder needs its own `config.yaml` (the wizard creates it). Rule packs for FY 2020-21 through 2025-26 are included, covering slab rates, deduction limits, CII tables, and CG rates for each year.
+
+```bash
+# Run for a specific year
+itr-tool compute "IT/2026-27" --no-wizard
+
+# Run all years (batch)
+for dir in IT/202*; do itr-tool compute "$dir" --no-wizard; done
+```
+
+---
+
+## FAQ
+
+**Q: Do I need to sort files into exact subfolder names?**
+No. The tool scans 20+ folder name variants. `Form 16/`, `form16/`, `To Send/Form 16/` all work. Files in the root folder are also detected.
+
+**Q: What if I have multiple employers?**
+Put all Form 16 PDFs in the same folder. The tool deduplicates by employer TAN and aggregates salary from all employers.
+
+**Q: What if form16x can't parse my Form 16?**
+The tool has a pdfplumber fallback parser with regex-based extraction. If both fail (e.g. scanned/image PDF), you'll see a warning. Consider entering salary manually in a future release.
+
+**Q: Is my data sent anywhere?**
+No. Everything runs offline on your machine. The only network call is downloading SBI TTBR exchange rates from a public GitHub CSV (and optional yfinance stock price lookup). No data is uploaded.
+
+**Q: How do I update deductions after filing?**
+Edit `config.yaml` directly or run `itr-tool init <folder>` to re-run the wizard.
+
+**Q: What Python version do I need?**
+Python 3.11 or newer.
+
+---
+
+## License
+
+MIT