Cycles/docs/strategy_manager.md

Strategy Manager Documentation

Overview

The Strategy Manager is a sophisticated orchestration system that enables the combination of multiple trading strategies with configurable signal aggregation rules. It supports multi-timeframe analysis, weighted consensus voting, and flexible signal combination methods.

Architecture

Core Components

1. StrategyBase: Abstract base class defining the strategy interface
2. StrategySignal: Encapsulates trading signals with confidence levels
3. StrategyManager: Orchestrates multiple strategies and combines signals
4. Strategy Implementations: DefaultStrategy, BBRSStrategy, etc.

New Timeframe System

The framework now supports strategy-level timeframe management:

• Strategy-Controlled Timeframes: Each strategy specifies its required timeframes
• Automatic Data Resampling: Framework automatically resamples 1-minute data to strategy needs
• Multi-Timeframe Support: Strategies can use multiple timeframes simultaneously
• Precision Stop-Loss: All strategies maintain 1-minute data for precise execution

class MyStrategy(StrategyBase):
    def get_timeframes(self):
        return ["15min", "1h"]  # Strategy needs both timeframes
    
    def initialize(self, backtester):
        # Access resampled data
        data_15m = self.get_data_for_timeframe("15min")
        data_1h = self.get_data_for_timeframe("1h")
        # Setup indicators...

Strategy Interface

StrategyBase Class

All strategies must inherit from StrategyBase and implement:

from cycles.strategies.base import StrategyBase, StrategySignal

class MyStrategy(StrategyBase):
    def get_timeframes(self) -> List[str]:
        """Specify required timeframes"""
        return ["15min"]
    
    def initialize(self, backtester) -> None:
        """Setup strategy with data"""
        self._resample_data(backtester.original_df)
        # Calculate indicators...
        self.initialized = True
    
    def get_entry_signal(self, backtester, df_index: int) -> StrategySignal:
        """Generate entry signals"""
        if condition_met:
            return StrategySignal("ENTRY", confidence=0.8)
        return StrategySignal("HOLD", confidence=0.0)
    
    def get_exit_signal(self, backtester, df_index: int) -> StrategySignal:
        """Generate exit signals"""
        if exit_condition:
            return StrategySignal("EXIT", confidence=1.0, 
                                metadata={"type": "SELL_SIGNAL"})
        return StrategySignal("HOLD", confidence=0.0)

StrategySignal Class

Encapsulates trading signals with metadata:

# Entry signal with high confidence
entry_signal = StrategySignal("ENTRY", confidence=0.9)

# Exit signal with specific price
exit_signal = StrategySignal("EXIT", confidence=1.0, price=50000,
                           metadata={"type": "STOP_LOSS"})

# Hold signal
hold_signal = StrategySignal("HOLD", confidence=0.0)

Available Strategies

1. Default Strategy

Meta-trend analysis using multiple Supertrend indicators.

Features:

• Uses 3 Supertrend indicators with different parameters
• Configurable timeframe (default: 15min)
• Entry when all trends align upward
• Exit on trend reversal or stop-loss

Configuration:

{
    "name": "default",
    "weight": 1.0,
    "params": {
        "timeframe": "15min",
        "stop_loss_pct": 0.03
    }
}

Timeframes:

• Primary: Configurable (default 15min)
• Stop-loss: Always includes 1min for precision

2. BBRS Strategy

Bollinger Bands + RSI with market regime detection.

Features:

• Market regime detection (trending vs sideways)
• Adaptive parameters based on market conditions
• Volume analysis and confirmation
• Multi-timeframe internal analysis (1min → 15min/1h)

Configuration:

{
    "name": "bbrs",
    "weight": 1.0,
    "params": {
        "bb_width": 0.05,
        "bb_period": 20,
        "rsi_period": 14,
        "strategy_name": "MarketRegimeStrategy",
        "stop_loss_pct": 0.05
    }
}

Timeframes:

• Input: 1min (Strategy class handles internal resampling)
• Internal: 15min, 1h (handled by underlying Strategy class)
• Output: Mapped back to 1min for backtesting

Signal Combination

Entry Signal Combination

combination_rules = {
    "entry": "weighted_consensus",  # or "any", "all", "majority"
    "min_confidence": 0.6
}

Methods:

• any: Enter if ANY strategy signals entry
• all: Enter only if ALL strategies signal entry
• majority: Enter if majority of strategies signal entry
• weighted_consensus: Enter based on weighted average confidence

Exit Signal Combination

combination_rules = {
    "exit": "priority"  # or "any", "all"
}

Methods:

• any: Exit if ANY strategy signals exit (recommended for risk management)
• all: Exit only if ALL strategies agree
• priority: Prioritized exit (STOP_LOSS > SELL_SIGNAL > others)

Configuration

Basic Strategy Manager Setup

