Update model card with multi-market support documentation

2fdeb16 verified 3 days ago

13.2 kB

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