README.md

metadata

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

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

---

🏗️ 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

# 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

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.