signalflow-trading 0.2.1__py3-none-any.whl

signalflow/feature/pandasta/pandas_ta_extractor.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import pandas as pd
+
+from signalflow.feature.adapter.pandas_feature_extractor import PandasFeatureExtractor
+from signalflow.core import sf_component
+
+
+@dataclass
+@sf_component(name="pta")
+class PandasTaExtractor(PandasFeatureExtractor):
+    """
+    Polars-first Pandas-TA adapter.
+
+    This extractor runs pandas-ta inside `pandas_group_fn` per (pair, resample_offset) group,
+    then merges produced feature columns back into the Polars pipeline.
+
+    Key guarantees:
+      - pandas-ta output is normalized to pd.DataFrame
+      - output length matches input group length
+      - output columns are namespaced to avoid collisions across extractors
+    """
+
+    indicator: str = "rsi"
+    params: dict[str, Any] = field(default_factory=dict)
+
+    input_column: str = "close"
+    additional_inputs: dict[str, str] = field(default_factory=dict)
+
+    feature_prefix: str | None = None
+
+    def __post_init__(self) -> None:
+        try:
+            import pandas_ta as _  
+        except ImportError as e:
+            raise ImportError("pandas-ta is required. Install with: pip install pandas-ta") from e
+
+        if not isinstance(self.indicator, str) or not self.indicator.strip():
+            raise ValueError("indicator name must be a non-empty string")
+
+        if not isinstance(self.input_column, str) or not self.input_column.strip():
+            raise ValueError("input_column must be a non-empty string")
+
+        if not isinstance(self.params, dict):
+            raise TypeError(f"params must be dict[str, Any], got {type(self.params)}")
+
+        if not isinstance(self.additional_inputs, dict):
+            raise TypeError(f"additional_inputs must be dict[str, str], got {type(self.additional_inputs)}")
+
+        for k, v in self.additional_inputs.items():
+            if not isinstance(k, str) or not k.strip():
+                raise TypeError(f"additional_inputs keys must be non-empty str, got {k!r}")
+            if not isinstance(v, str) or not v.strip():
+                raise TypeError(f"additional_inputs values must be non-empty str column names, got {v!r}")
+
+        self.pandas_group_fn = self._pandas_ta_group_fn
+
+        super().__post_init__()
+
+    def _pandas_ta_group_fn(self, group: pd.DataFrame, ctx: dict[str, Any] | None) -> pd.DataFrame:
+        import pandas_ta as ta
+
+        self._validate_required_columns(group)
+
+        try:
+            indicator_func = getattr(ta, self.indicator)
+        except AttributeError as e:
+            raise AttributeError(f"Indicator '{self.indicator}' not found in pandas-ta.") from e
+
+        kwargs = dict(self.params)
+
+        primary_input = group[self.input_column]
+        for param_name, column_name in self.additional_inputs.items():
+            kwargs[param_name] = group[column_name]
+
+        out = indicator_func(primary_input, **kwargs)
+
+        out_df = self._normalize_output(out, group_len=len(group))
+        out_df = self._namespace_columns(out_df)
+
+        return out_df
+
+    def _validate_required_columns(self, df: pd.DataFrame) -> None:
+        required = [self.input_column, *self.additional_inputs.values()]
+        missing = sorted(set(required) - set(df.columns))
+        if missing:
+            raise ValueError(f"Missing required columns for pandas-ta: {missing}")
+
+    def _normalize_output(self, out: Any, group_len: int) -> pd.DataFrame:
+        """
+        Normalize pandas-ta output to pd.DataFrame and ensure length matches group.
+        """
+        if isinstance(out, pd.Series):
+            out_df = out.to_frame()
+            col = out_df.columns[0]
+            if col is None or (isinstance(col, str) and not col.strip()):
+                out_df.columns = [self.indicator]
+        elif isinstance(out, pd.DataFrame):
+            out_df = out
+            if out_df.columns.isnull().any():
+                out_df = out_df.copy()
+                out_df.columns = [
+                    c if (c is not None and (not isinstance(c, str) or c.strip())) else f"{self.indicator}_{i}"
+                    for i, c in enumerate(out_df.columns)
+                ]
+        else:
+            raise TypeError(
+                f"pandas-ta '{self.indicator}' returned unsupported type: {type(out)}. "
+                f"Expected pd.Series or pd.DataFrame."
+            )
+
+        if len(out_df) != group_len:
+            raise ValueError(
+                f"{self.__class__.__name__}: len(output_group)={len(out_df)} != len(input_group)={group_len}"
+            )
+
+        return out_df
+
+    def _namespace_columns(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Prefix output columns to avoid collisions across different indicators/extractors.
+        """
+        prefix = self.feature_prefix or self.indicator
+        prefix = str(prefix).strip()
+
+        df = df.copy()
+        new_cols: list[str] = []
+        for i, c in enumerate(df.columns):
+            name = str(c) if c is not None else f"{self.indicator}_{i}"
+            name = name.strip() or f"{self.indicator}_{i}"
+
+            if name == prefix or name.startswith(prefix + "_"):
+                new_cols.append(name)
+            else:
+                new_cols.append(f"{prefix}_{name}")
+
+        df.columns = new_cols
+        return df

signalflow/feature/pandasta/top_pandasta_extractors.py

@@ -0,0 +1,64 @@
+
+
+from dataclasses import dataclass
+from signalflow.feature.pandasta.pandas_ta_extractor import PandasTaExtractor
+from signalflow.core import sf_component
+
+
+@dataclass
+@sf_component(name="pta/rsi")
+class PandasTaRsiExtractor(PandasTaExtractor):
+    length: int = 14
+
+    def __post_init__(self) -> None:
+        self.indicator = "rsi"
+        self.params = {"length": int(self.length)}
+        self.input_column = "close"
+        self.additional_inputs = {}
+        self.feature_prefix = "rsi"
+        super().__post_init__()
+
+
+@dataclass
+@sf_component(name="pta/bbands")
+class PandasTaBbandsExtractor(PandasTaExtractor):
+    length: int = 20
+    std: float = 2.0
+
+    def __post_init__(self) -> None:
+        self.indicator = "bbands"
+        self.params = {"length": int(self.length), "std": float(self.std)}
+        self.input_column = "close"
+        self.additional_inputs = {}
+        self.feature_prefix = f"bbands_{int(self.length)}_{float(self.std)}"
+        super().__post_init__()
+
+
+@dataclass
+@sf_component(name="pta/macd")
+class PandasTaMacdExtractor(PandasTaExtractor):
+    fast: int = 12
+    slow: int = 26
+    signal: int = 9
+
+    def __post_init__(self) -> None:
+        self.indicator = "macd"
+        self.params = {"fast": int(self.fast), "slow": int(self.slow), "signal": int(self.signal)}
+        self.input_column = "close"
+        self.additional_inputs = {}
+        self.feature_prefix = f"macd_{int(self.fast)}_{int(self.slow)}_{int(self.signal)}"
+        super().__post_init__()
+
+
+@dataclass
+@sf_component(name="pta/atr")
+class PandasTaAtrExtractor(PandasTaExtractor):
+    length: int = 14
+
+    def __post_init__(self) -> None:
+        self.indicator = "atr"
+        self.params = {"length": int(self.length)}
+        self.input_column = "high"
+        self.additional_inputs = {"low": "low", "close": "close"}
+        self.feature_prefix = f"atr_{int(self.length)}"
+        super().__post_init__()

signalflow/feature/smoother/__init__.py

@@ -0,0 +1,5 @@
+from signalflow.feature.smoother.sma_extractor import SmaExtractor
+
+__all__ = [
+    "SmaExtractor",
+]   

signalflow/feature/smoother/sma_extractor.py

@@ -0,0 +1,46 @@
+# src/signalflow/feature/extractor/sma_extractor.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+import polars as pl
+
+
+from signalflow.feature.base import FeatureExtractor
+from signalflow.core import sf_component
+
+
+@dataclass
+@sf_component(name="smooth/sma")
+class SmaExtractor(FeatureExtractor):
+    """
+    SMA per (pair, resample_offset) group.
+
+    Notes:
+    - offset_window here is for RollingAggregator (your framework requirement).
+      SMA window is `sma_period`.
+    - In v1 you said only spot -> keep data_type="spot" by default.
+    """
+    offset_window: int = 1
+    use_resample: bool = True
+
+    sma_period: int = 20
+    price_col: str = "close"
+    out_col: str = "sma"
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if self.sma_period <= 0:
+            raise ValueError(f"sma_period must be > 0, got {self.sma_period}")
+        if not self.out_col:
+            self.out_col = "sma"
+
+    def compute_group(self, group_df: pl.DataFrame, data_context: dict | None) -> pl.DataFrame:
+        if self.price_col not in group_df.columns:
+            raise ValueError(f"Missing required column: {self.price_col}")
+
+        sma = (
+            pl.col(self.price_col)
+            .rolling_mean(window_size=self.sma_period, min_samples=self.sma_period)
+            .alias(self.out_col)
+        )
+        return group_df.with_columns(sma)

signalflow/strategy/__init__.py

@@ -0,0 +1,9 @@
+import signalflow.strategy.broker as broker
+import signalflow.strategy.component as component
+import signalflow.strategy.runner as runner
+
+__all__ = [
+    "broker",
+    "component",
+    "runner",
+]

signalflow/strategy/broker/__init__.py

@@ -0,0 +1,15 @@
+"""
+SignalFlow Broker Module.
+
+Broker handles order execution and state persistence.
+"""
+import signalflow.strategy.broker.executor as executor
+from signalflow.strategy.broker.base import Broker
+from signalflow.strategy.broker.backtest import BacktestBroker
+
+
+__all__ = [
+    "executor",
+    "Broker",
+    "BacktestBroker",
+]

signalflow/strategy/broker/backtest.py

@@ -0,0 +1,172 @@
+"""Backtest broker implementation."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import ClassVar
+import uuid
+
+from signalflow.core.enums import SfComponentType, PositionType
+from signalflow.core.decorators import sf_component
+from signalflow.core.containers.position import Position
+from signalflow.core.containers.trade import Trade
+from signalflow.core.containers.order import Order, OrderFill
+from signalflow.core.containers.strategy_state import StrategyState
+from signalflow.strategy.broker.base import Broker
+from signalflow.strategy.broker.executor.base import OrderExecutor
+from signalflow.data.strategy_store.base import StrategyStore
+
+
+@dataclass
+@sf_component(name='backtest', override=True)
+class BacktestBroker(Broker):
+    """
+    Broker for backtesting - handles order execution, position management, and state persistence.
+    
+    Execution flow:
+        1. Mark prices on positions
+        2. Submit orders -> get fills
+        3. Apply fills to positions
+        4. Persist state
+    """
+    component_type: ClassVar[SfComponentType] = SfComponentType.STRATEGY_BROKER
+    
+    def create_position(self, order: Order, fill: OrderFill) -> Position:
+        """Create a new position from an order fill."""
+        # Determine position type from order side
+        position_type = PositionType.LONG if order.side == 'BUY' else PositionType.SHORT
+        
+        position = Position(
+            id=str(uuid.uuid4()),
+            is_closed=False,
+            pair=fill.pair,
+            position_type=position_type,
+            signal_strength=order.signal_strength,
+            entry_time=fill.ts,
+            last_time=fill.ts,
+            entry_price=fill.price,
+            last_price=fill.price,
+            qty=fill.qty,
+            fees_paid=fill.fee,
+            realized_pnl=0.0,
+            meta={
+                'order_id': order.id,
+                'fill_id': fill.id,
+                **order.meta
+            }
+        )
+        return position
+    
+    def apply_fill_to_position(self, position: Position, fill: OrderFill) -> None:
+        """Apply a fill to an existing position."""
+        trade = Trade(
+            id=fill.id,
+            position_id=position.id,
+            pair=fill.pair,
+            side=fill.side,
+            ts=fill.ts,
+            price=fill.price,
+            qty=fill.qty,
+            fee=fill.fee,
+            meta=fill.meta
+        )
+        position.apply_trade(trade)
+
+    def process_fills(
+        self, 
+        fills: list[OrderFill], 
+        orders: list[Order], 
+        state: StrategyState
+    ) -> list[Trade]:
+        """
+        Process fills and UPDATE CASH BALANCE.
+        
+        FIX: Properly update portfolio.cash when opening/closing positions
+        """
+        trades: list[Trade] = []
+        order_map = {o.id: o for o in orders}
+        
+        for fill in fills:
+            order = order_map.get(fill.order_id)
+            if order is None:
+                continue
+            
+            notional = fill.price * fill.qty
+            
+            if fill.position_id and fill.position_id in state.portfolio.positions:
+                position = state.portfolio.positions[fill.position_id]
+                self.apply_fill_to_position(position, fill)
+                
+                if fill.side == 'SELL':
+                    state.portfolio.cash += (notional - fill.fee)
+                elif fill.side == 'BUY':
+                    state.portfolio.cash -= (notional + fill.fee)
+                
+                trade = Trade(
+                    id=fill.id,
+                    position_id=position.id,
+                    pair=fill.pair,
+                    side=fill.side,
+                    ts=fill.ts,
+                    price=fill.price,
+                    qty=fill.qty,
+                    fee=fill.fee,
+                    meta={'type': 'exit', **fill.meta}
+                )
+                trades.append(trade)
+                
+            else:
+                position = self.create_position(order, fill)
+                state.portfolio.positions[position.id] = position
+                
+                if fill.side == 'BUY':
+                    state.portfolio.cash -= (notional + fill.fee)
+                elif fill.side == 'SELL':
+                    state.portfolio.cash += (notional - fill.fee)
+                
+                trade = Trade(
+                    id=fill.id,
+                    position_id=position.id,
+                    pair=fill.pair,
+                    side=fill.side,
+                    ts=fill.ts,
+                    price=fill.price,
+                    qty=fill.qty,
+                    fee=fill.fee,
+                    meta={'type': 'entry', **fill.meta}
+                )
+                trades.append(trade)
+        
+        return trades
+    
+    def mark_positions(
+        self,
+        state: StrategyState,
+        prices: dict[str, float],
+        ts: datetime
+    ) -> None:
+        """Mark all open positions to current prices."""
+        for position in state.portfolio.open_positions():
+            price = prices.get(position.pair)
+            if price is not None and price > 0:
+                position.mark(ts=ts, price=price)
+    
+    def get_open_position_for_pair(
+        self,
+        state: StrategyState,
+        pair: str
+    ) -> Position | None:
+        """Get open position for a specific pair, if any."""
+        for pos in state.portfolio.open_positions():
+            if pos.pair == pair:
+                return pos
+        return None
+    
+    def get_open_positions_by_pair(
+        self,
+        state: StrategyState
+    ) -> dict[str, Position]:
+        """Get dict of pair -> open position."""
+        return {
+            pos.pair: pos
+            for pos in state.portfolio.open_positions()
+        }

signalflow/strategy/broker/base.py

@@ -0,0 +1,186 @@
+"""
+SignalFlow Broker Base.
+
+Broker is the bridge between Strategy (business logic) and execution.
+It handles:
+    - Order execution (backtest or live)
+    - State persistence
+    - Fill synchronization
+    
+Key principle: Portfolio changes ONLY through fills.
+Strategy generates intents (orders), Broker executes them.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from signalflow.strategy.broker.executor.base import OrderExecutor
+from signalflow.data.strategy_store.base import StrategyStore
+from signalflow.core import Position, Order, OrderFill, StrategyState
+from signalflow.core.enums import SfComponentType
+from typing import ClassVar
+
+
+@dataclass
+class Broker(ABC):
+    """
+    Base Broker class.
+    
+    Combines execution and storage. Single source of truth through fills:
+    - Strategy generates orders (intents)
+    - Broker executes them and returns fills
+    - Fills are the ONLY way portfolio changes
+    
+    This design ensures:
+    - Clean separation between intent and execution
+    - Easy switch from backtest to live (just swap executor)
+    - Proper state recovery on restart
+    
+    Attributes:
+        executor: Order execution implementation
+        store: State persistence implementation
+        fee_rate: Trading fee rate (e.g., 0.001 = 0.1%)
+    """
+
+    component_type: ClassVar[SfComponentType] = SfComponentType.STRATEGY_BROKER 
+    executor: OrderExecutor
+    store: StrategyStore
+    fee_rate: float = 0.001
+    
+    _pending_fills: list[OrderFill] = field(default_factory=list)
+
+    
+    def submit_orders(
+        self,
+        orders: list[Order],
+        prices: dict[str, float],
+        ts: datetime,
+    ) -> list[OrderFill]:
+        """
+        Submit orders for execution.
+        
+        Args:
+            orders: Orders to execute
+            prices: Current prices per pair
+            ts: Current timestamp
+            
+        Returns:
+            List of fills from execution
+        """
+        if not orders:
+            return []
+        
+        fills = self.executor.execute(orders, prices, ts)
+        
+        # Persist fills
+        if fills:
+            strategy_id = self._get_strategy_id(orders)
+            if strategy_id:
+                self.store.save_fills(strategy_id, fills)
+        
+        return fills
+    
+    def _get_strategy_id(self, orders: list[Order]) -> str | None:
+        """Extract strategy_id from orders metadata."""
+        for order in orders:
+            if "strategy_id" in order.meta:
+                return order.meta["strategy_id"]
+        return None
+
+    
+    def sync_fills(self) -> list[OrderFill]:
+        """
+        Synchronize fills from external source.
+        
+        For backtest: returns empty (fills are immediate)
+        For live: returns fills that arrived since last sync
+        
+        Returns:
+            List of new fills
+        """
+        fills = list(self._pending_fills)
+        self._pending_fills.clear()
+        return fills
+    
+    def add_pending_fill(self, fill: OrderFill) -> None:
+        """Add fill to pending queue (for live executor callbacks)."""
+        self._pending_fills.append(fill)
+    
+    def persist_state(self, state: StrategyState) -> None:
+        """
+        Persist current strategy state.
+        
+        Called at end of each tick to save:
+        - Portfolio state
+        - Positions
+        - Metrics
+        """
+        self.store.save_state(state)
+        self.store.save_positions(
+            state.strategy_id, 
+            list(state.positions.values())
+        )
+        if state.last_ts and state.all_metrics:
+            self.store.save_metrics(
+                state.strategy_id,
+                state.last_ts,
+                state.all_metrics,
+            )
+    
+    def restore_state(self, strategy_id: str) -> StrategyState:
+        """
+        Restore strategy state from storage.
+        
+        Called on startup to recover from last known state.
+        
+        Args:
+            strategy_id: Strategy to restore
+            
+        Returns:
+            Restored state (or fresh state if not found)
+        """
+        state = self.store.load_state(strategy_id)
+        
+        if state is None:
+            return StrategyState(strategy_id=strategy_id)
+        
+        positions = self.store.load_positions(strategy_id, open_only=False)
+        state.portfolio.positions = {p.id: p for p in positions}
+        
+        return state
+    
+    @abstractmethod
+    def create_position(
+        self,
+        order: Order,
+        fill: OrderFill,
+    ) -> Position:
+        """
+        Create new position from order and fill.
+        
+        Args:
+            order: Original open order
+            fill: Execution fill
+            
+        Returns:
+            New Position instance
+        """
+        ...
+    
+    @abstractmethod
+    def apply_fill_to_position(
+        self,
+        position: Position,
+        fill: OrderFill,
+    ) -> None:
+        """
+        Apply fill to existing position.
+        
+        Mutates position in-place.
+        
+        Args:
+            position: Position to update
+            fill: Fill to apply
+        """
+        ...

signalflow/strategy/broker/executor/__init__.py

@@ -0,0 +1,9 @@
+from signalflow.strategy.broker.executor.base import OrderExecutor
+from signalflow.strategy.broker.executor.binance_spot import BinanceSpotExecutor
+from signalflow.strategy.broker.executor.virtual_spot import VirtualSpotExecutor
+
+__all__ = [
+    "OrderExecutor",
+    "BinanceSpotExecutor",
+    "VirtualSpotExecutor",
+]

signalflow/strategy/broker/executor/base.py

@@ -0,0 +1,35 @@
+from signalflow.core import Order, OrderFill, SfComponentType
+from datetime import datetime
+from typing import Protocol, ClassVar
+
+class OrderExecutor(Protocol):
+    component_type: ClassVar[SfComponentType] = SfComponentType.STRATEGY_EXECUTOR
+    """
+    Protocol for order execution.
+    
+    Implementations:
+        - VirtualExecutor: Simulates fills at current prices
+        - LiveExecutor: Submits orders to exchange
+        - BinanceExecutor(LiveExecutor): Submits orders to Binance
+    """
+    
+    def execute(
+        self,
+        orders: list[Order],
+        prices: dict[str, float],
+        ts: datetime,
+    ) -> list[OrderFill]:
+        """
+        Execute orders and return fills.
+        
+        Args:
+            orders: List of orders to execute
+            prices: Current prices per pair
+            ts: Current timestamp
+            
+        Returns:
+            List of fills (may be empty if orders rejected)
+        """
+        ...
+
+