signalflow-trading 0.2.1__py3-none-any.whl

signalflow/strategy/component/metric/main_metrics.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from signalflow.core import StrategyState
+from signalflow.core.decorators import sf_component
+from signalflow.strategy.component.base import StrategyMetric
+import numpy as np
+
+
+@dataclass
+@sf_component(name='total_return', override=True)
+class TotalReturnMetric(StrategyMetric):
+    """Computes total return metrics for the portfolio."""
+    
+    initial_capital: float = 10000.0
+    
+    @property
+    def name(self) -> str:
+        return 'total_return'
+    
+    def compute(
+        self,
+        state: StrategyState,
+        prices: dict[str, float]
+    ) -> dict[str, float]:
+        equity = state.portfolio.equity(prices=prices)
+        cash = state.portfolio.cash
+        
+        total_realized = sum(p.realized_pnl for p in state.portfolio.positions.values())
+        total_unrealized = sum(p.unrealized_pnl for p in state.portfolio.open_positions())
+        total_fees = sum(p.fees_paid for p in state.portfolio.positions.values())
+        
+        total_return = (equity - self.initial_capital) / self.initial_capital if self.initial_capital > 0 else 0.0
+        
+        return {
+            'equity': equity,
+            'cash': cash,
+            'total_return': total_return,
+            'realized_pnl': total_realized,
+            'unrealized_pnl': total_unrealized,
+            'total_fees': total_fees,
+            'open_positions': len(state.portfolio.open_positions()),
+            'closed_positions': len([p for p in state.portfolio.positions.values() if p.is_closed]),
+        }
+
+@dataclass
+@sf_component(name='balance_allocation', override=True)
+class BalanceAllocationMetric(StrategyMetric):
+    
+    initial_capital: float = 10000.0
+    
+    @property
+    def name(self) -> str:
+        return 'balance_allocation'
+    
+    def compute(self, state: StrategyState, prices: dict[str, float]) -> dict[str, float]:
+        equity = state.portfolio.equity(prices=prices)
+        cash = state.portfolio.cash
+        
+        positions_value = equity - cash
+        capital_utilization = positions_value / equity if equity > 0 else 0.0
+        free_balance_pct = cash / equity if equity > 0 else 0.0
+        allocation_vs_initial = positions_value / self.initial_capital if self.initial_capital > 0 else 0.0
+        
+        return {
+            'capital_utilization': capital_utilization,      
+            'free_balance_pct': free_balance_pct,           
+            'allocated_value': positions_value,             
+            'allocation_vs_initial': allocation_vs_initial 
+        }
+
+
+@dataclass
+@sf_component(name='drawdown', override=True)
+class DrawdownMetric(StrategyMetric):
+    
+    _peak_equity: float = 0.0
+    _max_drawdown: float = 0.0
+    
+    @property
+    def name(self) -> str:
+        return 'drawdown'
+    
+    def compute(self, state: StrategyState, prices: dict[str, float]) -> dict[str, float]:
+        equity = state.portfolio.equity(prices=prices)
+        
+        if equity > self._peak_equity:
+            self._peak_equity = equity
+        
+        current_drawdown = 0.0
+        if self._peak_equity > 0:
+            current_drawdown = (self._peak_equity - equity) / self._peak_equity
+        
+        if current_drawdown > self._max_drawdown:
+            self._max_drawdown = current_drawdown
+        
+        return {
+            'current_drawdown': current_drawdown,
+            'max_drawdown': self._max_drawdown,
+            'peak_equity': self._peak_equity
+        }
+
+
+@dataclass
+@sf_component(name='win_rate', override=True)
+class WinRateMetric(StrategyMetric):
+    
+    @property
+    def name(self) -> str:
+        return 'win_rate'
+    
+    def compute(self, state: StrategyState, prices: dict[str, float]) -> dict[str, float]:
+        closed_positions = [
+            p for p in state.portfolio.positions.values() 
+            if p.is_closed
+        ]
+        
+        if not closed_positions:
+            return {
+                'win_rate': 0.0,
+                'winning_trades': 0,
+                'losing_trades': 0
+            }
+        
+        winning = sum(1 for p in closed_positions if p.realized_pnl > 0)
+        losing = sum(1 for p in closed_positions if p.realized_pnl <= 0)
+        
+        win_rate = winning / len(closed_positions) if closed_positions else 0.0
+        
+        return {
+            'win_rate': win_rate,
+            'winning_trades': winning,
+            'losing_trades': losing
+        }
+
+
+@dataclass
+@sf_component(name='sharpe_ratio', override=True)
+class SharpeRatioMetric(StrategyMetric):
+
+    initial_capital: float = 10000.0
+    window_size: int = 100  
+    risk_free_rate: float = 0.0 
+    _returns_history: list[float] = None
+    
+    def __post_init__(self):
+        self._returns_history = []
+    
+    @property
+    def name(self) -> str:
+        return 'sharpe_ratio'
+    
+    def compute(self, state: StrategyState, prices: dict[str, float]) -> dict[str, float]:
+        import numpy as np
+        
+        equity = state.portfolio.equity(prices=prices)
+        current_return = (equity - self.initial_capital) / self.initial_capital
+        
+        self._returns_history.append(current_return)
+        
+        if len(self._returns_history) > self.window_size:
+            self._returns_history.pop(0)
+        
+        if len(self._returns_history) < 2:
+            return {'sharpe_ratio': 0.0}
+        
+        returns_array = np.array(self._returns_history)
+        returns_diff = np.diff(returns_array)
+        
+        if len(returns_diff) < 2:
+            return {'sharpe_ratio': 0.0}
+        
+        mean_return = np.mean(returns_diff)
+        std_return = np.std(returns_diff)
+        
+        if std_return == 0:
+            return {'sharpe_ratio': 0.0}
+        
+        sharpe = (mean_return - self.risk_free_rate) / std_return
+        
+        return {'sharpe_ratio': sharpe}
+

