---
title: Quant AI - Advanced Quant Trading Engine & Backtest Simulator
emoji: 📈
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# 📈 Quant.ai — Institutional Alpha Research & Live/Paper Trading Platform

<p align="center">
  <a href="https://huggingface.co/spaces/Ypeng12/quant-ai" target="_blank">
    <img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Live%20Demo-FFD21E.svg?style=for-the-badge&logo=huggingface&logoColor=black" alt="Hugging Face Space" />
  </a>
  <a href="https://github.com/ypeng12/Quant.ai" target="_blank">
    <img src="https://img.shields.io/badge/GitHub-Quant.ai-181717.svg?style=for-the-badge&logo=github&logoColor=white" alt="GitHub Repository" />
  </a>
  <img src="https://img.shields.io/badge/Python-3.9%2B-3776AB.svg?style=for-the-badge&logo=python&logoColor=white" alt="Python Version" />
  <img src="https://img.shields.io/badge/FastAPI-v0.95%2B-009688.svg?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI" />
  <img src="https://img.shields.io/badge/Alpaca-Paper%20%26%20Live-F58220.svg?style=for-the-badge&logo=alpaca&logoColor=white" alt="Alpaca Trading" />
  <img src="https://img.shields.io/badge/Docker-Ready-2496ED.svg?style=for-the-badge&logo=docker&logoColor=white" alt="Docker Ready" />
</p>

