spb/vquant Public MIT
VibeQuant — AI-powered institutional-grade financial intelligence platform.
TypeScript 84.3%
Python 11.7%
JavaScript 1.6%
CSS 1.5%
HTML 0.7%
1<!--2 =============================================================================3 VibeQuant (vquant) — AI-Powered Financial Intelligence Platform4 -----------------------------------------------------------------------------5 File: README.md67 Author: Simon-Pierre Boucher8 Contact: contact@spboucher.ai9 Website: https://www.spboucher.ai10 Demo: https://www.vquant.ai11 License: MIT (see LICENSE)1213 Copyright © 2026 Simon-Pierre Boucher. All rights reserved.14 =============================================================================15-->1617<div align="center">1819# VibeQuant2021### AI-Powered Institutional-Grade Financial Intelligence Platform2223<br/>2425**🌐 Live Demo: [www.vquant.ai](https://www.vquant.ai)**2627[](https://www.vquant.ai)28[](./LICENSE)29[](./)3031<br/>3233<a href="https://www.vquant.ai">34 <picture>35 <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/home-dark.png">36 <img alt="VQuant — AI-powered financial analysis assistant" src="docs/screenshots/home.png" width="92%">37 </picture>38</a>3940<sup>_The hero adapts to your GitHub theme — just like the app adapts to yours._ 🌗</sup>4142<br/>4344**Stack**4546[](https://www.typescriptlang.org/)47[](https://react.dev/)48[](https://vitejs.dev/)49[](https://expressjs.com/)50[](https://nodejs.org/)51[](https://tailwindcss.com/)5253**AI & Data**5455[-d97706?style=flat-square&logo=anthropic&logoColor=white)](https://anthropic.com/)56[](https://python.org/)57[](https://numpy.org/)58[](https://pandas.pydata.org/)59[](https://scipy.org/)60[](https://scikit-learn.org/)6162**Database & ORM**6364[](https://sqlite.org/)65[](https://postgresql.org/)66[](https://orm.drizzle.team/)67[](https://zod.dev/)6869**Quality & Testing**7071[](https://eslint.org/)72[](https://prettier.io/)73[](https://vitest.dev/)74[](https://testing-library.com/)7576**Metrics**7778[](./)79[](./)80[](./)81[](./)82[](./)83[](./)84[](./)85[](./)86[](./)87[](./)8889---9091[**Screenshots**](#screenshots) • [**Getting Started**](#getting-started) • [**Features**](#features) • [**Architecture**](#architecture) • [**API Reference**](#api-reference) • [**Contributing**](#contributing)9293</div>9495---9697## Overview9899VibeQuant is a production-grade full-stack financial analysis platform that combines **Claude AI (Fable 5 default, 6 selectable models, up to 1M token context)** with **265+ financial data endpoints**, **quantitative Python analysis** (Monte Carlo, GARCH, VaR, Black-Scholes, portfolio optimization), and **multi-source web research** (Tavily, Firecrawl, Exa, SerpAPI) to deliver institutional-grade insights through a real-time streaming conversational interface.100101Built with a modern TypeScript stack (React 18 + Vite + Express + Drizzle ORM), validated with Zod schemas, tested with Vitest, and linted with ESLint + Prettier.102103---104105## Screenshots106107> 📸 Captured live from [www.vquant.ai](https://www.vquant.ai)108109<table>110 <tr>111 <td align="center" width="50%">112 <a href="docs/screenshots/report.png">113 <img src="docs/screenshots/report.png" alt="AI-generated analysis report with one-click export"/>114 </a>115 <br/><b>🤖 AI Analysis Reports</b><br/>116 <sub>Streaming Claude-generated research reports with one-click <b>Markdown / PDF / Word / Slides</b> export</sub>117 </td>118 <td align="center" width="50%">119 <a href="docs/screenshots/report-scrolled.png">120 <img src="docs/screenshots/report-scrolled.png" alt="Rich markdown report rendering"/>121 </a>122 <br/><b>📊 Institutional-Grade Content</b><br/>123 <sub>Rich markdown rendering — tables, sourced data, structured investment theses</sub>124 </td>125 </tr>126 <tr>127 <td align="center" width="50%">128 <a href="docs/screenshots/showcase.png">129 <img src="docs/screenshots/showcase.png" alt="Community showcase of public analyses"/>130 </a>131 <br/><b>🌐 Community Showcase</b><br/>132 <sub>Hundreds of public analyses, searchable, with the exact tool-chain used by the agent on every card</sub>133 </td>134 <td align="center" width="50%">135 <a href="docs/screenshots/docs.png">136 <img src="docs/screenshots/docs.png" alt="In-app documentation and AI model selection"/>137 </a>138 <br/><b>📚 Built-in Documentation</b><br/>139 <sub>6 selectable Claude models (Fable 5 default, 1M context) and 200+ documented tools</sub>140 </td>141 </tr>142</table>143144---145146## Features147148### Financial Data Engine149150[](https://financialmodelingprep.com/)151152| Category | Endpoints | Details |153|----------|-----------|---------|154| **Company Fundamentals** | 40+ | Profiles, income statements, balance sheets, cash flows, key metrics, financial ratios, growth rates |155| **Market Data** | 30+ | Real-time quotes, historical prices, intraday data, batch quotes, market hours, gainers/losers/actives |156| **Technical Analysis** | 15+ | RSI, MACD, EMA, SMA, ADX, Williams %R, CCI, Stochastic, WMA, DEMA, TEMA, Bollinger Bands |157| **Analyst & Ratings** | 20+ | Estimates, price targets, upgrades/downgrades, consensus, historical grades, ratings snapshots |158| **Insider & Institutional** | 15+ | Insider trading, institutional holders, 13F filings, Senate/House trading, beneficial ownership |159| **Economic & Macro** | 15+ | Economic calendar, Treasury rates, economic indicators, market risk premium, COT reports |160| **SEC & Compliance** | 25+ | SEC filings (8-K, 10-K, 10-Q), EDGAR search, company notes, earnings transcripts |161| **Alternative Data** | 20+ | ESG scores, social sentiment, Congressional trading, crowdfunding, equity offerings |162| **ETFs & Indices** | 15+ | ETF holdings, sector weightings, S&P 500/NASDAQ/Dow Jones constituents |163| **Valuation** | 10+ | DCF, levered DCF, custom DCF, enterprise values, owner earnings, financial scores |164| **Forex & Crypto** | 15+ | Forex pairs, crypto quotes, commodity prices, historical forex data |165| **Events** | 10+ | Earnings calendar, IPO calendar, dividend history, stock splits, mergers & acquisitions |166167### Quantitative Analysis Engine168169[](https://python.org/)170171| Model | Description | Libraries |172|-------|-------------|-----------|173| **Monte Carlo Simulation** | Price path simulation with customizable parameters (10k+ paths, configurable horizon) | `numpy`, `scipy` |174| **Options Pricing** | Black-Scholes model with full Greeks (delta, gamma, theta, vega, rho) | `scipy.stats` |175| **GARCH Volatility** | Volatility modeling and forecasting with GARCH(1,1) | `arch`, `statsmodels` |176| **Value at Risk (VaR)** | Historical, parametric, and Monte Carlo VaR at multiple confidence levels | `numpy`, `scipy` |177| **Portfolio Optimization** | Mean-variance optimization (Modern Portfolio Theory), efficient frontier | `cvxpy`, `scipy.optimize` |178| **Risk Metrics** | Sharpe, Sortino, Calmar, max drawdown, beta, alpha, information ratio | `numpy`, `pandas` |179| **Custom Python** | Arbitrary Python code execution with access to 17 libraries and FMP data | All libraries |180181<details>182<summary><b>Full Python library list (17 packages)</b></summary>183184| Library | Version | Purpose |185|---------|---------|---------|186| `numpy` | latest | Numerical computing |187| `pandas` | latest | Data manipulation |188| `scipy` | latest | Scientific computing |189| `scikit-learn` | latest | Machine learning |190| `statsmodels` | latest | Statistical models |191| `matplotlib` | latest | Plotting & charts |192| `seaborn` | latest | Statistical visualization |193| `plotly` | latest | Interactive charts |194| `arch` | latest | GARCH models |195| `cvxpy` | latest | Convex optimization |196| `yfinance` | latest | Market data |197| `ta` | latest | Technical analysis |198| `quantstats` | latest | Portfolio analytics |199| `beautifulsoup4` | latest | Web scraping |200| `requests` | latest | HTTP client |201| `lxml` | latest | XML/HTML parsing |202| `Pillow` | latest | Image processing |203204</details>205206### Web Research Engine207208| Source | Capabilities | Badge |209|--------|-------------|-------|210| **Tavily** | AI-powered search with generated answers, time filters, domain filtering | [](https://tavily.com/) |211| **Firecrawl** | Web scraping, PDF extraction (up to 750 pages), intelligent crawling, structured extraction, autonomous agents | [](https://firecrawl.dev/) |212| **Exa** | Semantic neural search, content retrieval, similar page discovery | [](https://exa.ai/) |213| **SerpAPI** | Google Search, Images, Shopping, Finance, Trends, Scholar, Videos, Flights, Hotels | [](https://serpapi.com/) |214215### AI Agent216217[](https://anthropic.com/)218219| Feature | Details |220|---------|---------|221| **Models** | 6 selectable Claude models — **Fable 5** (default), **Opus 4.8 / 4.7 / 4.6**, **Sonnet 4.6**, **Haiku 4.5** — up to 1M token context |222| **Model Selector** | Switchable from the input bar and the welcome screen (per-model icons); selection persisted in `localStorage` |223| **Reasoning** | Adaptive extended thinking shown in a collapsible "Raisonnement" widget that auto-expands while the model thinks (Fable 5 / Opus / Sonnet; Haiku has no adaptive thinking) |224| **Tools** | 213 specialized financial tools |225| **Batching** | Intelligent tool batching (5 tools per batch with 500ms pauses) |226| **Streaming** | Real-time Server-Sent Events (SSE) for instant response display |227| **History** | Persistent conversation sessions with token tracking |228| **Vision** | Image analysis support (charts, screenshots, documents) |229| **Cost Tracking** | Per-session input/output token counting and cost estimation |230231### Interface & Design232233| Aspect | Details |234|--------|---------|235| **Theme** | Modern light/dark themes with an indigo-violet accent; toggle persisted in `localStorage` |236| **Design** | Rounded soft-cornered components, subtle background gradient, thin rounded scrollbars |237| **Welcome screen** | Categorized example prompts + dedicated model selector with per-model icons |238| **Stack** | Tailwind CSS 3.4 + Radix UI primitives |239240### Export & Reports241242| Format | Description | Badge |243|--------|-------------|-------|244| **PDF** | Professional reports generated with Puppeteer, markdown rendering | [](./) |245| **DOCX** | Word documents via Pandoc conversion | [](./) |246| **LaTeX Slides** | Beamer presentations with professional theming | [](./) |247| **Data Files** | CSV, XLSX, JSON, TXT downloads of analysis data | [](./) |248| **Share Links** | Shareable report URLs with unique IDs | [](./) |249250---251252## Getting Started253254### Prerequisites255256[](https://nodejs.org/)257[](https://python.org/)258[](https://npmjs.com/)259260### Installation261262```bash263# Clone the repository264git clone https://github.com/spboucher-ai/vquant.git265cd vquant266267# Install Node.js dependencies268npm install269270# Set up Python virtual environment271python3 -m venv .venv272source .venv/bin/activate # macOS/Linux273# .venv\Scripts\activate # Windows274pip install -r requirements-safe.txt275276# Configure environment variables277cp .env.example .env278# Edit .env with your API keys279280# Start development server281npm run dev282```283284The app will be available at `http://localhost:5000`.285286### API Keys287288All services offer generous free tiers:289290| Service | Sign Up | Free Tier | Required |291|---------|---------|-----------|----------|292| [](https://console.anthropic.com) | [console.anthropic.com](https://console.anthropic.com) | $5 credit | **Yes** |293| [](https://financialmodelingprep.com) | [financialmodelingprep.com](https://financialmodelingprep.com) | 250 calls/day | **Yes** |294| [](https://firecrawl.dev) | [firecrawl.dev](https://firecrawl.dev) | 500 credits | Recommended |295| [](https://app.tavily.com) | [app.tavily.com](https://app.tavily.com) | 1000 calls/month | Recommended |296| [](https://exa.ai) | [exa.ai](https://exa.ai) | 1000 searches/month | Optional |297| [](https://serpapi.com) | [serpapi.com](https://serpapi.com) | 100 searches/month | Optional |298299---300301## Scripts302303| Command | Description |304|---------|-------------|305| `npm run dev` | Start development server (Vite HMR + Express) |306| `npm run build` | Build for production (client + server) |307| `npm start` | Start production server |308| `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) |309| `npm run lint` | ESLint check |310| `npm run lint:fix` | ESLint auto-fix |311| `npm run format` | Prettier format all files |312| `npm run format:check` | Prettier check (CI-friendly) |313| `npm test` | Run all tests (Vitest) |314| `npm run test:watch` | Run tests in watch mode |315| `npm run test:coverage` | Run tests with coverage report |316| `npm run db:push` | Push database schema changes (Drizzle Kit) |317318---319320## Architecture321322```323vquant/324├── client/src/ # Frontend (React + TypeScript)325│ ├── App.tsx # Router + providers + ErrorBoundary326│ ├── main.tsx # Entry point327│ ├── config.ts # App config, endpoints, feature flags328│ ├── components/329│ │ ├── chat/ # 13 chat-specific components330│ │ │ ├── search-bar.tsx # Query input with image support331│ │ │ ├── streaming-answer.tsx # Real-time markdown rendering332│ │ │ ├── agent-steps.tsx # Tool execution progress333│ │ │ ├── tool-results.tsx # Financial data display334│ │ │ ├── monte-carlo-results.tsx # Simulation visualizations335│ │ │ ├── share-button.tsx # Report sharing336│ │ │ ├── download-buttons.tsx # PDF/DOCX export337│ │ │ └── ... # + 6 more components338│ │ ├── explore/ # 7 stock explorer components339│ │ ├── financial/ # Price charts, options pricing340│ │ ├── ui/ # 35 shadcn/ui primitives341│ │ └── error-boundary.tsx # Global error handler342│ ├── hooks/343│ │ ├── useChatSession.ts # All chat state & business logic344│ │ ├── useChatMutation.ts # SSE streaming client345│ │ ├── useAnalytics.ts # Heartbeat tracking346│ │ ├── use-toast.ts # Toast notifications347│ │ └── use-mobile.tsx # Responsive detection348│ ├── pages/ # 9 route pages349│ │ ├── home.tsx # Main chat interface (255 lines)350│ │ ├── explore.tsx # Stock explorer351│ │ ├── admin.tsx # Admin dashboard352│ │ ├── auth.tsx # Login/register353│ │ ├── showcase.tsx # Community reports354│ │ ├── shared-report.tsx # Shared report viewer355│ │ ├── documentation.tsx # API documentation356│ │ └── ... # + privacy, terms, slides, 404357│ ├── lib/358│ │ ├── queryClient.ts # TanStack Query config359│ │ └── utils.ts # cn() + helpers360│ └── utils/361│ ├── chartCapture.ts # Chart-to-image conversion362│ └── pdfGenerator.ts # Client-side PDF generation363│364├── server/ # Backend (Express + TypeScript)365│ ├── index.ts # Server bootstrap, CORS, sessions366│ ├── routes.ts # /api/chat (SSE streaming) + speech-to-text367│ ├── routes/368│ │ ├── auth.ts # /api/auth/* (register, login, logout, me)369│ │ ├── admin.ts # /api/admin/* (database, CRUD) + requireAdmin370│ │ ├── analytics.ts # /api/analytics/* (heartbeat, active users, metrics)371│ │ ├── fmp.ts # /api/fmp/* (23 financial data endpoints)372│ │ ├── reports.ts # /api/share/*, sessions, PDF/DOCX/slides, download373│ │ └── validation.ts # Zod request schemas374│ ├── services/375│ │ ├── claude/376│ │ │ ├── toolDefinitions.ts # 213 tool definitions (4,480 lines)377│ │ │ └── tokenManagement.ts # Context window management378│ │ ├── claudeService.ts # Claude API integration379│ │ ├── fmpService.ts # 230 FMP API wrapper functions380│ │ ├── python/381│ │ │ ├── monteCarlo.ts # Monte Carlo simulation382│ │ │ ├── optionsPricing.ts # Black-Scholes pricing383│ │ │ ├── garch.ts # GARCH volatility model384│ │ │ ├── var.ts # VaR + portfolio + risk metrics385│ │ │ └── shared.ts # Python executor config386│ │ ├── *.py # 11 Python scientific services387│ │ ├── firecrawlService.ts # Web extraction388│ │ ├── tavilyService.ts # AI search389│ │ ├── exaService.ts # Semantic search390│ │ └── serpapiService.ts # Google search391│ ├── db.ts # Drizzle ORM (SQLite + PostgreSQL)392│ ├── storage.ts # Typed data access layer393│ ├── types/394│ │ └── modules.d.ts # Module declarations395│ └── utils/396│ └── logger.ts # Structured logging397│398├── shared/ # Shared between client & server399│ ├── schema.ts # PostgreSQL schema (Drizzle)400│ ├── schema-sqlite.ts # SQLite schema (Drizzle)401│ └── types.ts # API interfaces (SearchResult, etc.)402│403├── vitest.config.ts # Test configuration404├── eslint.config.js # ESLint flat config405├── vite.config.ts # Vite build config406├── tsconfig.json # TypeScript config407├── tailwind.config.ts # Tailwind CSS config408├── .prettierrc # Prettier config409├── .editorconfig # Editor config410├── .env.example # Environment template411└── .gitignore # Git ignore rules412```413414### System Architecture415416```417┌──────────────────────────────────────────────────────────────────┐418│ CLIENT (React 18) │419│ ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌───────────┐ │420│ │ Chat UI │ │ Explore Page │ │ Admin Panel│ │ Auth/Docs │ │421│ │ (SSE) │ │ (FMP data) │ │ (Analytics)│ │ (Sessions)│ │422│ └────┬─────┘ └──────┬───────┘ └─────┬──────┘ └─────┬─────┘ │423│ │ │ │ │ │424│ ┌────┴───────────────┴────────────────┴───────────────┴─────┐ │425│ │ TanStack Query + useChatSession │ │426│ └───────────────────────────┬───────────────────────────────┘ │427└──────────────────────────────┼──────────────────────────────────┘428 │ HTTP / SSE429┌──────────────────────────────┼──────────────────────────────────┐430│ SERVER (Express 4) │431│ ┌───────────────────────────┴───────────────────────────────┐ │432│ │ Route Modules (6) │ │433│ │ auth │ admin │ analytics │ fmp │ reports │ chat (SSE) │ │434│ └───┬───────┬──────────┬──────────┬──────────┬──────────────┘ │435│ │ │ │ │ │ │436│ ┌───┴───┐ ┌─┴──────┐ ┌┴────────┐ │ ┌─────┴──────────────┐ │437│ │Storage│ │Analytics│ │Zod Valid│ │ │ Claude Opus 4.8 │ │438│ │(Drizzle)│ │Metrics │ │Schemas │ │ │ 213 tools │ │439│ └───┬───┘ └────────┘ └────────┘ │ │ 5-tool batching │ │440│ │ │ └──────────┬──────────┘ │441│ ┌───┴──────┐ ┌─────┴──────┐ ┌─────┴──────────┐ │442│ │SQLite/PG │ │ FMP Service│ │ Python Engine │ │443│ │(Drizzle) │ │ 230 funcs │ │ 17 libraries │ │444│ └──────────┘ └────────────┘ └────────────────┘ │445│ │446│ ┌────────────────────────────────────────────────────────────┐ │447│ │ External APIs │ │448│ │ Tavily │ Firecrawl │ Exa │ SerpAPI │ ElevenLabs │ │449│ └────────────────────────────────────────────────────────────┘ │450└─────────────────────────────────────────────────────────────────┘451```452453---454455## API Reference456457### Chat (SSE Streaming)458459| Method | Endpoint | Description |460|--------|----------|-------------|461| `POST` | `/api/chat` | Main AI chat with streaming (Server-Sent Events) |462| `POST` | `/api/speech-to-text` | Audio transcription (ElevenLabs Scribe) |463464### Authentication465466| Method | Endpoint | Description |467|--------|----------|-------------|468| `POST` | `/api/auth/register` | Create account (generates unique token) |469| `POST` | `/api/auth/login` | Authenticate with token |470| `POST` | `/api/auth/logout` | End session |471| `GET` | `/api/auth/me` | Get current user |472473### Shared Reports & Sessions474475| Method | Endpoint | Description |476|--------|----------|-------------|477| `GET` | `/api/shared-reports` | List all shared reports |478| `POST` | `/api/share` | Create shareable report |479| `GET` | `/api/share/:shareId` | Get shared report |480| `GET` | `/api/sessions` | List user sessions |481| `GET` | `/api/sessions/:id` | Get session with messages |482483### Document Generation484485| Method | Endpoint | Description |486|--------|----------|-------------|487| `POST` | `/api/generate-pdf` | Markdown to PDF (Puppeteer) |488| `POST` | `/api/generate-docx` | Markdown to DOCX (Pandoc) |489| `POST` | `/api/convert-to-slides` | Markdown to Beamer LaTeX PDF |490| `GET` | `/api/download/:filename` | Download data file |491492### Financial Data (FMP)493494| Method | Endpoint | Description |495|--------|----------|-------------|496| `GET` | `/api/fmp/quote/:symbol` | Real-time stock quote |497| `GET` | `/api/fmp/company-profile/:symbol` | Company profile |498| `GET` | `/api/fmp/historical-price/:symbol` | Historical prices |499| `GET` | `/api/fmp/intraday/:symbol` | Intraday price data |500| `GET` | `/api/fmp/income-statement/:symbol` | Income statement |501| `GET` | `/api/fmp/balance-sheet/:symbol` | Balance sheet |502| `GET` | `/api/fmp/cash-flow/:symbol` | Cash flow statement |503| `GET` | `/api/fmp/key-metrics/:symbol` | Key financial metrics |504| `GET` | `/api/fmp/financial-ratios/:symbol` | Financial ratios |505| `GET` | `/api/fmp/analyst-estimates/:symbol` | Analyst estimates |506| `GET` | `/api/fmp/price-target/:symbol` | Price targets |507| `GET` | `/api/fmp/insider-trading/:symbol` | Insider trades |508| `GET` | `/api/fmp/institutional-holders/:symbol` | Institutional holders |509| `GET` | `/api/fmp/earnings-surprises/:symbol` | Earnings surprises |510| `GET` | `/api/fmp/dividend-history/:symbol` | Dividend history |511| `GET` | `/api/fmp/esg-score/:symbol` | ESG score |512| `GET` | `/api/fmp/financial-news/:symbol` | Financial news |513| `GET` | `/api/fmp/upgrades-downgrades/:symbol` | Analyst upgrades/downgrades |514| `GET` | `/api/fmp/gainers` | Top market gainers |515| `GET` | `/api/fmp/losers` | Top market losers |516| `GET` | `/api/fmp/actives` | Most active stocks |517| `GET` | `/api/fmp/market-hours` | Market hours |518| `GET` | `/api/fmp/chart/light/:symbol` | Lightweight chart data |519520### Analytics & Admin521522| Method | Endpoint | Description |523|--------|----------|-------------|524| `POST` | `/api/analytics/heartbeat` | Update user activity |525| `GET` | `/api/analytics/active-users` | Active users (admin) |526| `GET` | `/api/analytics/real-time-stats` | Real-time stats |527| `GET` | `/api/analytics/metrics` | Historical metrics (admin) |528| `POST` | `/api/admin/login` | Admin login |529| `GET` | `/api/admin/database` | Full database view (admin) |530| `DELETE` | `/api/admin/users/:id` | Delete user (admin) |531| `DELETE` | `/api/admin/sessions/:id` | Delete session (admin) |532| `DELETE` | `/api/admin/reports/:id` | Delete report (admin) |533534---535536## Usage Examples537538### Financial Analysis539```540"Full analysis of NVDA: profile, financials, insider trades, analyst ratings, sector performance"541542"Compare AAPL, MSFT, GOOGL on: market cap, P/E, revenue growth, ESG scores, analyst consensus"543544"Due diligence on TSLA: DCF valuation, institutional holders, insider trading patterns, earnings surprises"545546"Show me the top gainers today with their financial ratios and analyst ratings"547```548549### Quantitative Analysis550```551"Run a Monte Carlo simulation on AAPL with 10,000 paths over 252 trading days"552553"Calculate the correlation matrix of FAANG stocks and display a heatmap"554555"Backtest an RSI strategy on SPY and show the equity curve with Sharpe ratio"556557"Optimize a portfolio of AAPL, MSFT, GOOGL, AMZN for maximum Sharpe ratio"558559"Calculate Value at Risk for a $100,000 NVDA position at 95% and 99% confidence"560561"Estimate GARCH volatility for TSLA and forecast 30-day ahead volatility"562563"Price a call option on AAPL with strike $200, 30 days to expiry, and show all Greeks"564```565566### Web Research567```568"Search latest AI industry news this week and summarize key developments"569570"Extract the last NVIDIA earnings call transcript and highlight guidance changes"571572"Research the impact of Fed rate decisions on tech stocks in 2024-2025"573574"Crawl investor.nvidia.com and extract all Q4 financial press releases"575```576577---578579## Documentation580581Exhaustive documentation is available in the [`docs/`](./docs) directory:582583| Document | Description |584|----------|-------------|585| **[Getting Started](./docs/GETTING_STARTED.md)** | Prerequisites, installation, Python setup, env vars, first run, troubleshooting |586| **[Architecture](./docs/ARCHITECTURE.md)** | System diagram, directory structure, data flow, design decisions |587| **[API Reference](./docs/API_REFERENCE.md)** | All 44 endpoints with request/response schemas, SSE event types, query params |588| **[Python Analysis](./docs/PYTHON_ANALYSIS.md)** | 8 built-in models (Monte Carlo, Black-Scholes, GARCH, VaR, portfolio, risk, plots, custom), all 17 libraries |589| **[Database Schema](./docs/DATABASE.md)** | All 9 tables with columns, types, constraints, relationships |590| **[Deployment](./docs/DEPLOYMENT.md)** | Production build, env vars, Docker example, CORS, security checklist |591| **[Contributing](./docs/CONTRIBUTING.md)** | Dev setup, code conventions, commit format, how to add endpoints/tools |592| **[`.env.example`](./.env.example)** | All environment variables with categories |593594---595596## Testing597598[](./)599[](./)600[](./)601602| Suite | Tests | What it covers |603|-------|-------|---------------|604| `App.test.tsx` | 3 | Smoke test: renders, shows home page, search bar present |605| `config.test.ts` | 5 | App config: name, domain, endpoints, limits, feature flags |606| `utils.test.ts` | 5 | `cn()`: class merging, conditionals, dedup, edge cases |607| `queryClient.test.ts` | 6 | Query defaults: staleTime, gcTime, retry, refetch policy |608| `useChatSession.test.tsx` | 6 | Hook: initial state, reset, history toggle, mutation shape, handlers |609| `validation.test.ts` | 16 | All Zod schemas: valid/invalid inputs, missing fields, max lengths |610611```bash612npm test # Run once613npm run test:watch # Watch mode614npm run test:coverage # With coverage615```616617---618619## Deployment620621### Production Build622623```bash624npm run build # Builds client (Vite) + server (esbuild)625npm start # Starts production server626```627628### Environment Variables629630```bash631# Required632NODE_ENV=production633PORT=5000634SESSION_SECRET=<generate-a-strong-random-secret>635ANTHROPIC_API_KEY=sk-ant-...636FINANCIAL_MODELING_PREP_API_KEY=...637638# Database (default: SQLite)639DATABASE_URL=sqlite://local.db640# DATABASE_URL=postgresql://user:pass@host:5432/db641642# Optional APIs643FIRECRAWL_API_KEY=fc-...644TAVILY_API_KEY=tvly-...645EXA_API_KEY=...646SERPAPI_API_KEY=...647```648649---650651## Contributing6526531. Fork the repository6542. Create a feature branch (`git checkout -b feature/my-feature`)6553. Run checks before committing:656 ```bash657 npm run typecheck && npm run lint && npm test658 ```6594. Commit with a descriptive message6605. Open a Pull Request661662### Code Conventions663664| Rule | Enforced By |665|------|------------|666| TypeScript `strict` mode | `tsconfig.json` |667| ESLint (typescript-eslint + react-hooks) | `eslint.config.js` |668| Prettier formatting | `.prettierrc` |669| Zod validation on all API inputs | `server/routes/validation.ts` |670| `logger` instead of `console.log` | ESLint `no-console` rule |671| `@/` path alias (client), `@shared/` (shared) | `tsconfig.json` + `vite.config.ts` |672| Components grouped by domain | `components/chat/`, `components/explore/`, etc. |673| One hook per concern | `useChatSession`, `useChatMutation`, etc. |674675---676677## Authors678679<table>680 <tr>681 <td align="center" width="50%">682 <b>Simon-Pierre Boucher</b><br/>683 <i>Creator & Lead Developer</i><br/><br/>684 <a href="mailto:contact@spboucher.ai"><img src="https://img.shields.io/badge/Email-contact%40spboucher.ai-8b5cf6?style=flat-square&logo=maildotru&logoColor=white"/></a><br/>685 <a href="https://www.spboucher.ai"><img src="https://img.shields.io/badge/Website-spboucher.ai-3b82f6?style=flat-square&logo=safari&logoColor=white"/></a><br/>686 <a href="https://github.com/spboucher-ai"><img src="https://img.shields.io/badge/GitHub-spboucher--ai-181717?style=flat-square&logo=github&logoColor=white"/></a>687 </td>688 <td align="center" width="50%">689 <b>Claude Opus 4.8</b><br/>690 <i>AI Pair Programmer</i><br/><br/>691 <a href="https://claude.ai/claude-code"><img src="https://img.shields.io/badge/Claude_Code-Anthropic-d97706?style=flat-square&logo=anthropic&logoColor=white"/></a><br/>692 <a href="https://anthropic.com"><img src="https://img.shields.io/badge/Model-Opus_4.8_(1M_ctx)-d97706?style=flat-square"/></a><br/>693 <img src="https://img.shields.io/badge/Contribution-9_commits,_4000+_lines-22c55e?style=flat-square"/>694 </td>695 </tr>696</table>697698> Full codebase audit, architecture restructuring, TypeScript typing, route modularization, hook extraction, ESLint/Prettier/Vitest setup, ErrorBoundary, Zod validation, and README authored via [Claude Code](https://claude.ai/claude-code).699700---701702## Acknowledgments703704[](https://anthropic.com/)705[](https://financialmodelingprep.com/)706[](https://firecrawl.dev/)707[](https://tavily.com/)708[](https://exa.ai/)709[](https://radix-ui.com/)710[](https://ui.shadcn.com/)711[](https://recharts.org/)712713---714715## License716717[](./LICENSE)718719---720721<div align="center">722723<br/>724725[](https://www.vquant.ai)726727<br/>728729*Where AI Meets Institutional-Grade Financial Analysis*730731<br/>732733**Built with** 734[](./)735[](./)736[](./)737[](./)738[](./)739[](./)740741</div>742