{
    "strategies": [
        {
            "name": "default",
            "weight": 0.6,
            "params": {
                "timeframe": "15min",
                "stop_loss_pct": 0.03
            }
        },
        {
            "name": "bbrs", 
            "weight": 0.4,
            "params": {
                "bb_width": 0.05,
                "strategy_name": "MarketRegimeStrategy"
            }
        }
    ],
    "combination_rules": {
        "entry": "weighted_consensus",
        "exit": "any",
        "min_confidence": 0.5
    }
}

Timeframe Examples

Single Timeframe Strategy:

{
    "name": "default",
    "params": {
        "timeframe": "5min"  # Strategy works on 5-minute data
    }
}

Multi-Timeframe Strategy (Future Enhancement):

{
    "name": "multi_tf_strategy",
    "params": {
        "timeframes": ["5min", "15min", "1h"],  # Multiple timeframes
        "primary_timeframe": "15min"
    }
}

Usage Examples

Create Strategy Manager

from cycles.strategies import create_strategy_manager

config = {
    "strategies": [
        {"name": "default", "weight": 1.0, "params": {"timeframe": "15min"}}
    ],
    "combination_rules": {
        "entry": "any",
        "exit": "any"
    }
}

strategy_manager = create_strategy_manager(config)

Initialize and Use

# Initialize with backtester
strategy_manager.initialize(backtester)

# Get signals during backtesting
entry_signal = strategy_manager.get_entry_signal(backtester, df_index)
exit_signal, exit_price = strategy_manager.get_exit_signal(backtester, df_index)

# Get strategy summary
summary = strategy_manager.get_strategy_summary()
print(f"Loaded strategies: {[s['name'] for s in summary['strategies']]}")
print(f"All timeframes: {summary['all_timeframes']}")

Extending the System

Adding New Strategies

1. Create Strategy Class:

class NewStrategy(StrategyBase):
    def get_timeframes(self):
        return ["1h"]  # Specify required timeframes
    
    def initialize(self, backtester):
        self._resample_data(backtester.original_df)
        # Setup indicators...
        self.initialized = True
    
    def get_entry_signal(self, backtester, df_index):
        # Implement entry logic
        pass
    
    def get_exit_signal(self, backtester, df_index):
        # Implement exit logic
        pass

2. Register in StrategyManager:

# In StrategyManager._load_strategies()
elif name == "new_strategy":
    strategies.append(NewStrategy(weight, params))

Multi-Timeframe Strategy Development

For strategies requiring multiple timeframes:

class MultiTimeframeStrategy(StrategyBase):
    def get_timeframes(self):
        return ["5min", "15min", "1h"]
    
    def initialize(self, backtester):
        self._resample_data(backtester.original_df)
        
        # Access different timeframes
        data_5m = self.get_data_for_timeframe("5min")
        data_15m = self.get_data_for_timeframe("15min") 
        data_1h = self.get_data_for_timeframe("1h")
        
        # Calculate indicators on each timeframe
        # ...
    
    def _calculate_signal_confidence(self, backtester, df_index):
        # Analyze multiple timeframes for confidence
        primary_signal = self._get_primary_signal(df_index)
        confirmation = self._get_timeframe_confirmation(df_index)
        
        return primary_signal * confirmation

Performance Considerations

Timeframe Management

• Efficient Resampling: Each strategy resamples data once during initialization
• Memory Usage: Only required timeframes are kept in memory
• Signal Mapping: Efficient mapping between timeframes using pandas reindex

Strategy Combination

• Lazy Evaluation: Signals calculated only when needed
• Error Handling: Individual strategy failures don't crash the system
• Logging: Comprehensive logging for debugging and monitoring

Best Practices

1. Strategy Design:

   • Specify minimal required timeframes
   • Include 1min for stop-loss precision
   • Use confidence levels effectively

2. Signal Combination:

   • Use any for exits (risk management)
   • Use weighted_consensus for entries
   • Set appropriate minimum confidence levels

3. Error Handling:

   • Implement robust initialization checks
   • Handle missing data gracefully
   • Log strategy-specific warnings

4. Testing:

   • Test strategies individually before combining
   • Validate timeframe requirements
   • Monitor memory usage with large datasets

Troubleshooting

Common Issues

1. Timeframe Mismatches:

   • Ensure strategy specifies correct timeframes
   • Check data availability for all timeframes

2. Signal Conflicts:

   • Review combination rules
   • Adjust confidence thresholds
   • Monitor strategy weights

3. Performance Issues:

   • Minimize timeframe requirements
   • Optimize indicator calculations
   • Use efficient pandas operations

Debugging Tips

• Enable detailed logging: logging.basicConfig(level=logging.DEBUG)
• Use strategy summary: manager.get_strategy_summary()
• Test individual strategies before combining
• Monitor signal confidence levels

---

Version: 1.0.0
Last Updated: January 2025
TCP Cycles Project