signalflow-trading 0.2.1__py3-none-any.whl

signalflow/core/containers/raw_data_view.py

@@ -0,0 +1,169 @@
+from dataclasses import dataclass, field
+import pandas as pd
+import polars as pl
+from .raw_data import RawData
+from signalflow.core.enums import DataFrameType
+
+# TODO raw_data_type -> RawDataType
+
+@dataclass
+class RawDataView:
+    """Adapter for accessing RawData in different DataFrame formats.
+
+    Provides unified interface for converting between Polars and Pandas formats,
+    with optional caching for Pandas conversions.
+
+    Key features:
+        - Lazy conversion: Polars → Pandas only when needed
+        - Optional caching for repeated Pandas access
+        - Automatic timestamp normalization
+        - Automatic sorting by (pair, timestamp)
+
+    Attributes:
+        raw (RawData): Underlying raw data container.
+        cache_pandas (bool): Enable caching for Pandas conversions. Default: False.
+        _pandas_cache (dict[str, pd.DataFrame]): Internal cache for Pandas DataFrames.
+
+    Example:
+        ```python
+        from signalflow.core import RawData, RawDataView
+
+        # Create view
+        view = RawDataView(raw=raw_data, cache_pandas=True)
+
+        # Access as Polars (zero-copy)
+        spot_pl = view.to_polars("spot")
+
+        # Access as Pandas (cached)
+        spot_pd = view.to_pandas("spot")
+
+        # Unified interface
+        from signalflow.core.enums import DataFrameType
+        data = view.get_data("spot", DataFrameType.POLARS)
+        ```
+
+    Note:
+        Polars access is zero-copy. Pandas conversion creates a copy.
+        Enable cache_pandas for repeated Pandas access to same dataset.
+    """
+
+    raw: RawData
+    cache_pandas: bool = False
+    _pandas_cache: dict[str, pd.DataFrame] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Initialize internal cache if needed."""
+        if self._pandas_cache is None:
+            self._pandas_cache = {}
+
+    def to_polars(self, key: str) -> pl.DataFrame:
+        """Get dataset as Polars DataFrame.
+
+        Zero-copy access to underlying Polars DataFrame in RawData.
+
+        Args:
+            key (str): Dataset name (e.g. "spot", "signals").
+
+        Returns:
+            pl.DataFrame: Dataset as Polars DataFrame.
+
+        Example:
+            ```python
+            spot_df = view.to_polars("spot")
+            print(f"Shape: {spot_df.shape}")
+            ```
+        """
+        return self.raw[key]
+
+    def to_pandas(self, key: str) -> pd.DataFrame:
+        """Get dataset as Pandas DataFrame.
+
+        Converts Polars DataFrame to Pandas with:
+            - Timestamp normalization (UTC-aware → naive)
+            - Automatic sorting by (pair, timestamp)
+            - Optional caching for repeated access
+
+        Args:
+            key (str): Dataset name (e.g. "spot", "signals").
+
+        Returns:
+            pd.DataFrame: Dataset as Pandas DataFrame, sorted and normalized.
+
+        Example:
+            ```python
+            # First access: converts and caches (if enabled)
+            spot_df = view.to_pandas("spot")
+
+            # Second access: returns cached version (if cache enabled)
+            spot_df_again = view.to_pandas("spot")
+
+            # Check timestamp type
+            print(spot_df["timestamp"].dtype)  # datetime64[ns]
+            ```
+
+        Note:
+            Returns empty DataFrame if dataset doesn't exist.
+            Timestamp column is converted to timezone-naive datetime64[ns].
+        """
+        df_pl = self.to_polars(key)
+        if df_pl.is_empty():
+            return pd.DataFrame()
+
+        if self.cache_pandas and key in self._pandas_cache:
+            df = self._pandas_cache[key]
+        else:
+            df = df_pl.to_pandas()
+            if self.cache_pandas:
+                self._pandas_cache[key] = df
+
+        if "timestamp" in df.columns:
+            df["timestamp"] = pd.to_datetime(df["timestamp"], utc=False, errors="raise")
+
+        if {"pair", "timestamp"}.issubset(df.columns):
+            df = df.sort_values(["pair", "timestamp"], kind="stable").reset_index(drop=True)
+
+        return df
+
+    def get_data(
+        self, 
+        raw_data_type: str, 
+        df_type: DataFrameType
+    ) -> pl.DataFrame | pd.DataFrame:
+        """Get raw data in specified format.
+        
+        Unified interface for accessing data in required DataFrame format.
+        Used by FeatureSet to get data in format expected by extractors.
+        
+        Args:
+            raw_data_type (str): Type of data ('spot', 'futures', 'perpetual').
+            df_type (DataFrameType): Target DataFrame type (POLARS or PANDAS).
+            
+        Returns:
+            pl.DataFrame | pd.DataFrame: Dataset in requested format.
+
+        Raises:
+            ValueError: If df_type is not POLARS or PANDAS.
+            
+        Example:
+            ```python
+            from signalflow.core.enums import DataFrameType
+
+            # Get as Polars
+            spot_pl = view.get_data('spot', DataFrameType.POLARS)
+
+            # Get as Pandas
+            spot_pd = view.get_data('spot', DataFrameType.PANDAS)
+
+            # Used by FeatureExtractor
+            class MyExtractor(FeatureExtractor):
+                def extract(self, df):
+                    # df will be in format specified by df_type
+                    pass
+            ```
+        """
+        if df_type == DataFrameType.POLARS:
+            return self.to_polars(raw_data_type)   
+        elif df_type == DataFrameType.PANDAS:
+            return self.to_pandas(raw_data_type)
+        else:
+            raise ValueError(f"Unsupported df_type: {df_type}")

signalflow/core/containers/signals.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import polars as pl
+from signalflow.core.signal_transforms import SignalsTransform
+from signalflow.core.enums import SignalType
+
+
+@dataclass(frozen=True)
+class Signals:
+    """Immutable container for trading signals.
+
+    Canonical in-memory format is a Polars DataFrame with long schema.
+
+    Required columns:
+        - pair (str): Trading pair identifier
+        - timestamp (datetime): Signal timestamp
+        - signal_type (SignalType | int): Signal type (RISE, FALL, NONE)
+        - signal (int | float): Signal value
+
+    Optional columns:
+        - probability (float): Signal probability (required for merge logic)
+
+    Attributes:
+        value (pl.DataFrame): Polars DataFrame containing signal data.
+
+    Example:
+        ```python
+        from signalflow.core import Signals, SignalType
+        import polars as pl
+        from datetime import datetime
+
+        # Create signals
+        signals_df = pl.DataFrame({
+            "pair": ["BTCUSDT", "ETHUSDT"],
+            "timestamp": [datetime.now(), datetime.now()],
+            "signal_type": [SignalType.RISE.value, SignalType.FALL.value],
+            "signal": [1, -1],
+            "probability": [0.8, 0.7]
+        })
+
+        signals = Signals(signals_df)
+
+        # Apply transformation
+        filtered = signals.apply(filter_transform)
+
+        # Chain transformations
+        processed = signals.pipe(
+            transform1,
+            transform2,
+            transform3
+        )
+
+        # Merge signals
+        combined = signals1 + signals2
+        ```
+
+    Note:
+        All transformations return new Signals instance.
+        No in-place mutation is allowed.
+    """
+
+    value: pl.DataFrame
+
+    def apply(self, transform: SignalsTransform) -> "Signals":
+        """Apply a single transformation to signals.
+
+        Args:
+            transform (SignalsTransform): Callable transformation implementing
+                SignalsTransform protocol.
+
+        Returns:
+            Signals: New Signals instance with transformed data.
+
+        Example:
+            ```python
+            from signalflow.core import Signals
+            import polars as pl
+
+            def filter_high_probability(df: pl.DataFrame) -> pl.DataFrame:
+                return df.filter(pl.col("probability") > 0.7)
+
+            filtered = signals.apply(filter_high_probability)
+            ```
+        """
+        out = transform(self.value)
+        return Signals(out)
+
+    def pipe(self, *transforms: SignalsTransform) -> "Signals":
+        """Apply multiple transformations sequentially.
+
+        Args:
+            *transforms (SignalsTransform): Sequence of transformations to apply in order.
+
+        Returns:
+            Signals: New Signals instance after applying all transformations.
+
+        Example:
+            ```python
+            result = signals.pipe(
+                filter_none_signals,
+                normalize_probabilities,
+                add_metadata
+            )
+            ```
+        """
+        s = self
+        for t in transforms:
+            s = s.apply(t)
+        return s
+
+
+    def __add__(self, other: "Signals") -> "Signals":
+        """Merge two Signals objects.
+
+        Merge rules:
+            1. Key: (pair, timestamp)
+            2. Signal type priority:
+               - SignalType.NONE has lowest priority
+               - Non-NONE always overrides NONE
+               - If both non-NONE, `other` wins
+            3. SignalType.NONE normalized to probability = 0
+            4. Merge is deterministic
+
+        Args:
+            other (Signals): Another Signals object to merge.
+
+        Returns:
+            Signals: New merged Signals instance.
+
+        Raises:
+            TypeError: If other is not a Signals instance.
+
+        Example:
+            ```python
+            # Detector 1 signals
+            signals1 = detector1.run(data)
+
+            # Detector 2 signals
+            signals2 = detector2.run(data)
+
+            # Merge with priority to signals2
+            merged = signals1 + signals2
+
+            # NONE signals overridden by non-NONE
+            # Non-NONE conflicts resolved by taking signals2
+            ```
+        """
+        if not isinstance(other, Signals):
+            return NotImplemented
+
+        a = self.value
+        b = other.value
+
+        all_cols = list(dict.fromkeys([*a.columns, *b.columns]))
+
+        def align(df: pl.DataFrame) -> pl.DataFrame:
+            return (
+                df.with_columns(
+                    [pl.lit(None).alias(c) for c in all_cols if c not in df.columns]
+                )
+                .select(all_cols)
+            )
+
+        a = align(a).with_columns(pl.lit(0).alias("_src"))
+        b = align(b).with_columns(pl.lit(1).alias("_src"))
+
+        merged = pl.concat([a, b], how="vertical")
+
+        merged = merged.with_columns(
+            pl.when(pl.col("signal_type") == SignalType.NONE.value)
+            .then(pl.lit(0))
+            .otherwise(pl.col("probability"))
+            .alias("probability")
+        )
+
+        merged = merged.with_columns(
+            pl.when(pl.col("signal_type") == SignalType.NONE.value)
+            .then(pl.lit(0))
+            .otherwise(pl.lit(1))
+            .alias("_priority")
+        )
+
+        merged = (
+            merged
+            .sort(
+                ["pair", "timestamp", "_priority", "_src"],
+                descending=[False, False, True, True],
+            )
+            .unique(
+                subset=["pair", "timestamp"],
+                keep="first",
+            )
+            .drop(["_priority", "_src"])
+            .sort(["pair", "timestamp"])
+        )
+
+        return Signals(merged)

signalflow/core/containers/strategy_state.py

@@ -0,0 +1,147 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from signalflow.core.containers import Portfolio
+
+
+@dataclass(slots=True)
+class StrategyState:
+    """Single source of truth for strategy runtime state.
+
+    Mutable aggregate that tracks all strategy state including portfolio,
+    runtime context, metrics, and execution watermarks.
+
+    Lives in `signalflow.core` so both `signalflow.strategy` (logic/execution)
+    and `signalflow.data` (persistence) can depend on it without cycles.
+
+    State components:
+        - portfolio: Canonical portfolio state (cash + positions)
+        - runtime: Flexible bag for cooldowns, watermarks, guards
+        - metrics: Latest computed metrics snapshot
+        - watermarks: Last processed timestamp and event for idempotency
+
+    Attributes:
+        strategy_id (str): Unique strategy identifier.
+        last_ts (datetime | None): Last processed timestamp.
+        last_event_id (str | None): Last processed event ID (for live idempotency/resume).
+        portfolio (Portfolio): Current portfolio state.
+        runtime (dict[str, Any]): Runtime context (cooldowns, guards, etc.).
+        metrics (dict[str, float]): Latest metrics snapshot.
+        metrics_phase_done (set[str]): Phase completion tracking for metrics.
+
+    Example:
+        ```python
+        from signalflow.core import StrategyState, Portfolio
+        from datetime import datetime
+
+        # Initialize state
+        state = StrategyState(strategy_id="my_strategy")
+        state.portfolio.cash = 10000.0
+
+        # Process bar
+        state.touch(ts=datetime(2024, 1, 1, 10, 0))
+        state.metrics["total_return"] = 0.05
+        state.runtime["last_signal"] = "sma_cross"
+
+        # Save and resume
+        saved_state = save_to_db(state)
+        resumed_state = load_from_db(strategy_id="my_strategy")
+        
+        # Continue from last watermark
+        print(f"Resuming from: {resumed_state.last_ts}")
+
+        # Phase-gated metrics
+        state.reset_tick_cache()
+        # ... compute metrics for new tick ...
+        state.metrics_phase_done.add("returns")
+        ```
+
+    Note:
+        State should be persisted regularly for recovery.
+        All portfolio changes flow through fills, not direct modification.
+        Use touch() to update watermarks after successful tick commit.
+    """
+
+    strategy_id: str
+
+    last_ts: Optional[datetime] = None
+    last_event_id: Optional[str] = None
+
+    portfolio: Portfolio = field(default_factory=Portfolio)
+
+    runtime: Dict[str, Any] = field(default_factory=dict)
+    metrics: Dict[str, float] = field(default_factory=dict)
+
+    metrics_phase_done: set[str] = field(default_factory=set)
+
+    def touch(self, ts: datetime, event_id: Optional[str] = None) -> None:
+        """Update watermarks after successful tick commit.
+
+        Updates last_ts and optionally last_event_id to track processing progress.
+        Used for resume/recovery and live idempotency.
+
+        Args:
+            ts (datetime): Timestamp of successfully processed tick.
+            event_id (str | None): Optional event ID for idempotency tracking.
+
+        Example:
+            ```python
+            # Process bar successfully
+            for bar in bars:
+                # ... process trading logic ...
+                
+                # Commit and update watermarks
+                state.touch(ts=bar.timestamp)
+                save_to_db(state)
+
+            # Live trading with event IDs
+            for event in event_stream:
+                # ... process event ...
+                
+                # Track event for idempotency
+                state.touch(ts=event.timestamp, event_id=event.id)
+                save_to_db(state)
+            ```
+
+        Note:
+            Call after successful tick processing and before persistence.
+            Enables safe resume from last committed state.
+        """
+        self.last_ts = ts
+        if event_id is not None:
+            self.last_event_id = event_id
+
+    def reset_tick_cache(self) -> None:
+        """Clear phase completion tracking for new tick.
+
+        Resets metrics_phase_done set at the start of each tick
+        for phase-gated metrics computation.
+
+        Use when computing metrics incrementally across phases
+        (e.g., pre-trade, post-trade, end-of-bar).
+
+        Example:
+            ```python
+            # At start of each tick
+            state.reset_tick_cache()
+
+            # Phase 1: Pre-trade metrics
+            if "returns" not in state.metrics_phase_done:
+                compute_return_metrics(state)
+                state.metrics_phase_done.add("returns")
+
+            # Phase 2: Post-trade metrics
+            if "drawdown" not in state.metrics_phase_done:
+                compute_drawdown_metrics(state)
+                state.metrics_phase_done.add("drawdown")
+
+            # Next tick - reset and recompute
+            state.reset_tick_cache()
+            ```
+
+        Note:
+            Only needed if using phase-gated metrics pattern.
+            Otherwise, metrics_phase_done can be ignored.
+        """
+        self.metrics_phase_done.clear()

signalflow/core/containers/trade.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Iterable, Literal
+
+import polars as pl
+
+TradeSide = Literal["BUY", "SELL"]
+
+@dataclass(frozen=True, slots=True)
+class Trade:
+    """Immutable domain event representing an executed trade.
+
+    A Trade is a fact: it happened, it cannot be changed.
+    All position accounting flows from trades.
+
+    Trade → Position relationship:
+        - Trades are immutable events
+        - Position state is derived from applying trades
+        - One position can have multiple trades (entry, partial exits, full exit)
+
+    Attributes:
+        id (str): Unique trade identifier.
+        position_id (str | None): ID of the position this trade belongs to.
+        pair (str): Trading pair (e.g. "BTCUSDT").
+        side (TradeSide): Trade side - "BUY" or "SELL".
+        ts (datetime | None): Execution timestamp.
+        price (float): Execution price.
+        qty (float): Executed quantity (always positive).
+        fee (float): Transaction fee paid (always positive).
+        meta (dict[str, Any]): Additional metadata (e.g., order_id, fill_type).
+
+    Example:
+        ```python
+        from signalflow.core import Trade
+        from datetime import datetime
+
+        # Entry trade
+        entry = Trade(
+            position_id="pos_123",
+            pair="BTCUSDT",
+            side="BUY",
+            ts=datetime.now(),
+            price=45000.0,
+            qty=0.5,
+            fee=22.5,
+            meta={"type": "entry", "signal": "sma_cross"}
+        )
+
+        # Exit trade
+        exit = Trade(
+            position_id="pos_123",
+            pair="BTCUSDT",
+            side="SELL",
+            ts=datetime.now(),
+            price=46000.0,
+            qty=0.5,
+            fee=23.0,
+            meta={"type": "exit", "reason": "take_profit"}
+        )
+
+        # Calculate PnL
+        pnl = (exit.price - entry.price) * entry.qty
+        total_fees = entry.fee + exit.fee
+        net_pnl = pnl - total_fees
+        print(f"Net PnL: ${net_pnl:.2f}")
+
+        # Check notional value
+        print(f"Entry notional: ${entry.notional:.2f}")
+        print(f"Exit notional: ${exit.notional:.2f}")
+        ```
+
+    Note:
+        Trades are immutable events. Position state is derived from trades.
+        qty and fee are always positive regardless of side.
+    """
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    position_id: str | None = None
+
+    pair: str = ""
+    side: TradeSide = "BUY"
+    ts: datetime | None = None
+
+    price: float = 0.0
+    qty: float = 0.0
+    fee: float = 0.0
+
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def notional(self) -> float:
+        """Calculate notional value of the trade.
+
+        Notional = price * qty
+
+        Returns:
+            float: Notional value in currency units.
+
+        Example:
+            ```python
+            trade = Trade(price=45000.0, qty=0.5)
+            assert trade.notional == 22500.0  # 45000 * 0.5
+
+            # Track total volume
+            trades = [trade1, trade2, trade3]
+            total_volume = sum(t.notional for t in trades)
+            ```
+        """
+        return float(self.price) * float(self.qty)