---
title: QuantAgent OS - Autonomous Quant Trading & Self-Improving Alpha Discovery
emoji: 📈
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 4.42.0
app_file: app.py
pinned: false
license: mit
---

# 🏛️ QuantAgent OS: Autonomous Quantitative Trading System
### *Self-Improving Multi-Agent Quantitative Architecture based on arXiv:2402.03755*

![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)
![Gradio](https://img.shields.io/badge/Gradio-4.42.0-orange.svg)
![arXiv](https://img.shields.io/badge/arXiv-2402.03755-b31b1b.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

QuantAgent OS is an institutional-grade, self-improving quantitative investment system powered by agentic AI. It implements the two-layer loop architecture pioneered in the research paper:

> **QuantAgent: Seeking Holy Grail in Trading by Self-Improving Large Language Model**  
> *Saizhuo Wang, Hang Yuan, Lionel M. Ni, Jian Guo (HKUST & IDEA Research)*  
> [arXiv:2402.03755](https://arxiv.org/abs/2402.03755)

---

## 🏗️ System Architecture

QuantAgent OS solves the core bottleneck of domain-specific financial AI: **how to autonomously discover, test, and accumulate quantitative trading signals (alphas) without manual human data curation.**

```
                           +---------------------------------------+
                           |           Outer Feedback Loop         |
                           |  (Slow / Real-World Backtest Oracle)  |
                           +---------------------------------------+
                                        |                   ^
                         Submit Alpha   |                   | Ground-truth Metrics
                         for Backtest   v                   | & Qualitative Review
                           +--------------------+           |
                           |  Real Environment  |-----------+
                           |  (Backtesting Eng) |
                           +--------------------+
                                        |
                          Updates KB    v
+---------------------------------------------------------------------------------+
|                        Inner Reasoning Loop (Fast Simulation)                   |
|                                                                                 |
|       +------------------------------------------------------------------+      |
|       |                     Shared Context Buffer (ctx)                  |      |
|       +------------------------------------------------------------------+      |
|             |                     ^                 |              ^            |
|   1. Query  | 2. Writer Hint      | 3. Generated    | 4. Judge     | 5. Review  |
|             v                     |    Alpha Code   v    Hint      |    & Score |
|      +---------------+    +---------------+    +---------------+   |            |
|      | KnowledgeBase |    |  Writer LLM   |    |   Judge LLM   |---+            |
|      |     (KB)      |    +---------------+    +---------------+                |
|      +---------------+                                                          |
+---------------------------------------------------------------------------------+
```

### 1. The Inner Reasoning Loop (Fast Heuristic Simulation)
- **Shared Context Buffer**: Holds task descriptions, retrieved knowledge hints, generated factor code, and mentor feedback.
- **Quant Alpha Writer**: Translates qualitative trading ideas into vectorized, lookahead-free Python factor code inheriting from the standardized `Factor` base class.
- **Quant Mentor Judge**: Evaluates candidate signals against 6 quantitative criteria:
  1. *Vectorization efficiency* (no single-asset Python loops)
  2. *Lookahead bias prevention* (no `shift(-1)` or future leakage)
  3. *Continuous nuance* (smooth tanh / z-score scaling into `[-1.0, 1.0]`)
  4. *Numerical stability* (`.clip()`, `.fillna()`, zero-division protection)
  5. *Code validity*
  6. *Economic intuition alignment*
- **Iterative Dialogue**: The Writer and Judge iterate for up to $T$ rounds until the candidate meets approval score $\beta$.

### 2. The Outer Feedback Loop (Real Backtesting Oracle)
- Submits the approved alpha code to the vectorized backtesting engine against historical market cross-sections.
- Calculates empirical metrics:
  - **Information Coefficient (IC)**: Cross-sectional Pearson correlation between signal and forward returns.
  - **IC Information Ratio (IC_IR)**: $\text{Mean}(IC) / \text{Std}(IC)$.
  - **Long-Short Sharpe Ratio, Max Drawdown, and Turnover Rate**.
- **Autonomous Knowledge Base (KB)**: Retains both successful and failed alphas (with failure diagnosis) to enable *pessimistic value updates*.

### 3. Downstream XGBoost Alpha Ensemble (Paper Figure 5)
- Automatically pools all valid alphas from the KB as feature columns.
- Trains an XGBoost cross-validated non-linear regression model to predict cross-sectional asset returns, demonstrating how prediction Mean Squared Error (MSE) monotonically decreases as the KB accumulates more diverse alphas.

---

## 🌐 Free Public Data Sources Integrated

| Source | Description | Authentication |
| :--- | :--- | :--- |
| **Yahoo Finance** | Live & historical OHLCV, volume, dividends, valuation metrics, beta, market cap | 100% Free (Built-in browser session) |
| **SEC EDGAR API** | Official regulatory 10-K and 10-Q XBRL financial facts: Revenue, Net Income, Total Assets, Liabilities, Debt/Equity | 100% Free (Official SEC endpoint) |
| **FRED / Market Proxies** | 10Y Treasury, 3M T-bill, Yield Curve Slope, VIX Volatility Index, Crude Oil, USD Index | 100% Free (FRED key optional) |
| **Yahoo RSS & Finnhub** | Live news headlines, company announcements, financial sentiment polarity scoring | 100% Free (Finnhub key optional) |

---

## 🚀 How to Run Locally

```bash
# 1. Clone the repository
git clone https://github.com/your-username/quantagent-os.git
cd quantagent-os

# 2. Install dependencies
pip install -r requirements.txt

# 3. Launch the application
python app.py
```
Open your browser at `http://localhost:7860` to access the interactive dashboard.

---

## ☁️ Deploying to Hugging Face Spaces

You can deploy this Space in one of two ways:

### Method 1: Directly from the Web UI (Tab 6)
1. Open the application locally or on your server.
2. Navigate to **Tab 6: Hugging Face Deployment & Settings**.
3. Enter your Hugging Face API Token (with `write` permission) and target Space ID (`username/quantagent-os`).
4. Click **Deploy to Hugging Face Spaces**.

### Method 2: Via Git
```bash
git remote add space https://huggingface.co/spaces/your-username/quantagent-os
git push space main
```

---

## 📐 Mathematical Formulation & Regret Guarantees

The framework formulates alpha mining as an Information-State Markov Decision Process $(S, A, \mathcal{T}, r, \gamma)$:
- **Inner Loop**: Under implicit Bayesian inference by the LLM (Assumption 4.1), Bayesian regret is sublinear in inner iterations $T$.
- **Outer Loop**: Grounded in Pessimistic Value Iteration (PEVI, Jin et al. 2021), epistemic uncertainty between simulated KB and real-world environment decays with outer iterations $K$.
- **Overall Regret**: Total Bayesian regret $R(TK)$ decomposes into four bounded terms and is proven **sublinear in $KT$** (Theorem 4.6).

---

## ⚖️ License
Released under the MIT License. Educational and quantitative research use only.