# VibeQuant ### AI-Powered Institutional-Grade Financial Intelligence Platform
**🌐 Live Demo: [www.vquant.ai](https://www.vquant.ai)** [![Live](https://img.shields.io/badge/Live_Demo-www.vquant.ai-00c853?style=for-the-badge&logo=googlechrome&logoColor=white)](https://www.vquant.ai) [![License](https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge)](./LICENSE) [![Version](https://img.shields.io/badge/Version-2.1.0-7c3aed?style=for-the-badge)](./)
VQuant β€” AI-powered financial analysis assistant _The hero adapts to your GitHub theme β€” just like the app adapts to yours._ πŸŒ—
**Stack** [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![React](https://img.shields.io/badge/React-18.3-61dafb?style=flat-square&logo=react&logoColor=black)](https://react.dev/) [![Vite](https://img.shields.io/badge/Vite-5-646cff?style=flat-square&logo=vite&logoColor=white)](https://vitejs.dev/) [![Express](https://img.shields.io/badge/Express-4.21-000000?style=flat-square&logo=express&logoColor=white)](https://expressjs.com/) [![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/) [![TailwindCSS](https://img.shields.io/badge/Tailwind_CSS-3.4-06b6d4?style=flat-square&logo=tailwindcss&logoColor=white)](https://tailwindcss.com/) **AI & Data** [![Claude AI](https://img.shields.io/badge/Claude-Fable_5_(1M_ctx)-d97706?style=flat-square&logo=anthropic&logoColor=white)](https://anthropic.com/) [![Python](https://img.shields.io/badge/Python-3.11+-3776ab?style=flat-square&logo=python&logoColor=white)](https://python.org/) [![NumPy](https://img.shields.io/badge/NumPy-013243?style=flat-square&logo=numpy&logoColor=white)](https://numpy.org/) [![Pandas](https://img.shields.io/badge/Pandas-150458?style=flat-square&logo=pandas&logoColor=white)](https://pandas.pydata.org/) [![SciPy](https://img.shields.io/badge/SciPy-8caae6?style=flat-square&logo=scipy&logoColor=white)](https://scipy.org/) [![scikit--learn](https://img.shields.io/badge/scikit--learn-f7931e?style=flat-square&logo=scikitlearn&logoColor=white)](https://scikit-learn.org/) **Database & ORM** [![SQLite](https://img.shields.io/badge/SQLite-003b57?style=flat-square&logo=sqlite&logoColor=white)](https://sqlite.org/) [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169e1?style=flat-square&logo=postgresql&logoColor=white)](https://postgresql.org/) [![Drizzle](https://img.shields.io/badge/Drizzle_ORM-c5f74f?style=flat-square&logo=drizzle&logoColor=black)](https://orm.drizzle.team/) [![Zod](https://img.shields.io/badge/Zod-3e67b1?style=flat-square&logo=zod&logoColor=white)](https://zod.dev/) **Quality & Testing** [![ESLint](https://img.shields.io/badge/ESLint-4b32c3?style=flat-square&logo=eslint&logoColor=white)](https://eslint.org/) [![Prettier](https://img.shields.io/badge/Prettier-f7b93e?style=flat-square&logo=prettier&logoColor=black)](https://prettier.io/) [![Vitest](https://img.shields.io/badge/Vitest-6e9f18?style=flat-square&logo=vitest&logoColor=white)](https://vitest.dev/) [![Testing Library](https://img.shields.io/badge/Testing_Library-e33332?style=flat-square&logo=testinglibrary&logoColor=white)](https://testing-library.com/) **Metrics** [![Lines of Code](https://img.shields.io/badge/Lines_of_Code-36,000+-0969da?style=flat-square)](./) [![Source Files](https://img.shields.io/badge/Source_Files-150+-0969da?style=flat-square)](./) [![API Endpoints](https://img.shields.io/badge/API_Endpoints-265+-8b5cf6?style=flat-square)](./) [![Claude Tools](https://img.shields.io/badge/Claude_Tools-213-d97706?style=flat-square)](./) [![Python Libs](https://img.shields.io/badge/Python_Libs-17-3776ab?style=flat-square)](./) [![Tests](https://img.shields.io/badge/Tests-41_passing-22c55e?style=flat-square)](./) [![Test Suites](https://img.shields.io/badge/Test_Suites-6-22c55e?style=flat-square)](./) [![Components](https://img.shields.io/badge/React_Components-57-61dafb?style=flat-square)](./) [![Hooks](https://img.shields.io/badge/Custom_Hooks-5-61dafb?style=flat-square)](./) [![Route Modules](https://img.shields.io/badge/Route_Modules-6-000000?style=flat-square)](./) --- [**Screenshots**](#screenshots)  •  [**Getting Started**](#getting-started)  •  [**Features**](#features)  •  [**Architecture**](#architecture)  •  [**API Reference**](#api-reference)  •  [**Contributing**](#contributing)
--- ## Overview VibeQuant 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. Built with a modern TypeScript stack (React 18 + Vite + Express + Drizzle ORM), validated with Zod schemas, tested with Vitest, and linted with ESLint + Prettier. --- ## Screenshots > πŸ“Έ Captured live from [www.vquant.ai](https://www.vquant.ai)
AI-generated analysis report with one-click export
πŸ€– AI Analysis Reports
Streaming Claude-generated research reports with one-click Markdown / PDF / Word / Slides export 		Rich markdown report rendering
πŸ“Š Institutional-Grade Content
Rich markdown rendering β€” tables, sourced data, structured investment theses
Community showcase of public analyses
🌐 Community Showcase
Hundreds of public analyses, searchable, with the exact tool-chain used by the agent on every card 		In-app documentation and AI model selection
πŸ“š Built-in Documentation
6 selectable Claude models (Fable 5 default, 1M context) and 200+ documented tools
--- ## Features ### Financial Data Engine [![FMP API](https://img.shields.io/badge/FMP_API-230_endpoints-8b5cf6?style=flat-square)](https://financialmodelingprep.com/) | Category | Endpoints | Details | |----------|-----------|---------| | **Company Fundamentals** | 40+ | Profiles, income statements, balance sheets, cash flows, key metrics, financial ratios, growth rates | | **Market Data** | 30+ | Real-time quotes, historical prices, intraday data, batch quotes, market hours, gainers/losers/actives | | **Technical Analysis** | 15+ | RSI, MACD, EMA, SMA, ADX, Williams %R, CCI, Stochastic, WMA, DEMA, TEMA, Bollinger Bands | | **Analyst & Ratings** | 20+ | Estimates, price targets, upgrades/downgrades, consensus, historical grades, ratings snapshots | | **Insider & Institutional** | 15+ | Insider trading, institutional holders, 13F filings, Senate/House trading, beneficial ownership | | **Economic & Macro** | 15+ | Economic calendar, Treasury rates, economic indicators, market risk premium, COT reports | | **SEC & Compliance** | 25+ | SEC filings (8-K, 10-K, 10-Q), EDGAR search, company notes, earnings transcripts | | **Alternative Data** | 20+ | ESG scores, social sentiment, Congressional trading, crowdfunding, equity offerings | | **ETFs & Indices** | 15+ | ETF holdings, sector weightings, S&P 500/NASDAQ/Dow Jones constituents | | **Valuation** | 10+ | DCF, levered DCF, custom DCF, enterprise values, owner earnings, financial scores | | **Forex & Crypto** | 15+ | Forex pairs, crypto quotes, commodity prices, historical forex data | | **Events** | 10+ | Earnings calendar, IPO calendar, dividend history, stock splits, mergers & acquisitions | ### Quantitative Analysis Engine [![Python](https://img.shields.io/badge/Python-17_scientific_libraries-3776ab?style=flat-square&logo=python&logoColor=white)](https://python.org/) | Model | Description | Libraries | |-------|-------------|-----------| | **Monte Carlo Simulation** | Price path simulation with customizable parameters (10k+ paths, configurable horizon) | `numpy`, `scipy` | | **Options Pricing** | Black-Scholes model with full Greeks (delta, gamma, theta, vega, rho) | `scipy.stats` | | **GARCH Volatility** | Volatility modeling and forecasting with GARCH(1,1) | `arch`, `statsmodels` | | **Value at Risk (VaR)** | Historical, parametric, and Monte Carlo VaR at multiple confidence levels | `numpy`, `scipy` | | **Portfolio Optimization** | Mean-variance optimization (Modern Portfolio Theory), efficient frontier | `cvxpy`, `scipy.optimize` | | **Risk Metrics** | Sharpe, Sortino, Calmar, max drawdown, beta, alpha, information ratio | `numpy`, `pandas` | | **Custom Python** | Arbitrary Python code execution with access to 17 libraries and FMP data | All libraries |
Full Python library list (17 packages) | Library | Version | Purpose | |---------|---------|---------| | `numpy` | latest | Numerical computing | | `pandas` | latest | Data manipulation | | `scipy` | latest | Scientific computing | | `scikit-learn` | latest | Machine learning | | `statsmodels` | latest | Statistical models | | `matplotlib` | latest | Plotting & charts | | `seaborn` | latest | Statistical visualization | | `plotly` | latest | Interactive charts | | `arch` | latest | GARCH models | | `cvxpy` | latest | Convex optimization | | `yfinance` | latest | Market data | | `ta` | latest | Technical analysis | | `quantstats` | latest | Portfolio analytics | | `beautifulsoup4` | latest | Web scraping | | `requests` | latest | HTTP client | | `lxml` | latest | XML/HTML parsing | | `Pillow` | latest | Image processing |
### Web Research Engine | Source | Capabilities | Badge | |--------|-------------|-------| | **Tavily** | AI-powered search with generated answers, time filters, domain filtering | [![Tavily](https://img.shields.io/badge/Tavily-AI_Search-4f46e5?style=flat-square)](https://tavily.com/) | | **Firecrawl** | Web scraping, PDF extraction (up to 750 pages), intelligent crawling, structured extraction, autonomous agents | [![Firecrawl](https://img.shields.io/badge/Firecrawl-Web_Extraction-f97316?style=flat-square)](https://firecrawl.dev/) | | **Exa** | Semantic neural search, content retrieval, similar page discovery | [![Exa](https://img.shields.io/badge/Exa-Semantic_Search-6366f1?style=flat-square)](https://exa.ai/) | | **SerpAPI** | Google Search, Images, Shopping, Finance, Trends, Scholar, Videos, Flights, Hotels | [![SerpAPI](https://img.shields.io/badge/SerpAPI-Google_Search-34a853?style=flat-square)](https://serpapi.com/) | ### AI Agent [![Claude](https://img.shields.io/badge/Claude_Fable_5-6_models-d97706?style=flat-square&logo=anthropic&logoColor=white)](https://anthropic.com/) | Feature | Details | |---------|---------| | **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 | | **Model Selector** | Switchable from the input bar and the welcome screen (per-model icons); selection persisted in `localStorage` | | **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) | | **Tools** | 213 specialized financial tools | | **Batching** | Intelligent tool batching (5 tools per batch with 500ms pauses) | | **Streaming** | Real-time Server-Sent Events (SSE) for instant response display | | **History** | Persistent conversation sessions with token tracking | | **Vision** | Image analysis support (charts, screenshots, documents) | | **Cost Tracking** | Per-session input/output token counting and cost estimation | ### Interface & Design | Aspect | Details | |--------|---------| | **Theme** | Modern light/dark themes with an indigo-violet accent; toggle persisted in `localStorage` | | **Design** | Rounded soft-cornered components, subtle background gradient, thin rounded scrollbars | | **Welcome screen** | Categorized example prompts + dedicated model selector with per-model icons | | **Stack** | Tailwind CSS 3.4 + Radix UI primitives | ### Export & Reports | Format | Description | Badge | |--------|-------------|-------| | **PDF** | Professional reports generated with Puppeteer, markdown rendering | [![PDF](https://img.shields.io/badge/PDF-Puppeteer-ea4335?style=flat-square&logo=googlechrome&logoColor=white)](./) | | **DOCX** | Word documents via Pandoc conversion | [![DOCX](https://img.shields.io/badge/DOCX-Pandoc-2b579a?style=flat-square&logo=microsoftword&logoColor=white)](./) | | **LaTeX Slides** | Beamer presentations with professional theming | [![LaTeX](https://img.shields.io/badge/LaTeX-Beamer_Slides-008080?style=flat-square&logo=latex&logoColor=white)](./) | | **Data Files** | CSV, XLSX, JSON, TXT downloads of analysis data | [![Data](https://img.shields.io/badge/Data-CSV_XLSX_JSON-217346?style=flat-square&logo=microsoftexcel&logoColor=white)](./) | | **Share Links** | Shareable report URLs with unique IDs | [![Share](https://img.shields.io/badge/Share-Unique_Links-0ea5e9?style=flat-square)](./) | --- ## Getting Started ### Prerequisites [![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/) [![Python](https://img.shields.io/badge/Python-3.11+-3776ab?style=flat-square&logo=python&logoColor=white)](https://python.org/) [![npm](https://img.shields.io/badge/npm-9+-cb3837?style=flat-square&logo=npm&logoColor=white)](https://npmjs.com/) ### Installation ```bash # Clone the repository git clone https://github.com/spboucher-ai/vquant.git cd vquant # Install Node.js dependencies npm install # Set up Python virtual environment python3 -m venv .venv source .venv/bin/activate # macOS/Linux # .venv\Scripts\activate # Windows pip install -r requirements-safe.txt # Configure environment variables cp .env.example .env # Edit .env with your API keys # Start development server npm run dev ``` The app will be available at `http://localhost:5000`. ### API Keys All services offer generous free tiers: | Service | Sign Up | Free Tier | Required | |---------|---------|-----------|----------| | [![Anthropic](https://img.shields.io/badge/Anthropic-d97706?style=flat-square&logo=anthropic&logoColor=white)](https://console.anthropic.com) | [console.anthropic.com](https://console.anthropic.com) | $5 credit | **Yes** | | [![FMP](https://img.shields.io/badge/FMP-0969da?style=flat-square)](https://financialmodelingprep.com) | [financialmodelingprep.com](https://financialmodelingprep.com) | 250 calls/day | **Yes** | | [![Firecrawl](https://img.shields.io/badge/Firecrawl-f97316?style=flat-square)](https://firecrawl.dev) | [firecrawl.dev](https://firecrawl.dev) | 500 credits | Recommended | | [![Tavily](https://img.shields.io/badge/Tavily-4f46e5?style=flat-square)](https://app.tavily.com) | [app.tavily.com](https://app.tavily.com) | 1000 calls/month | Recommended | | [![Exa](https://img.shields.io/badge/Exa-6366f1?style=flat-square)](https://exa.ai) | [exa.ai](https://exa.ai) | 1000 searches/month | Optional | | [![SerpAPI](https://img.shields.io/badge/SerpAPI-34a853?style=flat-square)](https://serpapi.com) | [serpapi.com](https://serpapi.com) | 100 searches/month | Optional | --- ## Scripts | Command | Description | |---------|-------------| | `npm run dev` | Start development server (Vite HMR + Express) | | `npm run build` | Build for production (client + server) | | `npm start` | Start production server | | `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) | | `npm run lint` | ESLint check | | `npm run lint:fix` | ESLint auto-fix | | `npm run format` | Prettier format all files | | `npm run format:check` | Prettier check (CI-friendly) | | `npm test` | Run all tests (Vitest) | | `npm run test:watch` | Run tests in watch mode | | `npm run test:coverage` | Run tests with coverage report | | `npm run db:push` | Push database schema changes (Drizzle Kit) | --- ## Architecture ``` vquant/ β”œβ”€β”€ client/src/ # Frontend (React + TypeScript) β”‚ β”œβ”€β”€ App.tsx # Router + providers + ErrorBoundary β”‚ β”œβ”€β”€ main.tsx # Entry point β”‚ β”œβ”€β”€ config.ts # App config, endpoints, feature flags β”‚ β”œβ”€β”€ components/ β”‚ β”‚ β”œβ”€β”€ chat/ # 13 chat-specific components β”‚ β”‚ β”‚ β”œβ”€β”€ search-bar.tsx # Query input with image support β”‚ β”‚ β”‚ β”œβ”€β”€ streaming-answer.tsx # Real-time markdown rendering β”‚ β”‚ β”‚ β”œβ”€β”€ agent-steps.tsx # Tool execution progress β”‚ β”‚ β”‚ β”œβ”€β”€ tool-results.tsx # Financial data display β”‚ β”‚ β”‚ β”œβ”€β”€ monte-carlo-results.tsx # Simulation visualizations β”‚ β”‚ β”‚ β”œβ”€β”€ share-button.tsx # Report sharing β”‚ β”‚ β”‚ β”œβ”€β”€ download-buttons.tsx # PDF/DOCX export β”‚ β”‚ β”‚ └── ... # + 6 more components β”‚ β”‚ β”œβ”€β”€ explore/ # 7 stock explorer components β”‚ β”‚ β”œβ”€β”€ financial/ # Price charts, options pricing β”‚ β”‚ β”œβ”€β”€ ui/ # 35 shadcn/ui primitives β”‚ β”‚ └── error-boundary.tsx # Global error handler β”‚ β”œβ”€β”€ hooks/ β”‚ β”‚ β”œβ”€β”€ useChatSession.ts # All chat state & business logic β”‚ β”‚ β”œβ”€β”€ useChatMutation.ts # SSE streaming client β”‚ β”‚ β”œβ”€β”€ useAnalytics.ts # Heartbeat tracking β”‚ β”‚ β”œβ”€β”€ use-toast.ts # Toast notifications β”‚ β”‚ └── use-mobile.tsx # Responsive detection β”‚ β”œβ”€β”€ pages/ # 9 route pages β”‚ β”‚ β”œβ”€β”€ home.tsx # Main chat interface (255 lines) β”‚ β”‚ β”œβ”€β”€ explore.tsx # Stock explorer β”‚ β”‚ β”œβ”€β”€ admin.tsx # Admin dashboard β”‚ β”‚ β”œβ”€β”€ auth.tsx # Login/register β”‚ β”‚ β”œβ”€β”€ showcase.tsx # Community reports β”‚ β”‚ β”œβ”€β”€ shared-report.tsx # Shared report viewer β”‚ β”‚ β”œβ”€β”€ documentation.tsx # API documentation β”‚ β”‚ └── ... # + privacy, terms, slides, 404 β”‚ β”œβ”€β”€ lib/ β”‚ β”‚ β”œβ”€β”€ queryClient.ts # TanStack Query config β”‚ β”‚ └── utils.ts # cn() + helpers β”‚ └── utils/ β”‚ β”œβ”€β”€ chartCapture.ts # Chart-to-image conversion β”‚ └── pdfGenerator.ts # Client-side PDF generation β”‚ β”œβ”€β”€ server/ # Backend (Express + TypeScript) β”‚ β”œβ”€β”€ index.ts # Server bootstrap, CORS, sessions β”‚ β”œβ”€β”€ routes.ts # /api/chat (SSE streaming) + speech-to-text β”‚ β”œβ”€β”€ routes/ β”‚ β”‚ β”œβ”€β”€ auth.ts # /api/auth/* (register, login, logout, me) β”‚ β”‚ β”œβ”€β”€ admin.ts # /api/admin/* (database, CRUD) + requireAdmin β”‚ β”‚ β”œβ”€β”€ analytics.ts # /api/analytics/* (heartbeat, active users, metrics) β”‚ β”‚ β”œβ”€β”€ fmp.ts # /api/fmp/* (23 financial data endpoints) β”‚ β”‚ β”œβ”€β”€ reports.ts # /api/share/*, sessions, PDF/DOCX/slides, download β”‚ β”‚ └── validation.ts # Zod request schemas β”‚ β”œβ”€β”€ services/ β”‚ β”‚ β”œβ”€β”€ claude/ β”‚ β”‚ β”‚ β”œβ”€β”€ toolDefinitions.ts # 213 tool definitions (4,480 lines) β”‚ β”‚ β”‚ └── tokenManagement.ts # Context window management β”‚ β”‚ β”œβ”€β”€ claudeService.ts # Claude API integration β”‚ β”‚ β”œβ”€β”€ fmpService.ts # 230 FMP API wrapper functions β”‚ β”‚ β”œβ”€β”€ python/ β”‚ β”‚ β”‚ β”œβ”€β”€ monteCarlo.ts # Monte Carlo simulation β”‚ β”‚ β”‚ β”œβ”€β”€ optionsPricing.ts # Black-Scholes pricing β”‚ β”‚ β”‚ β”œβ”€β”€ garch.ts # GARCH volatility model β”‚ β”‚ β”‚ β”œβ”€β”€ var.ts # VaR + portfolio + risk metrics β”‚ β”‚ β”‚ └── shared.ts # Python executor config β”‚ β”‚ β”œβ”€β”€ *.py # 11 Python scientific services β”‚ β”‚ β”œβ”€β”€ firecrawlService.ts # Web extraction β”‚ β”‚ β”œβ”€β”€ tavilyService.ts # AI search β”‚ β”‚ β”œβ”€β”€ exaService.ts # Semantic search β”‚ β”‚ └── serpapiService.ts # Google search β”‚ β”œβ”€β”€ db.ts # Drizzle ORM (SQLite + PostgreSQL) β”‚ β”œβ”€β”€ storage.ts # Typed data access layer β”‚ β”œβ”€β”€ types/ β”‚ β”‚ └── modules.d.ts # Module declarations β”‚ └── utils/ β”‚ └── logger.ts # Structured logging β”‚ β”œβ”€β”€ shared/ # Shared between client & server β”‚ β”œβ”€β”€ schema.ts # PostgreSQL schema (Drizzle) β”‚ β”œβ”€β”€ schema-sqlite.ts # SQLite schema (Drizzle) β”‚ └── types.ts # API interfaces (SearchResult, etc.) β”‚ β”œβ”€β”€ vitest.config.ts # Test configuration β”œβ”€β”€ eslint.config.js # ESLint flat config β”œβ”€β”€ vite.config.ts # Vite build config β”œβ”€β”€ tsconfig.json # TypeScript config β”œβ”€β”€ tailwind.config.ts # Tailwind CSS config β”œβ”€β”€ .prettierrc # Prettier config β”œβ”€β”€ .editorconfig # Editor config β”œβ”€β”€ .env.example # Environment template └── .gitignore # Git ignore rules ``` ### System Architecture ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ CLIENT (React 18) β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ Chat UI β”‚ β”‚ Explore Page β”‚ β”‚ Admin Panelβ”‚ β”‚ Auth/Docs β”‚ β”‚ β”‚ β”‚ (SSE) β”‚ β”‚ (FMP data) β”‚ β”‚ (Analytics)β”‚ β”‚ (Sessions)β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ TanStack Query + useChatSession β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ HTTP / SSE β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ SERVER (Express 4) β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ Route Modules (6) β”‚ β”‚ β”‚ β”‚ auth β”‚ admin β”‚ analytics β”‚ fmp β”‚ reports β”‚ chat (SSE) β”‚ β”‚ β”‚ β””β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”΄β”€β”€β”€β” β”Œβ”€β”΄β”€β”€β”€β”€β”€β”€β” β”Œβ”΄β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚Storageβ”‚ β”‚Analyticsβ”‚ β”‚Zod Validβ”‚ β”‚ β”‚ Claude Opus 4.8 β”‚ β”‚ β”‚ β”‚(Drizzle)β”‚ β”‚Metrics β”‚ β”‚Schemas β”‚ β”‚ β”‚ 213 tools β”‚ β”‚ β”‚ β””β”€β”€β”€β”¬β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ 5-tool batching β”‚ β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”Œβ”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚SQLite/PG β”‚ β”‚ FMP Serviceβ”‚ β”‚ Python Engine β”‚ β”‚ β”‚ β”‚(Drizzle) β”‚ β”‚ 230 funcs β”‚ β”‚ 17 libraries β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ External APIs β”‚ β”‚ β”‚ β”‚ Tavily β”‚ Firecrawl β”‚ Exa β”‚ SerpAPI β”‚ ElevenLabs β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` --- ## API Reference ### Chat (SSE Streaming) | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/api/chat` | Main AI chat with streaming (Server-Sent Events) | | `POST` | `/api/speech-to-text` | Audio transcription (ElevenLabs Scribe) | ### Authentication | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/api/auth/register` | Create account (generates unique token) | | `POST` | `/api/auth/login` | Authenticate with token | | `POST` | `/api/auth/logout` | End session | | `GET` | `/api/auth/me` | Get current user | ### Shared Reports & Sessions | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/shared-reports` | List all shared reports | | `POST` | `/api/share` | Create shareable report | | `GET` | `/api/share/:shareId` | Get shared report | | `GET` | `/api/sessions` | List user sessions | | `GET` | `/api/sessions/:id` | Get session with messages | ### Document Generation | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/api/generate-pdf` | Markdown to PDF (Puppeteer) | | `POST` | `/api/generate-docx` | Markdown to DOCX (Pandoc) | | `POST` | `/api/convert-to-slides` | Markdown to Beamer LaTeX PDF | | `GET` | `/api/download/:filename` | Download data file | ### Financial Data (FMP) | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/fmp/quote/:symbol` | Real-time stock quote | | `GET` | `/api/fmp/company-profile/:symbol` | Company profile | | `GET` | `/api/fmp/historical-price/:symbol` | Historical prices | | `GET` | `/api/fmp/intraday/:symbol` | Intraday price data | | `GET` | `/api/fmp/income-statement/:symbol` | Income statement | | `GET` | `/api/fmp/balance-sheet/:symbol` | Balance sheet | | `GET` | `/api/fmp/cash-flow/:symbol` | Cash flow statement | | `GET` | `/api/fmp/key-metrics/:symbol` | Key financial metrics | | `GET` | `/api/fmp/financial-ratios/:symbol` | Financial ratios | | `GET` | `/api/fmp/analyst-estimates/:symbol` | Analyst estimates | | `GET` | `/api/fmp/price-target/:symbol` | Price targets | | `GET` | `/api/fmp/insider-trading/:symbol` | Insider trades | | `GET` | `/api/fmp/institutional-holders/:symbol` | Institutional holders | | `GET` | `/api/fmp/earnings-surprises/:symbol` | Earnings surprises | | `GET` | `/api/fmp/dividend-history/:symbol` | Dividend history | | `GET` | `/api/fmp/esg-score/:symbol` | ESG score | | `GET` | `/api/fmp/financial-news/:symbol` | Financial news | | `GET` | `/api/fmp/upgrades-downgrades/:symbol` | Analyst upgrades/downgrades | | `GET` | `/api/fmp/gainers` | Top market gainers | | `GET` | `/api/fmp/losers` | Top market losers | | `GET` | `/api/fmp/actives` | Most active stocks | | `GET` | `/api/fmp/market-hours` | Market hours | | `GET` | `/api/fmp/chart/light/:symbol` | Lightweight chart data | ### Analytics & Admin | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/api/analytics/heartbeat` | Update user activity | | `GET` | `/api/analytics/active-users` | Active users (admin) | | `GET` | `/api/analytics/real-time-stats` | Real-time stats | | `GET` | `/api/analytics/metrics` | Historical metrics (admin) | | `POST` | `/api/admin/login` | Admin login | | `GET` | `/api/admin/database` | Full database view (admin) | | `DELETE` | `/api/admin/users/:id` | Delete user (admin) | | `DELETE` | `/api/admin/sessions/:id` | Delete session (admin) | | `DELETE` | `/api/admin/reports/:id` | Delete report (admin) | --- ## Usage Examples ### Financial Analysis ``` "Full analysis of NVDA: profile, financials, insider trades, analyst ratings, sector performance" "Compare AAPL, MSFT, GOOGL on: market cap, P/E, revenue growth, ESG scores, analyst consensus" "Due diligence on TSLA: DCF valuation, institutional holders, insider trading patterns, earnings surprises" "Show me the top gainers today with their financial ratios and analyst ratings" ``` ### Quantitative Analysis ``` "Run a Monte Carlo simulation on AAPL with 10,000 paths over 252 trading days" "Calculate the correlation matrix of FAANG stocks and display a heatmap" "Backtest an RSI strategy on SPY and show the equity curve with Sharpe ratio" "Optimize a portfolio of AAPL, MSFT, GOOGL, AMZN for maximum Sharpe ratio" "Calculate Value at Risk for a $100,000 NVDA position at 95% and 99% confidence" "Estimate GARCH volatility for TSLA and forecast 30-day ahead volatility" "Price a call option on AAPL with strike $200, 30 days to expiry, and show all Greeks" ``` ### Web Research ``` "Search latest AI industry news this week and summarize key developments" "Extract the last NVIDIA earnings call transcript and highlight guidance changes" "Research the impact of Fed rate decisions on tech stocks in 2024-2025" "Crawl investor.nvidia.com and extract all Q4 financial press releases" ``` --- ## Documentation Exhaustive documentation is available in the [`docs/`](./docs) directory: | Document | Description | |----------|-------------| | **[Getting Started](./docs/GETTING_STARTED.md)** | Prerequisites, installation, Python setup, env vars, first run, troubleshooting | | **[Architecture](./docs/ARCHITECTURE.md)** | System diagram, directory structure, data flow, design decisions | | **[API Reference](./docs/API_REFERENCE.md)** | All 44 endpoints with request/response schemas, SSE event types, query params | | **[Python Analysis](./docs/PYTHON_ANALYSIS.md)** | 8 built-in models (Monte Carlo, Black-Scholes, GARCH, VaR, portfolio, risk, plots, custom), all 17 libraries | | **[Database Schema](./docs/DATABASE.md)** | All 9 tables with columns, types, constraints, relationships | | **[Deployment](./docs/DEPLOYMENT.md)** | Production build, env vars, Docker example, CORS, security checklist | | **[Contributing](./docs/CONTRIBUTING.md)** | Dev setup, code conventions, commit format, how to add endpoints/tools | | **[`.env.example`](./.env.example)** | All environment variables with categories | --- ## Testing [![Tests](https://img.shields.io/badge/Tests-41_passing-22c55e?style=flat-square&logo=vitest&logoColor=white)](./) [![Vitest](https://img.shields.io/badge/Framework-Vitest_4-6e9f18?style=flat-square)](./) [![Duration](https://img.shields.io/badge/Duration-<1s-22c55e?style=flat-square)](./) | Suite | Tests | What it covers | |-------|-------|---------------| | `App.test.tsx` | 3 | Smoke test: renders, shows home page, search bar present | | `config.test.ts` | 5 | App config: name, domain, endpoints, limits, feature flags | | `utils.test.ts` | 5 | `cn()`: class merging, conditionals, dedup, edge cases | | `queryClient.test.ts` | 6 | Query defaults: staleTime, gcTime, retry, refetch policy | | `useChatSession.test.tsx` | 6 | Hook: initial state, reset, history toggle, mutation shape, handlers | | `validation.test.ts` | 16 | All Zod schemas: valid/invalid inputs, missing fields, max lengths | ```bash npm test # Run once npm run test:watch # Watch mode npm run test:coverage # With coverage ``` --- ## Deployment ### Production Build ```bash npm run build # Builds client (Vite) + server (esbuild) npm start # Starts production server ``` ### Environment Variables ```bash # Required NODE_ENV=production PORT=5000 SESSION_SECRET= ANTHROPIC_API_KEY=sk-ant-... FINANCIAL_MODELING_PREP_API_KEY=... # Database (default: SQLite) DATABASE_URL=sqlite://local.db # DATABASE_URL=postgresql://user:pass@host:5432/db # Optional APIs FIRECRAWL_API_KEY=fc-... TAVILY_API_KEY=tvly-... EXA_API_KEY=... SERPAPI_API_KEY=... ``` --- ## Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/my-feature`) 3. Run checks before committing: ```bash npm run typecheck && npm run lint && npm test ``` 4. Commit with a descriptive message 5. Open a Pull Request ### Code Conventions | Rule | Enforced By | |------|------------| | TypeScript `strict` mode | `tsconfig.json` | | ESLint (typescript-eslint + react-hooks) | `eslint.config.js` | | Prettier formatting | `.prettierrc` | | Zod validation on all API inputs | `server/routes/validation.ts` | | `logger` instead of `console.log` | ESLint `no-console` rule | | `@/` path alias (client), `@shared/` (shared) | `tsconfig.json` + `vite.config.ts` | | Components grouped by domain | `components/chat/`, `components/explore/`, etc. | | One hook per concern | `useChatSession`, `useChatMutation`, etc. | --- ## Authors
Simon-Pierre Boucher
Creator & Lead Developer



 Claude Opus 4.8
AI Pair Programmer
> 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). --- ## Acknowledgments [![Anthropic](https://img.shields.io/badge/Anthropic-Claude_AI-d97706?style=flat-square&logo=anthropic&logoColor=white)](https://anthropic.com/) [![FMP](https://img.shields.io/badge/Financial_Modeling_Prep-Financial_Data-0969da?style=flat-square)](https://financialmodelingprep.com/) [![Firecrawl](https://img.shields.io/badge/Firecrawl-Web_Extraction-f97316?style=flat-square)](https://firecrawl.dev/) [![Tavily](https://img.shields.io/badge/Tavily-AI_Search-4f46e5?style=flat-square)](https://tavily.com/) [![Exa](https://img.shields.io/badge/Exa-Semantic_Search-6366f1?style=flat-square)](https://exa.ai/) [![Radix UI](https://img.shields.io/badge/Radix_UI-Components-161618?style=flat-square)](https://radix-ui.com/) [![shadcn/ui](https://img.shields.io/badge/shadcn/ui-Design_System-000000?style=flat-square)](https://ui.shadcn.com/) [![Recharts](https://img.shields.io/badge/Recharts-Charts-22b5bf?style=flat-square)](https://recharts.org/) --- ## License [![MIT License](https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge)](./LICENSE) ---

[![Website](https://img.shields.io/badge/www.vquant.ai-Visit_Live_Platform-00c853?style=for-the-badge&logo=googlechrome&logoColor=white)](https://www.vquant.ai)
*Where AI Meets Institutional-Grade Financial Analysis*
**Built with**   [![TypeScript](https://img.shields.io/badge/-TypeScript-3178c6?style=flat-square&logo=typescript&logoColor=white)](./) [![React](https://img.shields.io/badge/-React-61dafb?style=flat-square&logo=react&logoColor=black)](./) [![Claude](https://img.shields.io/badge/-Claude_AI-d97706?style=flat-square&logo=anthropic&logoColor=white)](./) [![Python](https://img.shields.io/badge/-Python-3776ab?style=flat-square&logo=python&logoColor=white)](./) [![Vite](https://img.shields.io/badge/-Vite-646cff?style=flat-square&logo=vite&logoColor=white)](./) [![Tailwind](https://img.shields.io/badge/-Tailwind-06b6d4?style=flat-square&logo=tailwindcss&logoColor=white)](./)