thinkingEverytime/QuantOracle
1
1---2title: QuantOracle3emoji: "📈"4colorFrom: "indigo"5colorTo: "pink"6sdk: docker7app_port: 78608pinned: false9---10 11# QuantOracle12 13India-first quant research + portfolio intelligence app (Streamlit) with an EOD market screener pipeline.14 15[Live app (Hugging Face Spaces)](https://huggingface.co/spaces/thinkingEverytime/QuantOracle) (cold start can take a couple minutes)16 17[](https://github.com/rishigupta2004/QuantOracle/actions/workflows/ci.yml)18[](https://github.com/rishigupta2004/QuantOracle/actions/workflows/eod_pipeline.yml)19[](#)20[](LICENSE)21 22## What’s Inside23 24- **Markets**: candlesticks + indicators + symbol search (India-first)25- **Portfolio**: holdings, P/L, simple rebalance suggestions26- **Risk**: VaR, max drawdown, beta/correlation27- **Quant ML**:28 - single-stock baselines (on-demand)29 - EOD market screener (published snapshot after close; fast + deterministic in the UI)30 31## Data (Practical Coverage)32 33- **NSE cash equities + ETFs (EOD/intraday snapshots)**: provider chain with `--provider auto` (Upstox -> Groww -> EODHD/Finnhub -> Yahoo fallback)34- **Indices**: shown via **tradable ETF proxies** (e.g., `NIFTYBEES.NS`, `BANKBEES.NS`, `ITBEES.NS`)35- **Global tickers / crypto**: free-first fallbacks (CoinGecko + Yahoo)36- **News**: daily published intel snapshot (`news/intel/latest.json`) with official-source + impact tags, then live fallback chain (NewsData/TheNewsAPI/GNews/RSS)37 38## Machine Learning39 40### Single Stock (On-Demand Baselines)41- **Moving Average**: SMA20/SMA50 crossover signal42- **Multi-factor Technical Score**: combines indicators (RSI / trend / volatility-style heuristics)43- **Mean Reversion**: Bollinger Bands + RSI oversold/overbought logic44 45### EOD Market Screener (Published)46- **Model**: ridge regression (closed-form; no sklearn dependency)47- **Target**: predicted forward return (default horizon: 5 trading days)48- **Features (lightweight + robust)**: recent returns (1d/5d/20d), 20d volatility, price vs SMA20/SMA50, RSI1449- **Outputs**: top/bottom ranks + a constraint-based long/short portfolio50 51## Risk + Quant Portfolio52 53- **VaR (95/99)**: daily-loss estimate from the return distribution54- **Max drawdown**: largest peak-to-trough fall over the lookback window55- **Beta / correlation**: market sensitivity vs an India market proxy (`NIFTYBEES.NS`)56- **Long/short construction (EOD)**: constraints for gross/net exposure + max per-name weight57 58## Visuals (Illustrative)59 60These example visuals show the kind of outputs QuantOracle produces (not a claim about any specific ticker’s future performance).61 6263 6465 6667 68## Architecture (EOD Pipeline)69 70Hugging Face Spaces storage is ephemeral, so QuantOracle uses a published-artifacts workflow:71 72- **Publisher (GitHub Actions, after close)**: fetches EOD candles via provider chain (`auto`), builds a feature snapshot, trains a ridge model, uploads artifacts73- **UI (Hugging Face Spaces)**: downloads `latest.json` + `features.parquet` + model files and renders instantly (no training in the UI)74 7576 77## New Web App (Vercel)78 79QuantOracle now includes a full Next.js command center in `web/` (single-project deploy to Vercel):80 81- UI: workspace plan badge, upgrade modal, entitlement gates, usage meter cards82- API routes (same project):83 - `GET /api/health`84 - `GET /api/status` (provider/key readiness + optional probe)85 - `GET /api/billing/workspaces/{id}/usage`86 - `GET /api/quotes`87 - `GET /api/news`88 - `GET /api/macro`89 - `GET /api/upstox/callback`90 91Run locally:92 93```bash94cd web95npm install96npm run dev97```98 99Then open `http://localhost:3000`.100 101Web shell shortcuts:102 103- `Cmd/Ctrl + K`: command palette104- `Alt + L` / `Alt + R`: toggle left/right drawers105- `Alt + 1..5`: focus map/quotes/news/macro/entitlements106- `Alt + 6..8`: set layout preset (`atlas` / `focus` / `stack`)107- `Alt + Q/W/E`: load layout slot `1/2/3`108- `Alt + Shift + Q/W/E`: save current layout to slot `1/2/3`109- `Alt + 0`: reset layout (drawers + panels + slots)110 111Deployment smoke test:112 113```bash114python scripts/smoke_vercel_web.py --base-url https://quant-oracle.vercel.app115```116 117Strict mode (fails on schema/status checks):118 119```bash120python scripts/smoke_vercel_web.py --base-url https://quant-oracle.vercel.app --strict121```122 123Published data freshness check (quotes + EOD + news intel):124 125```bash126python scripts/check_data_freshness.py --strict127```128 129Manual news intel publish:130 131```bash132python scripts/publish_news_intel.py --max-items 60 --upload133```134 135Push available local env values to Vercel (prod+dev):136 137```bash138python scripts/push_vercel_env.py --root . --targets production,development139```140 141Push preview env values for a specific branch:142 143```bash144python scripts/push_vercel_env.py --root . --targets preview --preview-branch main145```146 147## Upstox Pending Mode148 149If Upstox account activation is pending (no access token/map yet), QuantOracle web still works with:150 151- Billing cards + entitlement gates152- News pipeline153- Macro pulse154- Crypto quotes (CoinGecko)155- Supabase snapshot fallback for symbols available in `quotes.json`156 157Once Upstox is active, set `UPSTOX_ACCESS_TOKEN` + `UPSTOX_SYMBOL_MAP` in Vercel and redeploy to enable live India quote coverage.158 159## Repository Layout160 161```text162api/ FastAPI backend (billing/workspace usage endpoint)163web/ Next.js app + API routes for Vercel deployment164frontend/ Streamlit app (pages, theme, services)165quant/ Core analytics + features + model helpers166scripts/ Publisher + diagnostics167tests/ pytest suite168streamlit_app.py Hugging Face Spaces entrypoint (repo root)169data/universe/ Universe lists (tracked)170```171 172## Roadmap (Next-Level Quant)173 174- Walk-forward evaluation reports + model registry/versioning UI175- Better models (GBDT) + broader feature set + factor diagnostics176- Long/short portfolio construction with constraints (gross/net, caps, turnover, risk sizing)177- Persistent portfolio storage (Supabase DB) + scheduled universe management178- Raise test coverage target to 90%+ (currently gated at 50% to move fast; increase once core pipeline is stable)179 180## Disclaimer181 182Not investment advice. Data source availability and licensing vary by provider.183 184## License185 186MIT - see `LICENSE`.187