Quant India
A full-stack NSE stock intelligence platform. Combines live market data, quantitative alpha scoring, news sentiment analysis, and portfolio tools in a single dark-mode dashboard.
Validation: the quantitative models are covered by ~168,000 property/edge-case
assertions (currently passing) — put-call parity, optimiser weight constraints,
Black-Litterman view responsiveness, HRP clustering behaviour, Monte Carlo
percentile ordering, and more. The suites are deterministic and offline:
cd backend
python tests/test_core_properties.py # ~81,000 assertions
python tests/test_new_algorithms_stress.py # ~87,000 assertions
python tests/test_modules_integration.py # import-safety + integration
See VALIDATION.md for each model's formulation, how it was
validated, its assumptions, and its known limitations — and
RESEARCH_momentum.md for an honest backtest write-up
(where correcting a look-ahead flaw erased half the measured edge).
Features
| Section | What it does |
|---|
| Dashboard | Live Nifty 50 prices, MCX commodities, market news, top picks (alpha model), regime analysis, and prediction track record |
| Stocks | Screener table across the NSE universe with P/E / ROE / market cap / sector filters — click any row for full analysis |
| Stock Detail | Company intro, 52-week range, intraday chart, full valuation & balance sheet metrics, 4-factor alpha score with AI explanation, GARCH volatility forecast, news sentiment |
| My Stocks | Personal watchlist with live prices and P&L |
| Simulator | Paper-trade against real NSE prices (realtime) or replay historical data |
| Portfolio Lab | Mean-variance optimisation, Black-Litterman, HRP, efficient frontier |
| Research | Sentiment-alpha backtest, mean-reversion, momentum studies, pairs trading |
| Markets | MCX commodities, macro news, market regime (3-state Gaussian HMM) |
| Calculators | SIP, lumpsum, STCG/LTCG tax |
Alpha model
Ranks every large liquid NSE stock on four quantitative factors — momentum, quality, value, and sentiment — then explains each signal with a Fama-French reality check.
Tech stack
Backend — Python 3.11, FastAPI, yfinance, FinBERT (sentiment), GARCH (arch), XGBoost, scipy/statsmodels, APScheduler
Frontend — React 18, Vite, Tailwind CSS, Recharts, TanStack Query, React Router v6
Local setup
Prerequisites
- Python 3.11+
- Node.js 18+
- A free NewsAPI key
1. Clone
git clone https://github.com/YOUR_USERNAME/quant-india.git
cd quant-india
2. Backend
cd backend
python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env and add your NEWS_API_KEY
GPU note: requirements.txt installs the CPU build of PyTorch. If you have an NVIDIA GPU, replace the torch line with:
pip install torch --index-url https://download.pytorch.org/whl/cu124
uvicorn main:app --reload --port 8000
Backend is live at http://localhost:8000. First startup downloads FinBERT (~420 MB).
3. Frontend
cd frontend
npm install
npm run dev
Frontend is live at http://localhost:5173. The Vite dev server proxies /api to localhost:8000 automatically.
Environment variables
| Variable | Required | Description |
|---|
NEWS_API_KEY | Yes | newsapi.org free key |
GMAIL_ADDRESS | No | Gmail address for price/signal alerts |
GMAIL_APP_PASSWORD | No | Gmail app password (not your main password) |
GMAIL_RECEIVER | No | Email address to receive alerts |
FRONTEND_URL | No | Set in production for CORS (your Vercel URL) |
Deployment
Full step-by-step in DEPLOY.md.
Quick summary:
- Backend → Render (Docker, Standard plan — 2 GB RAM needed for FinBERT)
- Frontend → Vercel (free, auto-detects Vite)
# After any change
git add -A
git commit -m "your message"
git push
# Render and Vercel redeploy automatically
Project structure
quant-india/
├── backend/
│ ├── main.py # FastAPI app, all route definitions
│ ├── requirements.txt
│ ├── Dockerfile
│ ├── .env.example
│ └── modules/
│ ├── alpha_model.py # 4-factor alpha scoring + XGBoost
│ ├── metrics.py # Valuation, Piotroski, DuPont, health score
│ ├── sentiment.py # FinBERT news sentiment
│ ├── regime_detector.py # Gaussian HMM market regime
│ ├── garch_vol.py # GARCH volatility forecasting
│ ├── screener.py # NSE universe screener
│ ├── portfolio_optimizer.py # MVO, Black-Litterman, HRP
│ ├── simulator.py # Paper trading engine
│ ├── news.py / rss_news.py # NewsAPI + RSS feed aggregation
│ └── ...
└── frontend/
├── src/
│ ├── App.jsx # Routes
│ ├── api.js # All Axios calls
│ ├── pages/
│ │ ├── Dashboard.jsx
│ │ ├── StockExplorer.jsx # Stocks list + detail (combined)
│ │ ├── MyStocks.jsx
│ │ ├── Simulator.jsx
│ │ ├── PortfolioLab.jsx
│ │ ├── QuantResearch.jsx
│ │ ├── Markets.jsx
│ │ └── Calculators.jsx
│ └── components/
│ ├── Sidebar.jsx
│ ├── AlphaMeter.jsx
│ ├── StatCard.jsx
│ └── ...
└── vite.config.js
Known limitations
- Ephemeral storage on Render — watchlist and saved simulations reset on redeploy. Add a persistent disk to fix.
- NSE stock-list download may be blocked from some cloud IPs; a built-in fallback covers the major stocks.
- ~30-60 s cold start after the backend idles (FinBERT reload). Top Picks specifically warns about this.
- Data is sourced from yfinance (delayed ~15 min during market hours) and NewsAPI. Not for live trading.
Disclaimer
This project is for educational and research purposes only. Nothing here constitutes financial advice. Past model performance does not predict future returns.
