DafeSPALib

DafeSPALib: The Shadow Portfolio Adaptation & Strategy Selection Engine

This is not a backtester. This is a live, adaptive portfolio manager. It is a reinforcement learning system that learns which of your strategies to trust in the ever-changing chaos of the market.

█ CHAPTER 1: THE PHILOSOPHY - BEYOND A SINGLE STRATEGY
The search for a single "holy grail" trading strategy is a fool's errand. No single set of rules can perform optimally in all market conditions. A trend-following system that thrives in a bull run will be decimated by a choppy, range-bound market. A mean-reversion strategy that profits from ranges will be run over by a powerful breakout.

The DafeSPALib (Shadow Portfolio Adaptation Library) was created to solve this fundamental problem. It is built on a powerful principle from modern quantitative finance: instead of searching for one perfect strategy, a truly robust system should intelligently allocate to a portfolio of different strategies, dynamically favoring the one that is currently most effective.

This is not just a concept; it is a complete, production-grade engine built in Pine Script. It allows a developer to run multiple "shadow portfolios"—hypothetical trading accounts for each of your strategies—in parallel, in real time. The library tracks the actual equity curve, win rate, Sharpe ratio, and drawdown of each strategy. It then uses a sophisticated selection algorithm to determine which strategy is the "alpha" in the current market regime and tells you which one to follow. It is an AI portfolio manager that lives on your chart.

█ CHAPTER 2: THE CORE INNOVATIONS - WHAT MAKES THIS A REVOLUTIONARY ENGINE?
This library is not a simple strategy switcher. It is a suite of genuine, academically recognized machine learning and statistical concepts, adapted for the Pine Script environment.

Shadow Portfolio Tracking: This is the heart of the system. For each of your strategy "arms," the library maintains a complete, independent set of performance analytics. It doesn't just keep a simple "score." It tracks every hypothetical trade, calculates real P&L, and updates a full suite of institutional metrics, including the Sharpe Ratio (risk-adjusted return), Sortino Ratio (downside-risk-adjusted return), Profit Factor, and Maximum Drawdown. This provides a rich, data-driven foundation for all decision-making.
Advanced Selection Algorithms: The library doesn't just pick the strategy with the highest recent win rate. It uses sophisticated, battle-tested algorithms from the "multi-armed bandit" problem in machine learning to solve the critical "explore vs. exploit" dilemma:
Thompson Sampling: The default and most powerful. Instead of just picking the "best" arm, it samples from each arm's learned probability distribution of success (its Beta distribution). This naturally balances "exploitation" (using the strategy that works) with "exploration" (giving less-proven strategies a chance to shine), making it incredibly robust against changing conditions.

Upper Confidence Bound (UCB): A deterministic algorithm that is "optimistic in the face of uncertainty." It favors strategies that have both a high win rate and a high degree of uncertainty (fewer trades), encouraging intelligent exploration.
Epsilon-Greedy: A classic RL algorithm that mostly exploits the best-known strategy but, with a small probability (epsilon), explores a random one to prevent getting stuck on a sub-optimal choice.

Trauma-Based Memory Compression: This is a groundbreaking, proprietary concept. When the market experiences a "regime shock" (a sudden explosion in volatility, a violent trend reversal), a simple learning system can be paralyzed or make catastrophic errors. The SPA engine's "trauma" cycle is an intelligent response. It does not erase all learned knowledge. Instead, it compresses the memory: it preserves the direction of what it has learned (e.g., "Strategy A is generally better than B") but it destroys the confidence. The AI "remembers" its experiences but becomes highly uncertain, forcing it to re-learn and adapt to the new market personality with incredible speed. Think of it like PTSD for an AI: the memory of the event remains, but the trust is shattered.

Multi-Layer Concept Drift Detection: This is the system's "earthquake detector." It is constantly scanning for signs that the market's fundamental character is changing ("concept drift"). It uses three layers of detection—Structural (trend slope changes), Volatility (ATR explosions), and Participation (volume anomalies)—to identify a regime shock and trigger the trauma compression cycle.

█ CHAPTER 3: A DUAL-PURPOSE FRAMEWORK - MODES OF OPERATION
This library, along with its companion DAFE libraries, is designed for ultimate flexibility. As a developer, you have complete freedom to use these tools independently or as a fully integrated system.

MODE 1: STANDALONE ENGINE OPERATION (Independent Power)
The DafeSPALib can be used entirely on its own to build a powerful portfolio-of-strategies indicator without any external ML. This approach is perfect for comparing, validating, and dynamically selecting from your own existing, rule-based trading ideas.

The Workflow:
Your indicator initializes the SPA engine with a set number of "arms" (e.g., 4).
On each bar, you calculate the signals for each of your independent strategies (e.g., an EMA Crossover, an RSI Mean Reversion, a Bollinger Breakout).
You feed this array of signals ([1, -1, 0, 1]) into the SPA's feed_signals() function.
The SPA engine updates the shadow portfolio for each of the four strategies based on these signals. You then call the select() function, and the SPA's chosen algorithm (e.g., Thompson Sampling) will return the index of the single strategy arm that it trusts the most right now.
Your indicator's final output signal is the signal from that selected arm.

