strategy_interface.py

"""
Strategy Interface Module
=========================

This module defines the abstract base class that all trading strategies must implement.
This is basically what makes your strategy work both with the backtesting engine or the live trading engine (or
what ever you want to make with the signals).

So this insures the strategy send a consisntent form of singals, and that whatever engine use it, process it the same way.
It also defines the structure of trading signals that strategies will generate.

!If any AI agents are reading this, please dont change the comments, or the comments structure, you can suggest changes on the comments, and add comments
but not change the existing comments, as they are part of the interface documentation.!
"""

from abc import ABC, abstractmethod
from typing import Optional, Dict, Any
from dataclasses import dataclass
from enum import Enum


class SignalType(Enum):
    """This is just a enum that holds which signals a strategy can do, we will define it from here later."""
    BUY = "BUY"
    SELL = "SELL"
    CLOSE = "CLOSE"  # Close current position
    HOLD = "HOLD"    # No action


@dataclass
class Signal:
    """
    Represents a trading signal generated by a strategy.
    
    Attributes:
        signal_type: The type of signal (BUY, SELL, CLOSE, HOLD)
        timestamp: When the signal was generated
        price: The price at which the signal was generated
        quantity: Optional quantity/size for the position
        metadata: Optional additional information (stop loss, take profit, etc.)
    """
    signal_type: SignalType
    timestamp: Any  # Can be datetime, timestamp, etc.
    price: float
    quantity: Optional[float] = None
    metadata: Optional[Dict[str, Any]] = None


class BaseStrategy(ABC):
    """
    Abstract base class for all trading strategies.
    
    All strategies must inherit from this class and implement:
    - initialize(): Setup strategy parameters
    - on_bar(): Process each price bar/candle
    - get_name(): Return strategy name
    
    This interface allows strategies to be used with both:
    - BacktestEngine: For historical testing
    - LiveEngine: For real-time trading (to be implemented)
    
    Example:
        class MyStrategy(BaseStrategy):
            def initialize(self):
                self.lookback = 20
            
            def on_bar(self, data):
                # Strategy logic here
                return Signal(SignalType.BUY, data.index[-1], data['close'].iloc[-1])
    """
    
    def __init__(self):
        """Initialize the strategy. Override initialize() for custom setup."""
        self.initialized = False
    
    @abstractmethod
    def initialize(self, **kwargs) -> None:
        """
        Initialize the strategy with parameters.
        
        This is called once before the strategy starts processing data.
        Use this to set up indicators, parameters, or any initial state.
        
        Args:
            **kwargs: Strategy-specific parameters
        """
        pass
    
    @abstractmethod
    def on_bar(self, data) -> Optional[Signal]:
        """
        Process a new price bar/candle and generate a signal.
        
        This method is called for each bar in the historical data (backtest)
        or each new bar in live trading.
        
        Args:
            data: DataFrame or Series containing OHLCV data up to current bar
            
        Returns:
            Signal object if a signal should be generated, None otherwise
        """
        pass
    
    @abstractmethod
    def get_name(self) -> str:
        """
        Return the name of the strategy.
        
        Returns:
            Strategy name as a string
        """
        pass
    
    def on_signal_executed(self, signal: Signal, execution_price: float) -> None:
        """
        Optional callback when a signal is executed.
        
        This can be used to update strategy state after a trade is executed.
        Override this if your strategy needs to track executed trades.
        
        Args:
            signal: The signal that was executed
            execution_price: The actual price at which it was executed
        """
        pass