spb/wp13_uqo

1% ============================================================================2\section{System Architecture and Data Layer}3\label{sec:architecture}4% ============================================================================56This section describes VQuant's architecture, the data it consumes, and the external services7it integrates. We treat the architecture as the ``setting'' of the paper: the methodology of8Section~\ref{sec:methodology} is a set of algorithms that run \emph{within} the structure9described here.1011\subsection{Overview}12\label{subsec:overview}1314VQuant is a full-stack TypeScript monorepo comprising three cooperating tiers15(Figure~\ref{fig:architecture}). A \textbf{React front end} renders a conversational interface16and streams results to the user as they are produced. A \textbf{modular Express back end}17orchestrates the LLM, executes tool calls, manages context and authentication, and persists18sessions. An \textbf{isolated Python layer} performs numerical computation in a sandboxed19subprocess. The three tiers communicate over HTTP, with the client--server channel using20Server-Sent Events (SSE) to stream incremental output. The data layer is abstracted through an21object-relational mapper that targets SQLite in development and PostgreSQL in production behind22a single typed access interface, so that storage logic is identical across environments.2324\input{figures/architecture}2526\subsection{The front end}27\label{subsec:frontend}2829The client is a single-page application. Its central abstraction is a session hook that owns30the full conversational state---the streaming answer, the model's intermediate reasoning, the31ordered list of tool invocations, retrieved sources, generated figures, and the results of32specialized computations such as Monte Carlo simulations and option-pricing tables. A companion33mutation hook manages the SSE connection: it issues the request, reads the byte stream, decodes34discrete events, and dispatches each to the appropriate state setter. Because state updates are35event-driven, the interface renders the agent's behavior \emph{as it happens}---text appears36token by token, tool calls populate a progress indicator, reasoning expands in a collapsible37panel, and figures materialize as the Python layer emits them. This streaming design is central38to the user experience and is discussed further in Section~\ref{sec:evaluation}.3940\subsection{The back end}41\label{subsec:backend}4243The server is organized into route modules (authentication, administration, analytics,44market-data proxying, report management, and the chat stream) and a set of isolated services45that encapsulate business logic. The most important service mediates all communication with the46LLM: it assembles the system prompt and tool catalogue, enforces the token budget, opens the47streaming connection, parses the provider's event stream, dispatches tool calls, and relays48results back to the client. Document generation, web research, and the quantitative-method49wrappers are each implemented as separate services, so that the orchestration logic remains50decoupled from the mechanics of any single capability. All request bodies are validated against51schemas at the boundary, eliminating untyped inputs and yielding uniform error handling.5253\subsection{The data layer and external integrations}54\label{subsec:data}5556VQuant is grounded in live data; it stores essentially no market data itself. Its primary57financial source is a commercial market-data provider exposing more than 265 endpoints, wrapped58by roughly 230 typed functions on the server and mirrored by a Python client used inside the59sandbox. These endpoints cover company fundamentals (income statements, balance sheets, cash60flows, key metrics and ratios), market data (real-time and historical quotes, intraday series,61market movers), technical indicators (RSI, MACD, moving averages, ADX, stochastics, and62others), analyst data (estimates, price targets, upgrades and downgrades, rating histories),63insider and institutional activity (insider transactions, 13F filings, congressional and64senate trading), macroeconomic series (treasury rates, economic indicators, the economic65calendar, COT reports), foreign exchange and commodities, SEC filings and earnings-call66transcripts, corporate events (earnings, dividends, splits, IPOs), and ESG and alternative-data67signals. Table~\ref{tab:tools} in Section~\ref{sec:methodology} summarizes the resulting tool68taxonomy.6970Beyond structured financial data, VQuant integrates four complementary web-research services---a71web-scraping and extraction service, an AI search service, a neural semantic-search service, and72a general search-engine API---so that the agent can incorporate qualitative and breaking73information that no structured endpoint captures. The persistence layer stores users (with74optional encrypted custom API keys), conversation sessions (including token accounting and cost75estimates), shared reports addressable by a unique public identifier, daily-usage counters, and76analytics events. This schema supports the platform's authentication, rate-limiting,77report-sharing, and observability features, which we revisit in Section~\ref{sec:evaluation}.7879\subsection{Model layer}80\label{subsec:models}8182VQuant is model-agnostic within the Claude family and exposes a user-facing selector83(Table~\ref{tab:models}). The default is a reasoning-augmented model with a very large context84window; users may instead select higher-capability or lower-latency alternatives to trade off85quality, speed, and cost per query. The orchestration service detects which models support86adaptive extended thinking and enables it only for those, so that the same code path serves the87full model range. This abstraction is what allows the methodology of the next section to be88stated independently of any particular model.8990\input{tables/models}91