FinSim Pro

FinSim Pro is a high-fidelity financial simulation engine designed to provide autonomous and semi-autonomous financial planning insights. It utilizes Monte Carlo simulations to project net worth across thousands of possible market scenarios, integrated with an agentic AI layer that reasons over an approximate model of Indian tax rules and investment strategies to act as a digital financial-planning assistant.

What does it do?

At its core, the application bridges rigorous mathematical forecasting with natural language strategy. It doesn't just show you "best-case" scenarios; it features Agentic capabilities, meaning it can think through your specific financial constraints, remember your long-term goals, and generate a self-contained strategy report.

The frontend is a two-phase flow: a single-page setup dashboard where you configure your profile, portfolio, goals, EMI and simulation settings, followed by a full-screen results view with a quick-edit drawer for re-running against tweaked inputs.

Here are its primary capabilities:

1. Correlated, Fat-Tailed Monte Carlo Engine

FinSim Pro runs up to 10,000 parallel simulations of your financial life. Behind the scenes, the engine:

1. Gathers Market Data: Fetches real-time tickers (Nifty 50, Gold, S&P 500) and uses Prophet (Meta's forecasting tool) to calculate historical CAGR and volatility, falling back to sane defaults if the fetch fails.
2. Simulates Realistic Risk: Draws jointly-correlated returns across asset classes (via a Cholesky-factored correlation matrix, so equities crash together and gold behaves as a partial hedge) with fat-tailed Student-t marginals, so crash risk isn't understated the way a plain Gaussian model would.
3. Calculates Probabilities: Returns precise success rates for your FIRE (Financial Independence, Retire Early) number, 1-Crore milestones, and — per goal — the probability it's fully funded across all simulated paths.
4. Manages Reserves Realistically: The emergency fund actually grows and is drawn down when cash flow goes negative, rather than being force-refilled every year.

2. Approximate FY 2024-25/25-26 Indian Tax Engine

The system includes a hard-coded tax engine that dynamically switches between regimes. It models the main slabs, rates and exemptions but is a planning approximation, not a filing-grade calculator — indexation, surcharge edge cases and several deductions are simplified.

• Dual-Regime Logic: Automatically compares the Old vs. New Tax Regime (Budget 2025) to find your lower estimated liability.
• Asset-Specific Tax: Estimates LTCG and STCG for Equity (12.5%), Gold, Real Estate, and Debt, including the ₹1.25L exemption limit; property/gold indexation is approximated with a flat CII uplift.
• Deductions: Assumes 80C is fully used and takes 80D, HRA and home-loan interest as user-supplied inputs rather than deriving them.
• Tax-Loss Harvesting: Flags each holding as SELL_FOR_LOSS, WAIT_FOR_LTCG, LOW_TAX_GAIN, or HOLD based on unrealised gains and days-to-LTCG.

3. Macro Stress Testing

Injects real-world shocks (2008 crash, COVID-19, job loss, stagflation, an aggressive rate-hike cycle, or a custom scenario) directly into the Monte Carlo paths and compares against an unshocked baseline using Common Random Numbers, so every non-shock year is identical between the two runs and the reported impact reflects the shock alone. Headline metrics are trough-based (the worst dip vs. baseline), since a fully-recovered terminal value would otherwise make every scenario look the same. Run a single scenario or compare all five at once.

4. Portfolio Optimizer & Retirement Planner

• Markowitz Efficient Frontier: Monte Carlo optimization over 5,000 random portfolios to find Max Sharpe, Min Volatility, and Max Return allocations, plotted against your current portfolio.
• FIRE Date Estimator: Projects your retirement age across multiple Safe Withdrawal Rates (3%–5%) with year-by-year net worth vs. FIRE-number tracking.

5. Agentic Financial Reporting (LangGraph)

Using a LangGraph workflow and Google's Gemini AI, the system performs "Thinking" steps before giving advice:

• Narrative Node: Analyzes simulation results to write a professional executive summary.
• Strategy Node: Identifies shortfalls in your goals and suggests specific "BUY/SELL" actions.
• PDF Generation: Compiles all charts (Net Worth Fan charts, Tax stacks) into a self-contained HTML/PDF report for the user.

6. Smart Rebalancing & Probabilistic Goal Tracking

• Age-Based Allocation: Suggests a target portfolio based on your current age and risk tolerance.
• Drift Analysis: Calculates the percentage "drift" in your portfolio and provides exact Rupee amounts needed to rebalance.
• Goal Priority: Tracks multiple goals (House, Education, Retirement) and reports each one's probability of being fully funded across all Monte Carlo paths — not just the median path.

---

Modeling Assumptions & Limitations

FinSim Pro is a planning tool, not financial advice. Key simplifications to be aware of:

• Returns: Asset-class CAGR/vol come from a Prophet fit on historical prices (with fixed fallbacks); the forecast endpoint ratio is used as CAGR and is noisy. Cross-asset correlations are single hand-picked constants, not estimated from data.
• Tax: Approximate — see the tax-engine section above. 80C is assumed fully utilised; indexation is a flat CII uplift; some old-regime slabs and surcharge edge cases are simplified.
• Goals: Funding probability compares total assets against the target, but the actual withdrawal then follows a fixed sell order (Debt → Gold → RE → Equity) regardless of per-holding tax flags.
• Inflation-adjusted goals are sized off the median inflation path, not per-path.
• Market data is fetched at request time from yfinance; results vary run-to-run unless rng_seed is pinned and forecasts are cached.

---

Tech Stack

• Frontend: Next.js 14, TypeScript, Tailwind CSS, Recharts, Chart.js.
• Backend: FastAPI (Python), NumPy, Pandas, Prophet.
• AI/LLM: LangGraph, LangChain, Google Gemini API.
• Financial Data: yfinance API.
• Testing: Pytest (backend — tax goldens, determinism, invariants, API contract tests).

Getting Started

Backend Setup

1. Navigate to /backend
2. Create a .env file with your GOOGLE_API_KEY
3. Install dependencies: pip install -r requirements.txt
4. Run server: uvicorn main:app --reload

Optional environment variables:

• FINSIM_CORS_ORIGINS — comma-separated allowed origins (defaults to localhost:3000)
• FINSIM_LOG_LEVEL — logging verbosity (defaults to INFO)

Run the backend test suite:

pip install -r requirements-dev.txt
pytest

Client Setup

1. Navigate to /client
2. Install dependencies: npm install
3. Run development server: npm run dev

---

Developed by Chinmay Nakwa