> 🚀 **Interactive Terminal Demo**: Experience the deployed terminal live on Hugging Face Spaces 👉 **[huggingface.co/spaces/Ypeng12/quant-ai](https://huggingface.co/spaces/Ypeng12/quant-ai)**

**Quant.ai** is an end-to-end, **Point-in-Time Consistent Quantitative Trading & Paper/Live Execution Platform**. Designed following Hudson River Trading (HRT) and Quantitative Hedge Fund engineering standards, it bridges the gap between **rigorous signal research**, **microstructure execution**, and **real-time broker integration (Alpaca API)**.

---

## 🔥 Key Platform Highlights

### ⚡ 1. Real-Time Live & Paper Trading (Alpaca Integration)
* **Direct Broker Connectivity**: Seamless REST & WebSocket integration with **Alpaca Markets** for real-time order routing, position tracking, and market streaming.
* **Paper & Live Mode Switch**: Flexible environment toggling (`https://paper-api.alpaca.markets` for risk-free simulation vs. live brokerage execution).
* **Execution Algorithmic Suite**: Smart order routing with TWAP, VWAP, and Implementation Shortfall (IS) execution algorithms.
* **Dynamic Portfolio Risk Controls**:
  * Real-time position tracking and ledger recording.
  * Trailing stop-loss triggers and volatility-based position sizing.
  * Drawdown-contingent risk multipliers & consecutive loss protections.

### 🔬 2. HRT-Standard Alpha Research Engine
* **Point-in-Time Data Hygiene**: Strict timestamp truncation at date $t$ to eliminate lookahead bias across U.S. Equity & ETF universes.
* **Purged Walk-Forward Cross Validation + Embargo**: Eliminates overlap leakage across rolling 3-year train / 6-month validation / 6-month OOS test windows with a 5-day embargo.
* **Novel Risk-Adjusted Signals**:
  * **Sortino Momentum**: $\text{Return}_{20d} / \text{DownsideVol}_{20d}$
  * **Residual Momentum**: 60-day rolling OLS stripping `SPY` Market Beta: $R_i(\tau) = \alpha_i + \beta_i R_{\text{SPY}}(\tau) + \epsilon_i(\tau)$
  * **Robust Z-Score Normalization**: Cross-sectional Median/MAD standardization.
* **Multiple Testing Correction**: Deflated Sharpe Ratio (DSR) and Stationary Bootstrap 95% Confidence Intervals.

### 📊 3. Microstructure & Orderbook Engine
* **Order Flow Imbalance (OFI)**: Real-time L2/L3 orderbook imbalance calculation for high-frequency price impact prediction.
* **Friction & Shortfall Modeling**: Multi-tiered transaction cost models with 2–15 bps slippage sensitivity checks.
* **Low-Latency Engine Core**: C++ accelerated order matching engine headers (`orderbook.hpp`).

### 🤖 4. Natural Language Alpha Hypothesis Parser
* LLM-assisted hypothesis compilation translating natural language ideas into validated, executable Pydantic model configurations.

---

## 🎯 Core Research Hypothesis

> **"Can volatility-adjusted and market-beta-residualized cross-sectional momentum signals across liquid U.S. ETFs predict short-term excess returns after transaction costs and execution friction?"**

---

## ⚡ Quick Start & Setup

### 1. Clone & Install Dependencies
```bash
git clone https://github.com/ypeng12/Quant.ai.git
cd Quant.ai

# Install Python requirements
pip install -r requirements.txt
```

### 2. Configure Environment & Alpaca Credentials
Create a `.env` file in the project root:
```env
# Alpaca Broker Credentials (Use Paper Trading for risk-free testing)
ALPACA_API_KEY=your_alpaca_paper_key
ALPACA_SECRET_KEY=your_alpaca_paper_secret
ALPACA_BASE_URL=https://paper-api.alpaca.markets

# Server Configuration
PORT=7860
```

### 3. Run Unit Tests (Zero Future Leakage Verification)
```bash
python -m pytest tests/ -v
```

### 4. Execute Out-of-Sample Alpha Experiment (`make oos`)
```bash
python run_experiment.py
```

Outputs:
```text
================================================================================
  QUANT.AI OUT-OF-SAMPLE EXPERIMENT RUNNER
  Hypothesis: Volatility-Adjusted Momentum across Liquid U.S. ETFs
  Lookback: 20d | Holding: 5d | Transaction Cost: 5.0 bps
================================================================================
  --> Raw_Momentum_Baseline        | OOS Rank IC: -0.0182 | Net Sharpe: 0.33 | MaxDD: -55.2%
  --> Vol_Adj_Momentum_Baseline    | OOS Rank IC: -0.0196 | Net Sharpe: 0.33 | MaxDD: -59.4%
  --> Ridge_Linear                 | OOS Rank IC:  0.0102 | Net Sharpe: 1.58 | MaxDD: -23.5%
```

### 5. Launch Local Dashboard / FastAPI Backend
```bash
# Launch FastAPI Backend
uvicorn backend.app.main:app --host 0.0.0.0 --port 7860 --reload
```
Navigate to `http://localhost:7860` in your browser.

---

## 📁 Repository Architecture

```text
Quant.ai/
├── .github/
│   └── workflows/
│       └── sync_to_hf.yml        # CI/CD GitHub Action auto-syncing to Hugging Face
├── backend/
│   └── app/
│       ├── trading_engine.py     # Live/Paper Trading Engine & Portfolio Risk Control
│       ├── simulator.py          # Execution Simulator & Implementation Shortfall Model
│       ├── orderbook_ofi.py      # Microstructure Order Flow Imbalance (OFI) Engine
│       ├── execution_algo.py     # TWAP / VWAP Order Execution Algorithms
│       ├── low_latency_engine.py # High-Frequency Matching Engine Adapter
│       └── cpp_engine/           # C++ Orderbook & Level-2 Matching Headers
├── frontend/                     # React / TypeScript Institutional Dashboard UI
├── src/
│   ├── data/
│   ├── features/
│   ├── labels/
│   ├── validation/
│   ├── models/
│   └── portfolio/
├── tests/                        # Zero Future Leak & Purged CV Unit Tests
├── Dockerfile                    # Hugging Face Space Docker Deployment spec
├── run_experiment.py             # One-command OOS research executable
└── requirements.txt              # Production Python dependencies
```

---

## 🔄 CI/CD & Hugging Face Auto-Sync Workflow

This repository features automated **GitHub Actions CI/CD** (`.github/workflows/sync_to_hf.yml`). 

Whenever changes are merged into the `main` branch, GitHub automatically mirrors and deploys the latest codebase directly to the [Hugging Face Space](https://huggingface.co/spaces/Ypeng12/quant-ai), guaranteeing 24/7 live deployment without manual intervention.

---

## 🤝 Collaborative Development & Branching Model

To ensure platform stability:
* **Feature Branches**: Developers work on dedicated feature branches (e.g. `ypeng12`, `lxc`).
* **Pull Requests (PR)**: Code is tested locally and submitted via PRs to `main`.
* **Deployment Trigger**: Merging to `main` automatically triggers Hugging Face live deployment.

---

<p align="center">
  <i>Developed with ❤️ for Quantitative Finance, Machine Learning, and Automated Execution Research.</i>
</p>