deepalpha-freqai 1.0.6

Quant-grade ML plugin for Freqtrade/FreqAI: Triple Barrier labels, SHAP selection, meta-labeling, purged walk-forward CV, LightGBM.

  ____                  _    _       _
 |  _ \  ___  ___ _ __ / \  | |_ __ | |__   __ _
 | | | |/ _ \/ _ \ '_ \ _ \ | | '_ \| '_ \ / _` |
 | |_| |  __/  __/ |_) | | || | |_) | | | | (_| |
 |____/ \___|\___| .__/|_|_||_| .__/|_| |_|\__,_|
                 |_|          |_|
            F R E Q A I   P L U G I N

Turn Freqtrade into a quant-grade ML trading machine.

A drop-in FreqAI model that replaces the default pipeline with institutional-grade ML techniques Triple Barrier Labeling. SHAP feature selection. Meta-labeling. Purged walk-forward CV. LightGBM.

Install - Quick Start - Docs - Examples - Website - Discord

---

Why DeepAlpha?

Stock FreqAI trains a regressor on raw future returns. That is a textbook approach that leaks, overfits, and ignores regime shifts. DeepAlpha replaces it with techniques used by quantitative hedge funds, codified by Marcos Lopez de Prado in Advances in Financial Machine Learning.

Standard FreqAI vs. DeepAlpha

	Standard FreqAI	DeepAlpha
Labeling	Fixed-horizon return	Triple Barrier (profit/stop/time)
Feature selection	All features, always	SHAP top-k, auto-refresh
Signal filter	Threshold on raw output	Meta-labeling (2nd model)
Validation	k-fold or holdout	Purged Walk-Forward CV
Overfitting control	Manual	Embargo + purge gaps
Backend	Mixed (LGB/XGB/sklearn)	LightGBM (tuned)
Realistic labels	No	Yes
Production-ready	Sometimes	Always

---

Install in 10 seconds

pip install deepalpha-freqai

That is it. No cloning, no symlinks, no copy-paste. The plugin registers DeepAlphaModel for FreqAI automatically.

---

Quick start in 30 seconds

1. Set the model in your config.json:

{
  "freqai": {
    "enabled": true,
    "model_type": "DeepAlphaModel",
    "deepalpha": {
      "triple_barrier":     { "profit_taking": 2.0, "stop_loss": 1.0, "max_holding_period": 48 },
      "shap_feature_selection": { "enabled": true, "top_k": 30 },
      "meta_labeling":      { "enabled": true, "threshold": 0.55 },
      "purged_cv":          { "n_splits": 5, "purge_gap": 24, "embargo_pct": 0.01 }
    }
  }
}

2. Run backtest:

freqtrade backtesting --strategy DeepAlphaStrategy \
  --config config.json \
  --freqaimodel DeepAlphaModel

That is it. DeepAlpha handles labels, feature selection, meta-filtering, and CV for you.

Prefer to use the primitives standalone (without FreqAI)? See examples/demo.py - 50 lines, no Freqtrade required.

---

Architecture

flowchart LR
    A[OHLCV + Indicators] --> B[Triple Barrier<br/>Labeling]
    B --> C[Primary LGBM<br/>full features]
    C --> D[SHAP Feature<br/>Selection top-k]
    D --> E[Primary LGBM<br/>pruned features]
    E --> F[Meta-Labeling<br/>LGBM filter]
    F --> G[Purged<br/>Walk-Forward CV]
    G --> H[Trading<br/>Signal]
    style B fill:#ff6b6b,color:#fff
    style D fill:#4ecdc4,color:#fff
    style F fill:#ffe66d,color:#000
    style G fill:#a8e6cf,color:#000

Every training run executes all six stages. Every prediction is filtered by the meta-model.

---

What is inside

The 5 pillars

1. Triple Barrier Labeling Labels candles based on which of three barriers is hit first - profit target, stop loss, or time expiry. Volatility-scaled, so labels adapt to regime shifts. No more training on noise.

2. SHAP Feature Selection After the first pass, SHAP values rank every feature by real contribution. The model is retrained using only the top-k. Refreshed every N trainings to follow regime drift. Result: less noise, less overfitting, faster inference.

3. Meta-Labeling A second LightGBM model learns when the primary model is likely right. Trades only fire when meta-confidence exceeds threshold. Dramatically improves precision at the cost of lower recall - exactly what live trading demands.

4. Purged Walk-Forward CV Time-series CV with purge gaps and embargo periods. Kills the most insidious lookahead bias. Honest out-of-sample diagnostics, every fold.

5. LightGBM Backend Gradient boosting tuned for financial noise. GPU-ready. Deterministic (random_state=42). Production-grade.

---

Performance (honest)

Results vary heavily by asset, timeframe, and feature set. The numbers below are from our own backtests on BTC/USDT 5m, 2024-2025, with 120-day training windows and 7-day forward tests. Your mileage will vary.

Metric	Standard FreqAI	DeepAlpha
Directional accuracy	~55-60%	~65-68%
Sharpe (annualised)	~0.8-1.2	~1.8-2.2
Max drawdown	~15-25%	~8-12%
Features used (of 200+)	All	30 (SHAP)
Trades filtered by meta	0%	~30-45%

What we will NOT promise:

• 100x returns
• Profit every market
• Set-and-forget riches

What we WILL say:

• Robust, peer-reviewed techniques
• Honest CV diagnostics
• Clean, tested, typed code
• Past performance is not future performance

---

When to use this

Use DeepAlpha if you...

• Already use FreqAI and want better science under the hood
• Want labels that reflect actual trading outcomes, not arbitrary horizons
• Suffer from models that look great in CV and die live (lookahead bias)
• Run portfolios of 10+ assets where overfitting compounds fast
• Care about calibrated signals, not just hit rate

DO NOT use this if you...

• Trade manually and want discretion
• Have less than 6 months of OHLCV history per pair
• Run extremely high-frequency (sub-second) strategies - this is minute-to-hour scale
• Refuse to read logs and adjust hyperparameters

---

Examples

See ./examples/:

• demo.py - 50-line standalone demo. Synthetic data -> Triple Barrier -> LGBM -> predictions. No Freqtrade required.
• quickstart.ipynb - Jupyter walkthrough with visualisations, SHAP plots, and a toy backtest.
• ../config_example.json - Full FreqAI config with DeepAlpha block.
• ../example_strategy.py - Reference Freqtrade strategy.

---

Roadmap

• v1.0.0 - Initial release
• v1.0.5 - Production-stable predict() schema, no more crashes
• v1.1 - Ensemble mode (LGBM + XGBoost + CatBoost stacking)
• v1.2 - Regime detection via HMM pre-filter
• v1.3 - Attention transformer option as primary model
• v1.4 - Fractional differentiation for feature stationarity (de Prado Ch. 5)
• v2.0 - Official FreqAI upstream submission

Vote on features on Discord.

---

The bigger picture

This plugin is extracted from DeepAlpha, a production trading system running the same pipeline live across crypto perps and spot. If you want the full stack - automated training, multi-exchange execution, risk manager, vault - visit deepalphabot.com.

The open-source plugin exists because we believe the science should be free. The edge is in the execution.

---

Community

• Website: deepalphabot.com
• Discord: Join here - quant chat, strategy tuning, free support
• GitHub: stefanoviana/deepalpha
• Issues / bugs: Open a ticket

---

Contributing

PRs welcome. Please:

1. Fork and branch from main
2. Add tests under ./tests/ (we use pytest)
3. Keep PEP-8, add type hints, run pytest -v
4. Open a PR with a clear description and backtest evidence if applicable

Want to upstream DeepAlpha into Freqtrade core? We are actively working on this - join Discord and help us get to v2.0.

---

License

MIT. Use it, fork it, ship it. Attribution appreciated but not required.

---

Acknowledgments

This plugin stands on the shoulders of:

• Marcos Lopez de Prado - Advances in Financial Machine Learning (Wiley, 2018). Triple Barrier, Meta-Labeling, Purged CV, Fractional Differentiation. Essential reading.
• Ernest Chan - Machine Trading and Quantitative Trading. The rigor and the scars.
• Lundberg & Lee - SHAP: A Unified Approach to Interpreting Model Predictions (NeurIPS 2017).
• The Freqtrade team - for building FreqAI and keeping it open.

If this plugin makes you money, buy their books first.

---

Built by traders, for traders.

If DeepAlpha helps you, star the repo and tell a friend.