itr-tool 1.0.0__py3-none-any.whl

itr_tool/__init__.py

@@ -0,0 +1,2 @@
+"""itr-tool: Offline Indian Income Tax computation tool."""
+__version__ = "1.0.0"

itr_tool/cli.py

@@ -0,0 +1,314 @@
+"""CLI entry point for itr-tool."""
+import os
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from itr_tool import __version__
+from itr_tool.config import load_config
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="itr-tool")
+def cli():
+    """itr-tool — Offline Indian Income Tax computation tool.
+
+    Privacy-first, offline CLI for salaried individuals with ESOP/ESPP/RSU.
+    Produces STI reports, ITR-2 JSON, and PDF computation sheets.
+    """
+    pass
+
+
+@cli.command()
+@click.argument("folder", type=click.Path(exists=True, file_okay=False))
+@click.option("--regime", type=click.Choice(["old", "new", "both"]), default="both",
+              help="Tax regime to compute.")
+@click.option("--fy", default=None, help="Financial year (e.g. 2025-26). Auto-detected from config.yaml.")
+@click.option("--ais-password", default="", help="AIS decrypt password (PAN+DOB). Prompted if needed.")
+@click.option("--output", "-o", type=click.Path(), default=None,
+              help="Output directory. Default: <folder>/output/")
+@click.option("--no-wizard", is_flag=True, default=False,
+              help="Skip interactive config wizard (use existing config.yaml as-is).")
+def compute(folder, regime, fy, ais_password, output, no_wizard):
+    """Run full tax computation from an organized document folder.
+
+    FOLDER should contain subfolders: form16/, etrade/, broker/, mf/, bank/, it/
+    """
+    folder_path = Path(folder)
+    console.print(Panel.fit(
+        f"[bold blue]itr-tool v{__version__}[/] — Tax Computation",
+        subtitle=f"FY {fy or 'auto'} | Regime: {regime}",
+    ))
+
+    # Load config (initial — may be incomplete)
+    with console.status("[bold green]Loading configuration..."):
+        cfg = load_config(folder_path, fy=fy, regime=regime, ais_password=ais_password)
+        if output:
+            cfg.output_folder = Path(output)
+        cfg.output_folder.mkdir(parents=True, exist_ok=True)
+
+    # Phase 1: Parse all documents (before wizard — to auto-detect values)
+    console.rule("[bold]Phase 1: Scanning & Parsing Documents")
+    from itr_tool.parsers.dispatcher import discover_and_parse
+    parsed = discover_and_parse(cfg)
+
+    # Interactive config wizard
+    config_path = folder_path / "config.yaml"
+    if not no_wizard:
+        import yaml
+        from itr_tool.config_wizard import run_config_wizard, save_config, show_config_summary
+
+        # Load existing raw config
+        existing_raw: dict = {}
+        if config_path.exists():
+            with open(config_path, "r", encoding="utf-8") as f:
+                existing_raw = yaml.safe_load(f) or {}
+
+        # Run wizard — auto-fills from parsed data, prompts user for each field
+        updated_cfg = run_config_wizard(folder_path, existing_raw, parsed, fy=fy)
+
+        # Show summary and confirm
+        show_config_summary(updated_cfg)
+        console.print()
+        save_it = click.confirm("  Save this configuration?", default=True)
+        if save_it:
+            saved_path = save_config(folder_path, updated_cfg)
+            console.print(f"  [green]Saved:[/] {saved_path}")
+
+        # Reload config from saved file
+        cfg = load_config(folder_path, fy=fy, regime=regime, ais_password=ais_password)
+        if output:
+            cfg.output_folder = Path(output)
+        cfg.output_folder.mkdir(parents=True, exist_ok=True)
+
+        # Re-parse with updated config (e.g. AIS password may have changed)
+        console.print()
+        console.rule("[bold]Re-parsing with updated config")
+        parsed = discover_and_parse(cfg)
+    else:
+        console.print(f"  PAN: [bold]{cfg.personal.pan or '(not set)'}[/]")
+        console.print(f"  FY:  [bold]{cfg.personal.financial_year}[/] -> AY {cfg.personal.assessment_year}")
+
+    console.print(f"  Input:  {cfg.input_folder}")
+    console.print(f"  Output: {cfg.output_folder}")
+    console.print()
+
+    # Phase 2: Compute tax
+    console.rule("[bold]Phase 2: Tax Computation")
+    from itr_tool.engine.compute import compute_tax
+    result = compute_tax(parsed, cfg)
+
+    # Phase 2b: ITR form selection
+    from itr_tool.engine.itr_form_selector import select_itr_form
+    itr_form, form_reasons = select_itr_form(parsed, result, cfg)
+    console.print(f"  [bold magenta]ITR Form: {itr_form}[/]")
+    for reason in form_reasons:
+        console.print(f"    • {reason}")
+
+    # Phase 3: Generate outputs
+    console.rule("[bold]Phase 3: Generating Reports")
+    from itr_tool.output.sti_report import generate_sti
+    from itr_tool.output.pdf_report import generate_pdf
+
+    sti_path = generate_sti(result, parsed, cfg)
+
+    if itr_form == "ITR-1":
+        from itr_tool.output.itr1_json import generate_itr1_json
+        json_path = generate_itr1_json(result, parsed, cfg)
+    else:
+        from itr_tool.output.itr2_json import generate_itr2_json
+        json_path = generate_itr2_json(result, parsed, cfg)
+
+    pdf_path = generate_pdf(result, parsed, cfg)
+
+    # Phase 4: Vestwise — ESOP/ESPP detailed workbook (if BenefitHistory.xlsx found)
+    vestwise_path = None
+    benefit_files = list(cfg.input_folder.rglob("BenefitHistory.xlsx"))
+    if benefit_files:
+        console.rule("[bold]Phase 4: Vestwise ESOP/ESPP Workbook")
+        benefit_file = benefit_files[0]
+        vestwise_out = cfg.output_folder / f"ESOP_Summary_{cfg.personal.financial_year}.xlsx"
+        try:
+            from itr_tool.parsers.vestwise import run_vestwise
+            run_vestwise(str(benefit_file), str(vestwise_out))
+            vestwise_path = vestwise_out
+            console.print(f"  [green]Vestwise:[/] {vestwise_path}")
+        except Exception as e:
+            console.print(f"  [red]Vestwise failed: {e}[/]")
+
+    console.print()
+    output_lines = (
+        f"[bold green]Done![/]\n"
+        f"  STI Report:  {sti_path}\n"
+        f"  ITR-2 JSON:  {json_path}\n"
+        f"  PDF/HTML:    {pdf_path}"
+    )
+    if vestwise_path:
+        output_lines += f"\n  ESOP Workbook: {vestwise_path}"
+    console.print(Panel.fit(output_lines, title="Output Files"))
+
+
+@cli.command()
+@click.argument("folder", type=click.Path(exists=True, file_okay=False))
+@click.option("--fy", default=None, help="Financial year (e.g. 2025-26).")
+def init(folder, fy):
+    """Create or update config.yaml interactively.
+
+    Scans FOLDER for tax documents, auto-detects values (PAN, employer,
+    salary, TDS), then walks you through each field to confirm or edit.
+    """
+    folder_path = Path(folder)
+    console.print(Panel.fit(
+        f"[bold blue]itr-tool[/] — Configuration Setup",
+        subtitle=str(folder_path),
+    ))
+
+    # Quick parse to auto-detect
+    cfg = load_config(folder_path, fy=fy)
+    console.rule("[bold]Scanning documents...")
+    from itr_tool.parsers.dispatcher import discover_and_parse
+    parsed = discover_and_parse(cfg)
+
+    # Run wizard
+    import yaml
+    from itr_tool.config_wizard import run_config_wizard, save_config, show_config_summary
+    existing_raw: dict = {}
+    config_path = folder_path / "config.yaml"
+    if config_path.exists():
+        with open(config_path, "r", encoding="utf-8") as f:
+            existing_raw = yaml.safe_load(f) or {}
+
+    updated_cfg = run_config_wizard(folder_path, existing_raw, parsed, fy=fy)
+    show_config_summary(updated_cfg)
+    console.print()
+    if click.confirm("  Save this configuration?", default=True):
+        saved_path = save_config(folder_path, updated_cfg)
+        console.print(f"  [green]Saved:[/] {saved_path}")
+    else:
+        console.print("  [yellow]Not saved.[/]")
+
+
+@cli.command()
+@click.argument("file_type", type=click.Choice([
+    "form16", "ais", "etrade-gl", "etrade-benefit", "employer-perq",
+    "zerodha", "mf", "bank", "26as", "auto",
+]))
+@click.argument("file_path", type=click.Path(exists=True))
+@click.option("--password", default="", help="Password for encrypted files (AIS).")
+def parse(file_type, file_path, password):
+    """Parse a single tax document and display structured output.
+
+    Supported types: form16, ais, etrade-gl, etrade-benefit, employer-perq,
+    zerodha, mf, bank, 26as, auto (auto-detect).
+    """
+    console.print(f"[bold]Parsing[/] {file_path} as [cyan]{file_type}[/]")
+    from itr_tool.parsers.dispatcher import parse_single
+    result = parse_single(file_type, Path(file_path), password=password)
+    if result:
+        console.print_json(data=result)
+    else:
+        console.print("[red]Parse failed or no data extracted.[/]")
+
+
+@cli.command()
+@click.argument("folder", type=click.Path(exists=True, file_okay=False))
+@click.option("--ais-password", default="", help="AIS decrypt password.")
+def verify(folder, ais_password):
+    """Cross-verify Form 16 vs AIS vs 26AS for mismatches.
+
+    Flags discrepancies in salary, TDS, interest, and dividends
+    before they become 143(1)(a) intimation issues.
+    """
+    console.print(Panel.fit("[bold yellow]Cross-Verification[/]", subtitle=folder))
+    from itr_tool.engine.reconcile import reconcile
+    folder_path = Path(folder)
+    cfg = load_config(folder_path, ais_password=ais_password)
+    issues = reconcile(cfg)
+    if not issues:
+        console.print("[bold green]All sources match. No discrepancies found.[/]")
+    else:
+        table = Table(title="Discrepancies Found")
+        table.add_column("Item", style="cyan")
+        table.add_column("Source A", style="green")
+        table.add_column("Source B", style="yellow")
+        table.add_column("Diff", style="red")
+        for issue in issues:
+            table.add_row(issue["item"], issue["a"], issue["b"], issue["diff"])
+        console.print(table)
+
+
+@cli.command()
+@click.option("--port", default=8000, help="Port for web server.")
+@click.option("--host", default="127.0.0.1", help="Host to bind to.")
+def web(port, host):
+    """Launch the web UI (FastAPI + React frontend)."""
+    console.print(f"[bold blue]Starting itr-tool web UI[/] at http://{host}:{port}")
+    import uvicorn
+    from itr_tool.web.server import app
+    uvicorn.run(app, host=host, port=port)
+
+
+@cli.command()
+def formats():
+    """Show supported input file types and expected folder structure."""
+    table = Table(title="Supported File Types")
+    table.add_column("Type", style="cyan", width=18)
+    table.add_column("Subfolder", style="green", width=12)
+    table.add_column("Format", style="yellow", width=10)
+    table.add_column("Description")
+
+    rows = [
+        ("form16", "form16/", "PDF", "Form 16 from employer (Part A + Part B)"),
+        ("ais", "it/", "JSON/PDF", "Annual Information Statement (encrypted)"),
+        ("26as", "it/", "PDF/TXT", "Form 26AS — TDS credits"),
+        ("etrade-gl", "etrade/", "XLSX", "E-Trade G&L Expanded — ESOP/ESPP sales"),
+        ("etrade-benefit", "etrade/", "XLSX", "E-Trade BenefitHistory — grants, vests, Schedule FA"),
+        ("employer-perq", "employer/", "PDF", "Employer perquisite workings"),
+        ("broker-pl", "broker/", "XLSX", "Broker tax P&L — dividends, equity trades"),
+        ("mf", "mf/", "XLSX", "Mutual fund capital gains report"),
+        ("bank", "bank/", "PDF/CSV", "Bank statements (any Indian bank)"),
+    ]
+    for r in rows:
+        table.add_row(*r)
+    console.print(table)
+
+    console.print("\n[bold]Expected folder structure:[/]")
+    console.print("""
+  <folder>/
+  ├── config.yaml       # PAN, DOB, FY, bank details (optional)
+  ├── form16/           # Form 16 PDFs
+  ├── etrade/           # E-Trade exports
+  ├── employer/         # Employer perquisite docs
+  ├── broker/           # Zerodha/Groww tax P&L
+  ├── mf/               # Mutual fund reports
+  ├── bank/             # Bank statements
+  └── it/               # AIS, TIS, 26AS, Form 168
+    """)
+
+
+@cli.command()
+@click.argument("folders", nargs=-1, required=True, type=click.Path(exists=True, file_okay=False))
+@click.option("--output", default=None, type=click.Path(), help="Output file path for comparison report.")
+def compare(folders, output):
+    """Compare tax across multiple assessment years.
+
+    Pass 2 or more AY folders to see salary, CG, deductions, and tax trends.
+
+    Example: itr-tool compare IT/2024-25 IT/2025-26 IT/2026-27
+    """
+    from itr_tool.output.yoy_report import generate_yoy_report
+    folder_paths = [Path(f) for f in folders]
+    out_path = Path(output) if output else None
+    console.print(Panel.fit(
+        f"[bold blue]Year-over-Year Comparison[/] — {len(folder_paths)} years",
+    ))
+    generate_yoy_report(folder_paths, output_path=out_path)
+
+
+if __name__ == "__main__":
+    cli()