signalflow/strategy/runner/__init__.py

@@ -0,0 +1,8 @@
+from signalflow.strategy.runner.base import StrategyRunner
+from signalflow.strategy.runner.backtest_runner import BacktestRunner
+from signalflow.strategy.runner.optimized_backtest_runner import OptimizedBacktestRunner
+__all__ = [
+    "StrategyRunner",
+    "BacktestRunner",
+    "OptimizedBacktestRunner",
+]

signalflow/strategy/runner/backtest_runner.py

@@ -0,0 +1,208 @@
+
+"""Backtest runner - orchestrates the backtesting loop."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+import polars as pl
+from loguru import logger
+
+from signalflow.core.containers.raw_data import RawData
+from signalflow.core.containers.signals import Signals
+from signalflow.core.containers.strategy_state import StrategyState
+from signalflow.core.containers.trade import Trade
+from signalflow.core.decorators import sf_component
+from signalflow.strategy.component.base import EntryRule, ExitRule, StrategyMetric
+from tqdm import tqdm
+from signalflow.strategy.runner.base import StrategyRunner
+
+@dataclass
+@sf_component(name='backtest_runner')
+class BacktestRunner(StrategyRunner):
+    """
+    Runs backtests over historical data.
+    
+    Execution flow per bar:
+        1. Mark prices on all positions
+        2. Compute metrics
+        3. Check and execute exits
+        4. Check and execute entries
+        
+    This order ensures:
+        - Metrics reflect current market state
+        - Exits are processed before entries (can close and re-enter same bar)
+        - No look-ahead bias
+    """    
+    strategy_id: str = 'backtest'
+    broker: Any = None 
+    entry_rules: list[EntryRule] = field(default_factory=list) 
+    exit_rules: list[ExitRule] = field(default_factory=list)  
+    metrics: list[StrategyMetric] = field(default_factory=list)     
+    
+    initial_capital: float = 10000.0
+    pair_col: str = 'pair'
+    ts_col: str = 'timestamp'
+    price_col: str = 'close'
+    data_key: str = 'spot'  
+    
+    _trades: list[Trade] = field(default_factory=list, init=False)
+    _metrics_history: list[dict] = field(default_factory=list, init=False)
+    
+    def run(
+        self,
+        raw_data: RawData,
+        signals: Signals,
+        state: StrategyState | None = None
+    ) -> StrategyState:
+        """
+        Run backtest over the entire dataset.
+        
+        Args:
+            raw_data: Historical OHLCV data
+            signals: Pre-computed signals for the period
+            state: Optional initial state (for continuing backtests)
+            
+        Returns:
+            Final strategy state
+        """
+        if state is None:
+            state = StrategyState(
+                strategy_id=self.strategy_id,
+            )
+            state.portfolio.cash = self.initial_capital
+        
+        self._trades = []
+        self._metrics_history = []
+        
+        # Get data
+        df = raw_data.get(self.data_key)
+        if df.height == 0:
+            logger.warning("No data to backtest")
+            return state
+        
+        timestamps = df.select(self.ts_col).unique().sort(self.ts_col).get_column(self.ts_col)
+        
+        signals_df = signals.value if signals else pl.DataFrame()
+        
+        logger.info(f"Starting backtest: {len(timestamps)} bars, {signals_df.height} signals")
+        
+        for ts in tqdm(timestamps, desc="Processing bars"):
+            state = self._process_bar(
+                ts=ts,
+                raw_df=df,
+                signals_df=signals_df,
+                state=state
+            )
+        
+        logger.info(
+            f"Backtest complete: {len(self._trades)} trades, "
+            f"{len(state.portfolio.open_positions())} open positions"
+        )
+        
+        return state
+    
+    def _process_bar(
+        self,
+        ts: datetime,
+        raw_df: pl.DataFrame,
+        signals_df: pl.DataFrame,
+        state: StrategyState
+    ) -> StrategyState:
+        """Process a single bar."""
+        state.touch(ts)
+        state.reset_tick_cache()
+        
+        bar_data = raw_df.filter(pl.col(self.ts_col) == ts)
+        prices = self._build_prices(bar_data)    
+        self.broker.mark_positions(state, prices, ts)
+        
+        all_metrics: dict[str, float] = {'timestamp': ts.timestamp()}
+        for metric in self.metrics:
+            metric_values = metric.compute(state, prices)
+            all_metrics.update(metric_values)
+        state.metrics = all_metrics
+        self._metrics_history.append(all_metrics.copy())
+        
+        exit_orders = []
+        open_positions = state.portfolio.open_positions()
+        for exit_rule in self.exit_rules:
+            orders = exit_rule.check_exits(open_positions, prices, state)
+            exit_orders.extend(orders)
+        
+        if exit_orders:
+            exit_fills = self.broker.submit_orders(exit_orders, prices, ts)
+            exit_trades = self.broker.process_fills(exit_fills, exit_orders, state)
+            self._trades.extend(exit_trades)
+        
+        bar_signals = self._get_bar_signals(signals_df, ts)
+        
+        entry_orders = []
+        for entry_rule in self.entry_rules:
+            orders = entry_rule.check_entries(bar_signals, prices, state)
+            entry_orders.extend(orders)
+        
+        if entry_orders:
+            entry_fills = self.broker.submit_orders(entry_orders, prices, ts)
+            entry_trades = self.broker.process_fills(entry_fills, entry_orders, state)
+            self._trades.extend(entry_trades)
+        
+        return state
+    
+    def _build_prices(self, bar_data: pl.DataFrame) -> dict[str, float]:
+        """Build pair -> price mapping from bar data."""
+        prices = {}
+        for row in bar_data.iter_rows(named=True):
+            pair = row.get(self.pair_col)
+            price = row.get(self.price_col)
+            if pair and price is not None:
+                prices[pair] = float(price)
+        return prices
+    
+    def _get_bar_signals(self, signals_df: pl.DataFrame, ts: datetime) -> Signals:
+        """Get signals for the current bar."""
+        if signals_df.height == 0:
+            return Signals(pl.DataFrame())
+        
+        bar_signals = signals_df.filter(pl.col(self.ts_col) == ts)
+        return Signals(bar_signals)
+    
+    @property
+    def trades(self) -> list[Trade]:
+        """Get all trades from the backtest."""
+        return self._trades
+    
+    @property
+    def trades_df(self) -> pl.DataFrame:
+        """Get trades as a DataFrame."""
+        from signalflow.core.containers.portfolio import Portfolio
+        return Portfolio.trades_to_pl(self._trades)
+    
+    @property
+    def metrics_df(self) -> pl.DataFrame:
+        """Get metrics history as a DataFrame."""
+        if not self._metrics_history:
+            return pl.DataFrame()
+        return pl.DataFrame(self._metrics_history)
+    
+    def get_results(self) -> dict[str, Any]:
+        """Get backtest results summary."""
+        trades_df = self.trades_df
+        metrics_df = self.metrics_df
+        
+        results = {
+            'total_trades': len(self._trades),
+            'metrics_df': metrics_df,
+            'trades_df': trades_df,
+        }
+        
+        if metrics_df.height > 0 and 'total_return' in metrics_df.columns:
+            results['final_return'] = metrics_df.select('total_return').tail(1).item()
+            results['final_equity'] = metrics_df.select('equity').tail(1).item()
+        
+        if trades_df.height > 0:
+            entry_trades = trades_df.filter(pl.col('meta').struct.field('type') == 'entry')
+            exit_trades = trades_df.filter(pl.col('meta').struct.field('type') == 'exit')
+            results['entry_count'] = entry_trades.height
+            results['exit_count'] = exit_trades.height
+        
+        return results

signalflow/strategy/runner/base.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import ClassVar
+from signalflow.core import SfComponentType, StrategyState, Position, Order, RawData, Signals
+from signalflow.strategy.broker.base import Broker
+from signalflow.strategy.component.base import EntryRule, ExitRule, StrategyMetric
+
+class StrategyRunner(ABC):
+    """Base class for strategy runners."""
+    component_type: ClassVar[SfComponentType] = SfComponentType.STRATEGY_RUNNER
+    broker: Broker
+    entry_rules: list[EntryRule]
+    exit_rules: list[ExitRule]
+    metrics: list[StrategyMetric]
+    
+    def run(self, raw_data: RawData, signals: Signals, state: StrategyState) -> StrategyState:
+        """Run the strategy."""
+        ...

signalflow/strategy/runner/optimized_backtest_runner.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+from signalflow.core import SfComponentType, StrategyState, Signals, sf_component
+from signalflow.strategy.component.base import EntryRule, ExitRule, StrategyMetric
+from signalflow.strategy.runner.base import StrategyRunner
+from datetime import datetime
+import polars as pl
+
+@dataclass
+@sf_component(name='backtest/optimized', override=True)
+class OptimizedBacktestRunner(StrategyRunner):
+
+    component_type = SfComponentType.STRATEGY_RUNNER
+    strategy_id: str = 'backtest'
+    broker: Any = None
+    entry_rules: list[EntryRule] = field(default_factory=list)
+    exit_rules: list = field(default_factory=list)
+    metrics: list[StrategyMetric] = field(default_factory=list)
+    initial_capital: float = 10000.0
+    pair_col: str = 'pair'
+    ts_col: str = 'timestamp'
+    price_col: str = 'close'
+    data_key: str = 'spot'
+    show_progress: bool = True
+    _trades: list = field(default_factory=list, init=False)
+    _metrics_history: list[dict] = field(default_factory=list, init=False)
+
+    def run(self, raw_data, signals: Signals, state: StrategyState | None = None):
+        from signalflow.core.containers.strategy_state import StrategyState
+        from tqdm import tqdm
+        
+        if state is None:
+            state = StrategyState(strategy_id=self.strategy_id)
+            state.portfolio.cash = self.initial_capital
+        
+        self._trades = []
+        self._metrics_history = []
+        
+        df = raw_data.get(self.data_key)
+        if df.height == 0:
+            return state
+        
+        timestamps = df.select(self.ts_col).unique().sort(self.ts_col).get_column(self.ts_col)
+        signals_df = signals.value if signals else pl.DataFrame()
+        
+        price_lookup = self._build_price_lookup(df)
+        
+        signal_lookup = self._build_signal_lookup(signals_df) if signals_df.height > 0 else {}
+        
+        iterator = tqdm(timestamps, desc='Backtesting') if self.show_progress else timestamps
+        
+        for ts in iterator:
+            state = self._process_bar_optimized(
+                ts=ts,
+                price_lookup=price_lookup,
+                signal_lookup=signal_lookup,
+                state=state
+            )
+        
+        return state
+
+    def _build_price_lookup(self, df: pl.DataFrame) -> dict[datetime, dict[str, float]]:
+        lookup = {}
+        for row in df.select([self.ts_col, self.pair_col, self.price_col]).iter_rows():
+            ts, pair, price = row
+            if ts not in lookup:
+                lookup[ts] = {}
+            lookup[ts][pair] = float(price)
+        return lookup
+
+    def _build_signal_lookup(self, signals_df: pl.DataFrame) -> dict[datetime, pl.DataFrame]:
+        lookup = {}
+        if signals_df.height == 0:
+            return lookup
+        
+        for ts in signals_df.select(self.ts_col).unique().get_column(self.ts_col):
+            lookup[ts] = signals_df.filter(pl.col(self.ts_col) == ts)
+        
+        return lookup
+
+    def _process_bar_optimized(
+        self,
+        ts: datetime,
+        price_lookup: dict[datetime, dict[str, float]],
+        signal_lookup: dict[datetime, pl.DataFrame],
+        state: StrategyState
+    ) -> StrategyState:
+        state.touch(ts)
+        state.reset_tick_cache()
+        
+        prices = price_lookup.get(ts, {})
+        
+        self.broker.mark_positions(state, prices, ts)
+        
+        all_metrics: dict[str, float] = {'timestamp': ts.timestamp()}
+        for metric in self.metrics:
+            metric_values = metric.compute(state, prices)
+            all_metrics.update(metric_values)
+        state.metrics = all_metrics
+        self._metrics_history.append(all_metrics.copy())
+        
+        exit_orders = []
+        open_positions = state.portfolio.open_positions()
+        for exit_rule in self.exit_rules:
+            orders = exit_rule.check_exits(open_positions, prices, state)
+            exit_orders.extend(orders)
+        
+        if exit_orders:
+            exit_fills = self.broker.submit_orders(exit_orders, prices, ts)
+            exit_trades = self.broker.process_fills(exit_fills, exit_orders, state)
+            self._trades.extend(exit_trades)
+        
+        bar_signals_df = signal_lookup.get(ts, pl.DataFrame())
+        bar_signals = Signals(bar_signals_df)
+        
+        entry_orders = []
+        for entry_rule in self.entry_rules:
+            orders = entry_rule.check_entries(bar_signals, prices, state)
+            entry_orders.extend(orders)
+        
+        if entry_orders:
+            entry_fills = self.broker.submit_orders(entry_orders, prices, ts)
+            entry_trades = self.broker.process_fills(entry_fills, entry_orders, state)
+            self._trades.extend(entry_trades)
+        
+        return state
+
+    @property
+    def trades(self):
+        return self._trades
+
+    @property
+    def trades_df(self) -> pl.DataFrame:
+        from signalflow.core.containers.portfolio import Portfolio
+        return Portfolio.trades_to_pl(self._trades)
+
+    @property
+    def metrics_df(self) -> pl.DataFrame:
+        if not self._metrics_history:
+            return pl.DataFrame()
+        return pl.DataFrame(self._metrics_history)
+
+    def get_results(self) -> dict[str, Any]:
+        trades_df = self.trades_df
+        metrics_df = self.metrics_df
+        
+        results = {
+            'total_trades': len(self._trades),
+            'metrics_df': metrics_df,
+            'trades_df': trades_df,
+        }
+        
+        if metrics_df.height > 0:
+            last_row = metrics_df.tail(1)
+            
+            if 'total_return' in metrics_df.columns:
+                results['final_return'] = last_row.select('total_return').item()
+            if 'equity' in metrics_df.columns:
+                results['final_equity'] = last_row.select('equity').item()
+            if 'sharpe_ratio' in metrics_df.columns:
+                results['sharpe_ratio'] = last_row.select('sharpe_ratio').item()
+            if 'max_drawdown' in metrics_df.columns:
+                results['max_drawdown'] = last_row.select('max_drawdown').item()
+            if 'win_rate' in metrics_df.columns:
+                results['win_rate'] = last_row.select('win_rate').item()
+        
+        if trades_df.height > 0:
+            entry_trades = trades_df.filter(
+                pl.col('meta').struct.field('type') == 'entry'
+            )
+            exit_trades = trades_df.filter(
+                pl.col('meta').struct.field('type') == 'exit'
+            )
+            results['entry_count'] = entry_trades.height
+            results['exit_count'] = exit_trades.height
+        
+        return results

signalflow/target/__init__.py

@@ -0,0 +1,14 @@
+from signalflow.target.base import Labeler
+from signalflow.target.fixed_horizon_labeler import FixedHorizonLabeler
+from signalflow.target.static_triple_barrier import StaticTripleBarrierLabeler
+from signalflow.target.triple_barrier import TripleBarrierLabeler
+
+import signalflow.target.adapter as adapter
+
+__all__ = [
+    "Labeler",
+    "FixedHorizonLabeler",
+    "StaticTripleBarrierLabeler",
+    "TripleBarrierLabeler",
+    "adapter",
+]

signalflow/target/adapter/__init__.py

@@ -0,0 +1,5 @@
+from signalflow.target.adapter.pandas_labeler import PandasLabeler
+
+__all__ = [
+    "PandasLabeler",
+]

signalflow/target/adapter/pandas_labeler.py

@@ -0,0 +1,45 @@
+from signalflow.target.base import Labeler
+from dataclasses import dataclass
+import pandas as pd
+import polars as pl
+from typing import Any
+from abc import abstractmethod
+
+
+@dataclass
+class PandasLabeler(Labeler):
+    """
+    Pandas-based labeling implementation, but with the SAME public interface as Labeler:
+      extract(pl.DataFrame) -> pl.DataFrame
+
+    Rules:
+      - all business logic is implemented on pandas in compute_pd_group()
+      - framework stays polars-first externally
+      - conversion happens:
+          pl group -> pandas group -> pandas out -> polars out
+    """
+
+    def compute_group(self, group_df: pl.DataFrame, data_context: dict[str, Any] | None) -> pl.DataFrame:
+        pd_in = group_df.to_pandas()
+        pd_out = self.compute_pd_group(pd_in, data_context=data_context)
+
+        if not isinstance(pd_out, pd.DataFrame):
+            raise TypeError(f"{self.__class__.__name__}.compute_pd_group must return pd.DataFrame")
+        if len(pd_out) != group_df.height:
+            raise ValueError(
+                f"{self.__class__.__name__}: len(output_group)={len(pd_out)} != len(input_group)={group_df.height}"
+            )
+
+        # IMPORTANT: ensure column order + row order preserved by user implementation
+        return pl.from_pandas(pd_out, include_index=False)
+
+    @abstractmethod
+    def compute_pd_group(self, group_df: pd.DataFrame, data_context: dict[str, Any] | None) -> pd.DataFrame:
+        """
+        Pandas labeling per pair.
+
+        MUST:
+          - preserve row order
+          - preserve row count (no filtering)
+        """
+        raise NotImplementedError