README.md

---
license: mit
tags:
- quant-trading
- alpha-model
- portfolio-optimization
- volatility-forecasting
- sentiment-analysis
- machine-learning
- financial-ai
- k2-think-v2
- multi-market
- cross-asset
language:
- en
---

# AlphaForge v3.1 — Multi-Market Institutional-Grade Quantitative Trading System

> **A research-backed, modular, institutional-grade quantitative trading framework supporting 9 global markets.**
> 
> Built for the [Build with K2 Think V2 Challenge](https://build.k2think.ai/) by MBZUAI.

---

## 🚀 Quick Start

```bash
git clone https://huggingface.co/Premchan369/alphaforge-quant-system
pip install -r requirements.txt
python main.py --mode full --tickers SPY QQQ AAPL
```

---

## 📊 Live Demo

**[AlphaForge x K2 Think V2 — Interactive Gradio Space](https://huggingface.co/spaces/Premchan369/alphaforge-k2think)**

Features: real-time multi-market analysis (US, UK, DE, JP, CN, IN, Crypto, Forex, Commodities), AI deep analysis, cross-market portfolio optimization, and direct AI chat.

---

## 🌍 Multi-Market Coverage

| Market | Suffix | Examples | Currency | Session |
|--------|--------|----------|----------|---------|
| 🇺🇸 **US Equities** | (none) | AAPL, TSLA, SPY, NVDA | USD | 09:30-16:00 ET |
| 🇬🇧 **UK Equities** | .L | SHEL.L, ULVR.L, AZN.L | GBP | 08:00-16:30 GMT |
| 🇩🇪 **Germany Equities** | .DE | SAP.DE, SIE.DE, ALV.DE | EUR | 09:00-17:30 CET |
| 🇯🇵 **Japan Equities** | .T | 7203.T, 9984.T, 6758.T | JPY | 09:00-15:00 JST |
| 🇨🇳 **China Equities** | .SS/.SZ | 600519.SS, 000858.SZ | CNY | 09:30-15:00 CST |
| 🇮🇳 **India Equities** | .NS | RELIANCE.NS, TCS.NS, INFY.NS | INR | 09:15-15:30 IST |
| ₿ **Crypto** | -USD | BTC-USD, ETH-USD, SOL-USD | USD | 24/7 |
| 💱 **Forex** | =X | EURUSD=X, GBPUSD=X, USDJPY=X | USD | 24/5 |
| 🛢 **Commodities** | =F | GC=F, CL=F, SI=F | USD | 08:20-13:30 ET |

### Cross-Market Portfolio Optimization
The system supports **mixed-asset portfolios** across all markets simultaneously:

```
Example: AAPL (US) + BTC-USD (Crypto) + EURUSD=X (Forex) + GC=F (Commodities) + SHEL.L (UK)
```

Auto-detection of market from symbol suffixes enables seamless multi-asset analysis.

---

## 🧠 What This Project Is

**AlphaForge** is an institutional-grade quantitative trading system built as a modular open-source Python framework. It was created to:

- Predict multi-asset expected returns (μ) across **9 global markets**
- Analyze financial sentiment via FinBERT and LLM embeddings
- Forecast volatility (σ) and covariance matrices (Σ)
- Optimize **cross-market portfolios** with real-world constraints
- Price options with ML (beating Black-Scholes)
- Run **honest** backtests with walk-forward validation
- Control drawdowns with CPPI and Kelly criterion
- Guard against data snooping bias
- Detect market regimes and adapt strategies
- Measure liquidity risk and position capacity
- Model transaction costs with market impact

---

## 🏗 Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    MULTI-MARKET DATA LAYER                     │
│  US │ UK │ DE │ JP │ CN │ IN │ Crypto │ Forex │ Commodities │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MARKET-SPECIFIC NORMALIZATION                 │
│  Suffix handling │ Currency │ Session timing │ Local holidays   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    UNIFIED ANALYSIS PIPELINE                    │
│  Technical Indicators │ Regime Detection │ Risk Metrics       │
│  Position Sizing │ Liquidity Analysis │ Event Calendar          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CROSS-MARKET PORTFOLIO                        │
│  Auto-detect market │ Mixed-asset optimization │ Tx cost model │
└─────────────────────────────────────────────────────────────────┘
```

---

## 📁 Module Overview (33+ Modules)

| Module | Purpose | Research Basis |
|--------|---------|--------------|
| `market_data.py` | Multi-market OHLCV fetching with suffix normalization | Standard TA |
| `sentiment_model.py` | FinBERT / LLM embeddings for financial sentiment | Yang et al. 2020 (FinBERT) |
| `alpha_model.py` | XGBoost + LSTM expected return prediction | Gu et al. 2020 |
| `volatility_model.py` | GARCH baseline + LSTM volatility forecasting | Michankow 2025 |
| `portfolio_optimizer.py` | Mean-variance with constraints, Black-Litterman | Markowitz 1952 |
| `options_model.py` | ML option pricing (5-layer FNN beats BS) | Berger et al. 2023 |
| `backtest_engine.py` | Honest backtesting with transaction costs | Lopez de Prado 2018 |
| `walk_forward_validation.py` | Expanding/sliding/purged/CPCV splits | Lopez de Prado 2018/2019 |
| `wavelet_denoising.py` | Wavelet noise reduction for time series | Lopez Gil 2024 |
| `alpha_mining.py` | Genetic programming + LLM-driven factor discovery | gplearn |
| `multi_task_learning.py` | Joint optimization: alpha + vol + portfolio | Ong & Herremans 2023 |
| `execution_algorithms.py` | TWAP, VWAP, Smart Order Router, Almgren-Chriss | Almgren & Chriss 2001 |
| `risk_management.py` | VaR/CVaR (hist/parametric/MC), stress tests | Jorion 2006 |
| `market_microstructure.py` | Kyle's lambda, VPIN, Roll measure, OFI, Amihud | Kyle 1985 |
| `hyperparameter_sweep.py` | Grid, random, Latin Hypercube sampling | Bergstra & Bengio 2012 |
| `gpu_optimization.py` | Flash Attention, AMP, gradient checkpointing | PyTorch best practices |
| `rl_execution.py` | PPO-based Deep Hedging optimal execution | Buehler et al. 2019 |
| `limit_order_book.py` | Level 2 LOB reconstruction, synthetic message feeds | Gould et al. 2013 |
| `market_making.py` | Avellaneda-Stoikov quoting, adverse selection | Avellaneda & Stoikov 2008 |
| `synthetic_market_sim.py` | Agent-based modeling, regime switching | LeBaron 2006 |
| `online_learning.py` | Per-symbol adaptive models, concept drift | Gama et al. 2014 |
| `stat_arb.py` | Cointegration, PCA mean-reversion, lead-lag | Gatev et al. 2006 |
| `conformal_prediction.py` | Distribution-free prediction intervals | Shafer & Vovk 2008 |
| `feature_store.py` | Microsecond feature computation, per-feature drift | Feature Store best practices |
| `adversarial_defense.py` | FGSM attacks, model watermarking, evasion monitoring | Goodfellow et al. 2015 |
| `ab_testing.py` | Sequential testing, multiple comparison correction | Johari et al. 2022 |
| `correlation_regime.py` | DCC-GARCH dynamic correlations, Ledoit-Wolf shrinkage | Engle 2002 |
| `news_data_integration.py` | NewsAPI, RSS, GDELT, Reddit/StockTwits aggregation | Alternative data |
| `regime_detection.py` | HMM/GMM market regime classifier, regime-conditioned Sharpe | Hamilton 1989 |
| `transaction_cost_model.py` | Square-root market impact, spread, fees, optimal participation | Almgren et al. 2005 |
| `drawdown_control.py` | CPPI insurance, fractional Kelly, dynamic leverage | Perold & Sharpe 1988 |
| `liquidity_risk.py` | Amihud illiquidity, Kyle's lambda, VPIN, position capacity | Amihud 2002 |
| `data_snooping_guard.py` | White's Reality Check, FDR, Bonferroni/Holm | White 2000 |
| `event_study.py` | Post-earnings drift, macro events, merger arbitrage | MacKinlay 1997 |
| `cross_sectional_factors.py` | Fama-French 5-factor, momentum, quality, low-vol | Fama & French 2015 |
| `factor_risk_model.py` | Barra-style multi-factor risk decomposition | Grinold & Kahn 2000 |

---

## 📈 Key Metrics & Scoring

| Metric | Description | Target |
|--------|-------------|--------|
| **Sharpe Ratio** | Risk-adjusted return | > 1.0 |
| **Sortino Ratio** | Downside risk-adjusted return | > 1.5 |
| **Information Coefficient (IC)** | Predicted vs actual return correlation | > 0.05 |
| **Max Drawdown** | Worst peak-to-trough decline | < -20% |
| **VaR (95%)** | Value at Risk | Reported |
| **CVaR (95%)** | Conditional VaR / Expected Shortfall | Reported |
| **Calmar Ratio** | Return / Max Drawdown | > 1.0 |
| **Win Rate** | % of positive return days | Reported |
| **Profit Factor** | Gross profit / Gross loss | > 1.2 |
| **GOAT Score** | Composite 0-100 scoring system | > 70 |
| **Regime-Conditioned Sharpe** | Sharpe in current market regime | Contextual |
| **Transaction Cost Drag** | Annualized cost of trading | < 2% |
| **Liquidity Score** | Amihud illiquidity ranking | Reported |
| **Kelly Fraction** | Optimal leverage for growth | < 1.0 (practical) |

---

## 📚 Research Foundation

Every major component is backed by published research:

| Component | Citation | Key Finding |
|-----------|----------|-------------|
| Wavelet Denoising | Lopez Gil 2024 (xLSTM-TS) | `db4` + soft thresholding |
| Multi-Task Learning | Ong & Herremans 2023 (MTL-TSMOM) | Joint MTL with negative Sharpe loss |
| Walk-Forward Validation | Lopez de Prado 2018/2019 | Purged CV + combinatorial CPCV |
| Options Pricing | Berger et al. 2023 | 5-layer FNN beats Black-Scholes |
| Volatility | Michankow 2025 | Skewed Student's t LSTM |
| RL Execution | Buehler et al. 2019 | Deep Hedging (PPO) |
| Market Making | Avellaneda & Stoikov 2008 | Inventory management |
| Correlation Regimes | Engle 2002 | DCC-GARCH dynamic correlations |
| Regime Detection | Hamilton 1989 | HMM for nonstationary time series |
| Transaction Costs | Almgren et al. 2005 | Square-root market impact law |
| Drawdown Control | Perold & Sharpe 1988 | CPPI dynamic asset allocation |
| Kelly Criterion | Thorp 2006 | Fractional Kelly for practical trading |
| Liquidity Risk | Amihud 2002 | Illiquidity premium via price impact ratio |
| Data Snooping | White 2000 | Bootstrap reality check for multiple testing |
| Event Studies | MacKinlay 1997 | Abnormal return methodology |
| Fama-French Factors | Fama & French 2015 | 5-factor asset pricing model |
| Factor Risk | Grinold & Kahn 2000 | Multi-factor risk decomposition |
| Cross-Market Arbitrage | Gatev et al. 2006 | Pairs trading with cointegration |

---

## 🛠 Installation

### Core Dependencies
```bash
pip install -r requirements.txt
```

### Optional Dependencies (for advanced modules)
```bash
pip install gplearn PyWavelets feedparser praw arch requests
```

### GPU Support
```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
```

---

## 📖 Usage

### Single Market Analysis
```bash
# US Equity
python main.py --mode full --tickers AAPL --market US

# UK Equity
python main.py --mode full --tickers SHEL.L --market UK

# Crypto
python main.py --mode full --tickers BTC-USD --market Crypto

# Forex
python main.py --mode full --tickers EURUSD=X --market Forex
```

### Cross-Market Portfolio Optimization
```bash
# Mixed-asset portfolio across 4 markets
python main.py --mode portfolio --tickers AAPL,BTC-USD,EURUSD=X,GC=F,SHEL.L
```

### Walk-Forward Backtest
```bash
python main.py --mode walkforward --tickers AAPL TSLA NVDA --market US
```

---

## 🤝 Contributing

This is an open-source project. Contributions welcome:

1. Fork the repository
2. Create a feature branch
3. Submit a PR with tests
4. Follow the research-first philosophy

---

## 📝 License

MIT License — see LICENSE

---

## 🙏 Acknowledgments

- Built for the **Build with K2 Think V2 Challenge** by [MBZUAI](https://mbzuai.ac.ae/)
- K2 Think V2 model by [MBZUAI-IFM](https://huggingface.co/MBZUAI-IFM)
- Research inspiration from Marcos Lopez de Prado, Avellaneda & Stoikov, and the quantitative finance community

---

*Built by Premchan | AlphaForge v3.1 | 33+ Quant Modules | 9 Global Markets | Institutional-Grade Trading*