itr_tool/config.py

@@ -0,0 +1,271 @@
+"""Configuration loader — reads config.yaml + FY rule packs."""
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+from pydantic import BaseModel, Field
+
+from itr_tool.models.personal import PersonalDetails, BankAccount, AccountType
+from itr_tool.models.deductions import (
+    AllDeductions, Deduction80C, Deduction80D, Deduction80CCD, DeductionHRA,
+)
+from itr_tool.models.advance_tax import TaxPaymentEntry
+
+
+RULES_DIR = Path(__file__).parent / "rules"
+
+
+class PriorYearLosses(BaseModel):
+    """Losses brought forward from prior assessment year."""
+    hp_loss_bf: float = 0.0
+    stcg_loss_bf: float = 0.0
+    ltcg_loss_bf: float = 0.0
+    source_ay: str = ""
+
+
+class HousePropertyConfig(BaseModel):
+    """House property income configuration."""
+    property_type: str = "self_occupied"  # self_occupied, let_out
+    rent_received: float = 0.0
+    municipal_taxes: float = 0.0
+    loan_interest: float = 0.0
+
+
+class PropertyTxnConfig(BaseModel):
+    """Property sale transaction for capital gains."""
+    description: str = ""
+    purchase_date: str = ""
+    sale_date: str = ""
+    purchase_cost: float = 0.0
+    improvement_cost: float = 0.0
+    sale_consideration: float = 0.0
+    stamp_duty_value: float = 0.0
+    tds_buyer: float = 0.0
+    exemption_54: float = 0.0
+    exemption_54f: float = 0.0
+
+
+class HRAConfig(BaseModel):
+    """HRA exemption inputs."""
+    rent_paid_annual: float = 0.0
+    is_metro: bool = False
+
+
+class AppConfig(BaseModel):
+    """Runtime configuration assembled from config.yaml + rule pack."""
+    personal: PersonalDetails = Field(default_factory=PersonalDetails)
+    input_folder: Path = Path(".")
+    output_folder: Path = Path("./output")
+    regime: str = "both"  # "old", "new", "both"
+    ais_password: str = ""
+    rules: dict[str, Any] = Field(default_factory=dict)
+    prior_year_losses: PriorYearLosses = Field(default_factory=PriorYearLosses)
+    deductions: AllDeductions = Field(default_factory=AllDeductions)
+    hra: HRAConfig = Field(default_factory=HRAConfig)
+    house_properties: list[HousePropertyConfig] = Field(default_factory=list)
+    property_transactions: list[PropertyTxnConfig] = Field(default_factory=list)
+    advance_tax_entries: list[TaxPaymentEntry] = Field(default_factory=list)
+    self_assessment_tax_entries: list[TaxPaymentEntry] = Field(default_factory=list)
+
+
+def load_rules(fy: str = "2025-26") -> dict[str, Any]:
+    """Load FY-specific tax rules from JSON pack."""
+    fname = f"fy{fy.replace('-', '_')}.json"
+    path = RULES_DIR / fname
+    if not path.exists():
+        raise FileNotFoundError(f"Rule pack not found: {path}")
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def load_config(
+    folder: Path,
+    fy: Optional[str] = None,
+    regime: str = "both",
+    ais_password: str = "",
+) -> AppConfig:
+    """Load config.yaml from folder + merge with defaults and FY rules."""
+    config_path = folder / "config.yaml"
+    raw: dict[str, Any] = {}
+    if config_path.exists():
+        with open(config_path, "r", encoding="utf-8") as f:
+            raw = yaml.safe_load(f) or {}
+
+    # Resolve FY
+    financial_year = fy or raw.get("financial_year", "2025-26")
+    assessment_year = raw.get("assessment_year", "")
+    if not assessment_year:
+        # derive: FY 2025-26 → AY 2026-27
+        parts = financial_year.split("-")
+        ay_start = int(parts[0]) + 1
+        ay_end = int(parts[1]) + 1
+        assessment_year = f"{ay_start}-{ay_end:02d}"
+
+    # Personal details
+    dob = raw.get("dob")
+    personal = PersonalDetails(
+        pan=raw.get("pan", ""),
+        name=raw.get("name", ""),
+        father_name=raw.get("father_name", ""),
+        date_of_birth=dob if dob else None,
+        address=raw.get("address", ""),
+        city=raw.get("city", ""),
+        state=raw.get("state", ""),
+        pincode=raw.get("pincode", ""),
+        email=raw.get("email", ""),
+        phone=raw.get("phone", ""),
+        aadhaar=raw.get("aadhaar", ""),
+        financial_year=financial_year,
+        assessment_year=assessment_year,
+    )
+
+    # Bank accounts
+    for b in raw.get("banks", []):
+        personal.bank_accounts.append(BankAccount(
+            name=b.get("name", ""),
+            ifsc=b.get("ifsc", ""),
+            account_number=str(b.get("account", "")),
+            account_type=AccountType(b.get("type", "savings")),
+        ))
+
+    # Rules
+    rules = load_rules(financial_year)
+
+    # AIS password
+    pwd = ais_password or raw.get("ais_password", "")
+
+    # Prior year losses
+    pyl_raw = raw.get("prior_year_losses", {}) or {}
+    prior_losses = PriorYearLosses(
+        hp_loss_bf=pyl_raw.get("hp_loss_bf", 0) or 0,
+        stcg_loss_bf=pyl_raw.get("stcg_loss_bf", 0) or 0,
+        ltcg_loss_bf=pyl_raw.get("ltcg_loss_bf", 0) or 0,
+        source_ay=str(pyl_raw.get("source_ay", "")),
+    )
+
+    # Deductions from config
+    ded_raw = raw.get("deductions", {}) or {}
+    d80c_raw = ded_raw.get("80c", {}) or {}
+    d80d_raw = ded_raw.get("80d", {}) or {}
+    d80ccd_raw = ded_raw.get("80ccd", {}) or {}
+    deductions = AllDeductions(
+        d80c=Deduction80C(
+            epf=d80c_raw.get("epf", 0) or 0,
+            ppf=d80c_raw.get("ppf", 0) or 0,
+            elss=d80c_raw.get("elss", 0) or 0,
+            lic=d80c_raw.get("lic", 0) or 0,
+            tuition_fees=d80c_raw.get("tuition_fees", 0) or 0,
+            nsc=d80c_raw.get("nsc", 0) or 0,
+            principal_repayment=d80c_raw.get("housing_principal", 0) or 0,
+            fd_5year=d80c_raw.get("fd_5year", 0) or 0,
+            other=d80c_raw.get("other", 0) or 0,
+        ),
+        d80d=Deduction80D(
+            self_premium=d80d_raw.get("self_premium", 0) or 0,
+            parents_premium=d80d_raw.get("parents_premium", 0) or 0,
+            preventive_checkup=d80d_raw.get("preventive_checkup", 0) or 0,
+        ),
+        d80ccd=Deduction80CCD(
+            employee_nps_80ccd1=d80ccd_raw.get("employee_nps", 0) or 0,
+            additional_nps_80ccd1b=d80ccd_raw.get("additional_nps", 0) or 0,
+            employer_nps_80ccd2=d80ccd_raw.get("employer_nps", 0) or 0,
+        ),
+        d80e=ded_raw.get("80e", 0) or 0,
+        d80g=ded_raw.get("80g", 0) or 0,
+        d80gg=ded_raw.get("80gg", 0) or 0,
+    )
+    # Compute 80C eligible (capped at 1.5L)
+    d80c = deductions.d80c
+    d80c.gross_total = (d80c.epf + d80c.ppf + d80c.elss + d80c.lic +
+                        d80c.tuition_fees + d80c.nsc + d80c.principal_repayment +
+                        d80c.fd_5year + d80c.other)
+    limit_80c = rules.get("deduction_limits", {}).get("80C", 150000)
+    d80c.eligible = min(d80c.gross_total, limit_80c)
+    # Compute 80D eligible
+    d80d = deductions.d80d
+    limit_self = rules.get("deduction_limits", {}).get("80D_self_below60", 25000)
+    limit_parents = rules.get("deduction_limits", {}).get("80D_parents_below60", 25000)
+    d80d.self_eligible = min(d80d.self_premium + min(d80d.preventive_checkup, 5000), limit_self)
+    d80d.parents_eligible = min(d80d.parents_premium, limit_parents)
+    d80d.total_eligible = d80d.self_eligible + d80d.parents_eligible
+    # Compute 80CCD eligible
+    d80ccd = deductions.d80ccd
+    d80ccd.eligible_80ccd1b = min(d80ccd.additional_nps_80ccd1b, 50000)
+    d80ccd.eligible_80ccd2 = d80ccd.employer_nps_80ccd2  # no limit
+
+    # HRA config
+    hra_raw = raw.get("hra", {}) or {}
+    hra_cfg = HRAConfig(
+        rent_paid_annual=hra_raw.get("rent_paid_annual", 0) or 0,
+        is_metro=hra_raw.get("is_metro", False),
+    )
+
+    # House property
+    hp_list = []
+    for hp in (raw.get("house_property") or []):
+        if isinstance(hp, dict):
+            hp_list.append(HousePropertyConfig(
+                property_type=hp.get("type", "self_occupied"),
+                rent_received=hp.get("rent_received", 0) or 0,
+                municipal_taxes=hp.get("municipal_taxes", 0) or 0,
+                loan_interest=hp.get("loan_interest", 0) or 0,
+            ))
+
+    # Property transactions
+    prop_txns = []
+    for pt in (raw.get("property_transactions") or []):
+        if isinstance(pt, dict):
+            prop_txns.append(PropertyTxnConfig(
+                description=pt.get("description", ""),
+                purchase_date=str(pt.get("purchase_date", "")),
+                sale_date=str(pt.get("sale_date", "")),
+                purchase_cost=pt.get("purchase_cost", 0) or 0,
+                improvement_cost=pt.get("improvement_cost", 0) or 0,
+                sale_consideration=pt.get("sale_consideration", 0) or 0,
+                stamp_duty_value=pt.get("stamp_duty_value", 0) or 0,
+                tds_buyer=pt.get("tds_buyer", 0) or 0,
+                exemption_54=pt.get("exemption_54", 0) or 0,
+                exemption_54f=pt.get("exemption_54f", 0) or 0,
+            ))
+
+    # Advance tax entries
+    adv_tax_entries = []
+    for at in (raw.get("advance_tax") or []):
+        if isinstance(at, dict):
+            adv_tax_entries.append(TaxPaymentEntry(
+                date=str(at.get("date", "")),
+                amount=at.get("amount", 0) or 0,
+                bsr_code=str(at.get("bsr_code", "")),
+                challan_no=str(at.get("challan_no", "")),
+            ))
+
+    # Self-assessment tax entries
+    sat_entries = []
+    for st in (raw.get("self_assessment_tax") or []):
+        if isinstance(st, dict):
+            sat_entries.append(TaxPaymentEntry(
+                date=str(st.get("date", "")),
+                amount=st.get("amount", 0) or 0,
+                bsr_code=str(st.get("bsr_code", "")),
+                challan_no=str(st.get("challan_no", "")),
+            ))
+
+    # Output folder
+    output = folder / "output"
+
+    return AppConfig(
+        personal=personal,
+        input_folder=folder,
+        output_folder=output,
+        regime=regime,
+        ais_password=pwd,
+        rules=rules,
+        prior_year_losses=prior_losses,
+        deductions=deductions,
+        hra=hra_cfg,
+        house_properties=hp_list,
+        property_transactions=prop_txns,
+        advance_tax_entries=adv_tax_entries,
+        self_assessment_tax_entries=sat_entries,
+    )