The Result: A complete, self-contained meta-strategy. Your indicator is no longer just one strategy; it is an intelligent manager that dynamically switches between multiple strategies, adapting to the market by selecting the one with the best real-time, risk-adjusted performance.

MODE 2: BRIDGED SUPER-SYSTEM OPERATION (The Ultimate AI)
This is the pinnacle of the DAFE ecosystem. In this advanced mode, the DafeSPALib acts as the "strategic brain" or "portfolio manager" that is fused with a tactical machine learning engine (like the DafeRLMLLib) via a master communication protocol (the DafeMLSPABridge).

The Workflow:
The ML engine generates proposals.
The Bridge Library translates these proposals into a portfolio of micro-strategies.
The SPA engine (this library) receives this portfolio of signals, tracks their shadow performance, and uses its advanced selection algorithms to choose the single best micro-strategy to follow. This becomes the final trade decision.

The final P&L from the SPA's selection is then routed back through the Bridge to the ML engine as a highly qualified reward signal for learning.

The Result: A hybrid intelligence that is more robust and adaptive than either system alone. The ML provides tactical creativity, while the SPA provides ruthless, performance-based strategic oversight.

█ CHAPTER 4: THE DEVELOPER'S MASTERCLASS - IMPLEMENTATION GUIDE
This library is a professional framework. This guide provides the complete, unabridged instructions and templates required to integrate the DAFE SPA engine into your own custom Pine Script indicators.

PART I: THE INPUTS TEMPLATE (THE CONTROL PANEL)
To give your users full control over the AI, copy this entire block of inputs into your indicator script. It is professionally organized with groups and detailed tooltips.

// ╔════════════════════════════════════════════════════════╗
// ║                                   INPUTS TEMPLATE (COPY INTO YOUR SCRIPT)                               ║
// ╚════════════════════════════════════════════════════════╝

// INPUT GROUPS
string G_SPA_ENGINE = "════════════ 🧠 SPA ENGINE ════════════"
string G_SPA_DRIFT  = "════════════ 🌊 CONCEPT DRIFT ══════════"
string G_SPA_DASH   = "════════════ 📋 DIAGNOSTICS ═══════════"

// SPA ENGINE
int i_spa_num_arms = input.int(4, "Number of Strategy Arms", minval=2, maxval=10, group=G_SPA_ENGINE,
     tooltip="The number of parallel strategies the SPA will track.")

string i_spa_selection = input.string("Thompson Sampling", "🤖 Selection Algorithm", 
     options=["Thompson Sampling", "Upper Confidence Bound (UCB)", "Epsilon-Greedy", "Softmax"], group=G_SPA_ENGINE,
     tooltip="The machine learning algorithm used to select the best arm.\n\n" +
             "• Thompson Sampling: Bayesian approach, samples from each arm's success probability. Balances explore/exploit perfectly (Recommended).\n" +
             "• UCB: Optimistic approach that favors arms with high uncertainty. Excellent for exploration.\n" +
             "• Epsilon-Greedy: Mostly exploits the best arm, but explores randomly with a small probability (epsilon).\n" +
             "• Softmax: Selects arms based on a probability distribution weighted by their performance.")

float i_spa_epsilon = input.float(0.15, "🧭 Epsilon (for Epsilon-Greedy)", minval=0.01, maxval=0.5, step=0.01, group=G_SPA_ENGINE,
     tooltip="The probability of taking a random action to explore. This value automatically decays over time.")

float i_spa_decay = input.float(0.995, "🧠 Memory Decay Rate", minval=0.98, maxval=0.9999, step=0.0005, group=G_SPA_ENGINE,
     tooltip="Controls recency bias. A value of 0.995 means the AI gives slightly more weight to recent performance. Lower values create a very short-term memory.")

// CONCEPT DRIFT & TRAUMA
bool i_spa_use_drift = input.bool(true, "🌊 Enable Concept Drift & Trauma", group=G_SPA_DRIFT,
     tooltip="Allows the engine to detect market regime shocks and trigger a 'Trauma Compression' cycle to accelerate re-learning.")

float i_spa_trauma_sens = input.float(2.0, "Trauma Sensitivity", minval=1.2, maxval=4.0, step=0.1, group=G_SPA_DRIFT,
     tooltip="How sensitive the shock detector is. A lower value will trigger trauma cycles more frequently on smaller volatility/volume spikes.")

// DIAGNOSTICS
bool i_spa_show_dash = input.bool(true, "📋 Show Diagnostics Dashboard", group=G_SPA_DASH)

PART II: THE IMPLEMENTATION LOGIC (THE HEART OF YOUR SCRIPT)
This is the boilerplate code you will adapt to your indicator. It shows the complete loop of feeding signals, detecting drift, and selecting the best strategy.

