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

```python
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:

```python
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:

```python
# 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:**
```json
{
    "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:**
```json
{
    "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

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

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

```json
{
    "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:**
```json
{
    "name": "default",
    "params": {
        "timeframe": "5min"  # Strategy works on 5-minute data
    }
}
```

**Multi-Timeframe Strategy (Future Enhancement):**
```json
{
    "name": "multi_tf_strategy",
    "params": {
        "timeframes": ["5min", "15min", "1h"],  # Multiple timeframes
        "primary_timeframe": "15min"
    }
}
```

## Usage Examples

### Create Strategy Manager

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

```python
# 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:**
```python
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:**
```python
# In StrategyManager._load_strategies()
elif name == "new_strategy":
    strategies.append(NewStrategy(weight, params))
```

### Multi-Timeframe Strategy Development

For strategies requiring multiple timeframes:

```python
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**