itr_tool/config_migrate.py

@@ -0,0 +1,57 @@
+"""Config version migration — detects old config.yaml and suggests new fields."""
+from pathlib import Path
+from rich.console import Console
+
+console = Console()
+
+CURRENT_VERSION = 2
+
+NEW_FIELDS_V2 = {
+    "advance_tax": "# advance_tax:\n#   - date: '2025-09-15'\n#     amount: 50000\n#     bsr_code: '0123456'\n#     challan_no: '12345'",
+    "self_assessment_tax": "# self_assessment_tax:\n#   - date: '2026-07-15'\n#     amount: 20000",
+    "config_version": "config_version: 2",
+}
+
+
+def check_and_migrate(config_path: Path) -> list[str]:
+    """Check config version and return list of migration suggestions.
+
+    Does NOT modify the file — just reports what's missing.
+    """
+    if not config_path.exists():
+        return []
+
+    text = config_path.read_text(encoding="utf-8")
+    suggestions = []
+
+    # Check for version field
+    if "config_version" not in text:
+        suggestions.append(
+            "Add 'config_version: 2' to track schema version"
+        )
+
+    # Check for v2 fields
+    if "advance_tax" not in text:
+        suggestions.append(
+            "New field available: 'advance_tax' — list of advance tax payments (date, amount, BSR code)"
+        )
+    if "self_assessment_tax" not in text:
+        suggestions.append(
+            "New field available: 'self_assessment_tax' — list of SAT payments"
+        )
+    if "prior_year_losses" not in text:
+        suggestions.append(
+            "New field available: 'prior_year_losses' — B/F STCG/LTCG/HP losses from prior AY"
+        )
+
+    return suggestions
+
+
+def print_migration_info(config_path: Path):
+    """Print migration suggestions to console."""
+    suggestions = check_and_migrate(config_path)
+    if suggestions:
+        console.print(f"\n  [yellow]Config upgrade suggestions ({config_path.name}):[/]")
+        for s in suggestions:
+            console.print(f"    • {s}")
+        console.print(f"  [dim]Run 'itr-tool init {config_path.parent}' to update interactively.[/]\n")