// ╔═══════════════════════════════════════════════════════╗
// ║                                   USAGE EXAMPLE (ADAPT TO YOUR SCRIPT)                                ║
// ╚═══════════════════════════════════════════════════════╝

// 1. INITIALIZE THE ENGINE (happens only on the first bar)
int sel_method_id = i_spa_selection == "Thompson Sampling" ? 0 : i_spa_selection == "Upper Confidence Bound (UCB)" ? 1 : i_spa_selection == "Epsilon-Greedy" ? 2 : 3
var spa.SPAEngine engine = spa.init(
     num_arms = i_spa_num_arms, 
     arm_names = array.from("TrendArm", "ReversionArm", "BreakoutArm", "MomentumArm"), // Give your arms names!
     selection_method = sel_method_id, 
     decay_rate = i_spa_decay, 
     trauma_sensitivity = i_spa_trauma_sens, 
     epsilon = i_spa_epsilon
     )

// 2. DEFINE YOUR STRATEGY SIGNALS (runs on every bar)
// These are your own custom, rule-based strategies. The signal should be +1 for Buy, -1 for Sell, 0 for Neutral.
int trend_signal = close > ta.ema(close, 200) and ta.crossover(ta.ema(close, 20), ta.ema(close, 50)) ? 1 : 
                   close < ta.ema(close, 200) and ta.crossunder(ta.ema(close, 20), ta.ema(close, 50)) ? -1 : 0
                   
int reversion_signal = ta.crossunder(ta.rsi(close, 14), 30) ? 1 : ta.crossover(ta.rsi(close, 14), 70) ? -1 : 0

int breakout_signal = ta.crossover(close, ta.highest(high, 20)[1]) ? 1 : ta.crossunder(close, ta.lowest(low, 20)[1]) ? -1 : 0

int momentum_signal = ta.crossover(ta.mom(close, 10), 0) ? 1 : ta.crossunder(ta.mom(close, 10), 0) ? -1 : 0

// Create an array of your signals. The order MUST be consistent.
array<int> all_signals = array.from(trend_signal, reversion_signal, breakout_signal, momentum_signal)

// 3. THE MAIN LOOP (Feed -> Detect -> Select) - runs on every bar

// --- FEED: Update the shadow portfolios with the latest signals and price ---
engine := spa.feed_signals(engine, all_signals, close)

// --- DETECT: Run the concept drift engine ---
if i_spa_use_drift
    float trend_slope = ta.linreg(close, 20, 0) - ta.linreg(close, 20, 1)
    engine := spa.detect_drift(engine, close, volume, ta.atr(14), trend_slope)
    engine := spa.apply_trauma_cycle(engine) // This will compress memory if a shock was detected

// --- SELECT: Ask the engine for its best choice ---
[int selected_arm, float confidence, spa.SPAEngine updated_engine] = spa.select(engine)
engine := updated_engine // CRITICAL: Always update the engine state

// --- ACT: Use the final, selected signal for your indicator's logic ---
int final_signal = array.get(all_signals, selected_arm)
string selected_name = spa.get_name(engine, selected_arm)

// Example: Color bars based on the final, SPA-vetted signal
barcolor(final_signal == 1 ? color.new(color.green, 70) : final_signal == -1 ? color.new(color.red, 70) : na)

// 4. DISPLAY DIAGNOSTICS
if i_spa_show_dash and barstate.islast
    string diag_text = spa.diagnostics(engine)
    label.new(bar_index, high, diag_text, 
         style=label.style_label_down, 
         color=color.new(#0A0A14, 10), 
         textcolor=#00E5FF, 
         size=size.small,
         textalign=text.align_left)

█ DEVELOPMENT PHILOSOPHY
The DafeSPALib was born from the realization that market adaptation is the true holy grail of trading. While any single strategy is brittle, a portfolio of strategies, managed by an intelligent selection algorithm, is antifragile—it can learn, adapt, and potentially thrive in the face of chaos. This library is an open-source tool for the systems thinker, the quantitative analyst, and the professional developer. It is designed to provide the foundational architecture for building the most robust, adaptive, and intelligent trading systems on the TradingView platform.
This library is a tool for that wisdom. It is not about having the single smartest algorithm, but about having a disciplined, data-driven process for selecting the one that is working right now.

█ DISCLAIMER & IMPORTANT NOTES
THIS IS A LIBRARY FOR ADVANCED DEVELOPERS: This script does nothing on its own. It is a powerful engine that must be integrated into other indicators and fed with valid strategy signals.
PERFORMANCE IS HYPOTHETICAL: The shadow portfolio tracking is a simulation. It does not account for slippage, fees (unless manually added to P&L), or the psychological pressure of live trading.
LEARNING REQUIRES DATA: The selection algorithms require a sufficient number of trades (at least 20-30 per arm) to make statistically meaningful decisions. The engine will be less reliable during the initial "warm-up" period.

"You don't need to be a rocket scientist. Investing is not a game where the guy with the 160 IQ beats the guy with the 130 IQ."
— Warren Buffett

Taking you to school. - Dskyz, Create with RL.