MarketRegimePredictor

Market Regime Fingerprinter

A Unified Machine Learning System for Detecting and Predicting Financial Market Regimes.

📌 Overview

Understanding whether the market is in a predictable trend, a volatile chop, or a liquidity crisis is crucial for portfolio management. This project uses Unsupervised Learning (K-Means) to discover hidden market states ("Regimes") and Supervised Learning (XGBoost) to predict these states in real-time.

🏗 Architecture

1. Data Ingestion: Fetches daily OHLCV data via yfinance.
2. Feature Engineering: Calculates Rolling Volatility, RSI, MACD, ATR, Volume Z-Scores, and Price Acceleration.
3. Regime Discovery:
   • Uses K-Means Clustering on stability/volatility features.
   • Automatically segments history into distinct regimes.
   • Dynamic Labeling: The app intelligently names regimes (e.g., "Steady Bull", "Crash") based on their statistical properties (Returns vs Volatility).
4. Classification:
   • Trains an XGBoost Classifier to map daily features to the discovered regime.
   • Optimized for deployability and interpretability.
5. Inference UI:
   • A Gradio web app for visualizing regimes and "Regime Fingerprints" (SHAP explanations).
   • Includes a Novice Mode with natural language explanations and a glossary.

🚀 Installation

pip install -r requirements.txt

🏃 Usage

1. Data & Training Pipeline

Run the following scripts in order:

# 1. Download Data & Generate Features
python src/data_loader.py

# 2. Discover Regimes (Clustering)
python src/regime_discovery.py

# 3. Train Classifier
python src/train_classifier.py

2. Run the App

Launch the interactive dashboard:

python app.py

⚠️ Disclaimer

This is a research project for educational purposes only.

• This model classifies historical behavioral patterns, not future prices.
• Market regimes do not guarantee future behavior.
• NOT FINANCIAL ADVICE. Do not trade based on these signals.