signalflow-trading 0.2.1__py3-none-any.whl

signalflow/core/containers/portfolio.py

@@ -0,0 +1,211 @@
+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
+
+from signalflow.core.containers.position import Position
+from signalflow.core.containers.trade import Trade
+
+@dataclass(slots=True)
+class Portfolio:
+    """Portfolio snapshot (pure domain).
+
+    Tracks cash and open/closed positions. Provides equity calculation
+    and DataFrame conversion utilities.
+
+    Portfolio state should only be modified through broker operations
+    to maintain accounting consistency.
+
+    Attributes:
+        cash (float): Available cash balance.
+        positions (dict[str, Position]): Dictionary of positions keyed by position ID.
+
+    Example:
+        ```python
+        from signalflow.core import Portfolio, Position, PositionType
+
+        # Initialize portfolio
+        portfolio = Portfolio(cash=10000.0)
+
+        # Add position
+        position = Position(
+            pair="BTCUSDT",
+            position_type=PositionType.LONG,
+            entry_price=45000.0,
+            qty=0.5
+        )
+        portfolio.positions[position.id] = position
+
+        # Calculate equity
+        prices = {"BTCUSDT": 46000.0, "ETHUSDT": 3200.0}
+        equity = portfolio.equity(prices=prices)
+
+        # Get open positions
+        open_positions = portfolio.open_positions()
+
+        # Convert to DataFrame
+        positions_df = Portfolio.positions_to_pl(open_positions)
+        ```
+
+    Note:
+        Portfolio state should only be modified through broker operations.
+        Direct manipulation may lead to accounting inconsistencies.
+    """
+
+    cash: float = 0.0
+    positions: dict[str, Position] = field(default_factory=dict)
+
+    def open_positions(self) -> list[Position]:
+        """Get list of open (non-closed) positions.
+
+        Returns:
+            list[Position]: Open positions.
+
+        Example:
+            ```python
+            open = portfolio.open_positions()
+            print(f"Open positions: {len(open)}")
+            
+            for pos in open:
+                print(f"{pos.pair}: {pos.qty} @ ${pos.entry_price}")
+            ```
+        """
+        return [p for p in self.positions.values() if not p.is_closed]
+
+    def equity(self, *, prices: dict[str, float]) -> float:
+        """Calculate total portfolio equity.
+
+        Equity = cash + sum(side_sign * price * qty for all positions)
+
+        Executor must keep accounting consistent for accurate equity.
+
+        Args:
+            prices (dict[str, float]): Current prices per pair.
+
+        Returns:
+            float: Total equity in currency units.
+
+        Example:
+            ```python
+            prices = {
+                "BTCUSDT": 46000.0,
+                "ETHUSDT": 3200.0
+            }
+            equity = portfolio.equity(prices=prices)
+            print(f"Total equity: ${equity:,.2f}")
+            
+            # Track equity over time
+            equity_history = []
+            for ts, prices in price_history:
+                eq = portfolio.equity(prices=prices)
+                equity_history.append((ts, eq))
+            ```
+
+        Note:
+            If price not in dict, uses position's last_price.
+            Executor must keep accounting consistent.
+        """
+        eq = self.cash
+        for p in self.positions.values():
+            px = prices.get(p.pair, p.last_price)
+            eq += p.side_sign * px * p.qty
+        return eq
+
+    @staticmethod
+    def positions_to_pl(positions: Iterable[Position]) -> pl.DataFrame:
+        """Convert positions to Polars DataFrame.
+
+        Args:
+            positions (Iterable[Position]): Positions to convert.
+
+        Returns:
+            pl.DataFrame: DataFrame with position data. Empty if no positions.
+
+        Example:
+            ```python
+            # Convert all positions
+            all_df = Portfolio.positions_to_pl(portfolio.positions.values())
+            
+            # Convert only open positions
+            open_df = Portfolio.positions_to_pl(portfolio.open_positions())
+            
+            # Analyze positions
+            print(open_df.select(["pair", "qty", "realized_pnl"]))
+            
+            # Group by pair
+            by_pair = open_df.group_by("pair").agg([
+                pl.col("qty").sum().alias("total_qty"),
+                pl.col("realized_pnl").sum().alias("total_pnl")
+            ])
+            ```
+        """
+        if not positions:
+            return pl.DataFrame()
+        return pl.DataFrame([
+            {
+                "id": p.id,
+                "is_closed": p.is_closed,
+                "pair": p.pair,
+                "position_type": p.position_type.value,
+                "signal_strength": p.signal_strength,
+                "entry_time": p.entry_time,
+                "last_time": p.last_time,
+                "entry_price": p.entry_price,
+                "last_price": p.last_price,
+                "qty": p.qty,
+                "fees_paid": p.fees_paid,
+                "realized_pnl": p.realized_pnl,
+                "meta": p.meta,
+            }
+            for p in positions
+        ])
+
+    @staticmethod
+    def trades_to_pl(trades: Iterable[Trade]) -> pl.DataFrame:
+        """Convert trades to Polars DataFrame.
+
+        Args:
+            trades (Iterable[Trade]): Trades to convert.
+
+        Returns:
+            pl.DataFrame: DataFrame with trade data. Empty if no trades.
+
+        Example:
+            ```python
+            # Convert all trades
+            trades_df = Portfolio.trades_to_pl(all_trades)
+            
+            # Analyze trades
+            print(trades_df.select(["pair", "side", "price", "qty"]))
+            
+            # Filter by type
+            entry_trades = trades_df.filter(
+                pl.col("meta").struct.field("type") == "entry"
+            )
+            
+            # Calculate total volume
+            total_volume = trades_df.select(
+                (pl.col("price") * pl.col("qty")).sum()
+            ).item()
+            ```
+        """
+        if not trades:
+            return pl.DataFrame()
+        return pl.DataFrame([
+            {
+                "id": t.id,
+                "position_id": t.position_id,
+                "pair": t.pair,
+                "side": t.side,
+                "ts": t.ts,
+                "price": t.price,
+                "qty": t.qty,
+                "fee": t.fee,
+                "meta": t.meta,
+            }
+            for t in trades
+        ])

signalflow/core/containers/position.py

@@ -0,0 +1,296 @@
+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
+
+from signalflow.core.containers.trade import Trade
+from signalflow.core.containers.trade import TradeSide
+from signalflow.core.enums import PositionType
+
+
+@dataclass(slots=True)
+class Position:
+    """Trading position aggregate.
+
+    Mutable by design - tracks the lifecycle of a trading position through
+    multiple trades (entry, partial exits, full exit).
+
+    Position state changes through two operations:
+        - mark(): Update to current market price (mark-to-market)
+        - apply_trade(): Apply executed trade to position
+
+    Attributes:
+        id (str): Unique position identifier.
+        is_closed (bool): Whether position is closed.
+        pair (str): Trading pair (e.g. "BTCUSDT").
+        position_type (PositionType): LONG or SHORT.
+        signal_strength (float): Strength of initial signal (0-1).
+        entry_time (datetime | None): Position entry timestamp.
+        last_time (datetime | None): Last update timestamp.
+        entry_price (float): Average entry price.
+        last_price (float): Current/last marked price.
+        qty (float): Current quantity held.
+        fees_paid (float): Total fees paid.
+        realized_pnl (float): Realized profit/loss.
+        meta (dict[str, Any]): Additional metadata.
+
+    Example:
+        ```python
+        from signalflow.core import Position, PositionType, Trade
+        from datetime import datetime
+
+        # Create position
+        position = Position(
+            pair="BTCUSDT",
+            position_type=PositionType.LONG,
+            entry_price=45000.0,
+            qty=0.5,
+            signal_strength=0.85,
+            entry_time=datetime.now()
+        )
+
+        # Mark to market
+        position.mark(ts=datetime.now(), price=46000.0)
+
+        # Apply exit trade
+        exit_trade = Trade(
+            pair="BTCUSDT",
+            side="SELL",
+            ts=datetime.now(),
+            price=46500.0,
+            qty=0.5,
+            fee=23.25
+        )
+        position.apply_trade(exit_trade)
+
+        # Check results
+        print(f"Total PnL: ${position.total_pnl:.2f}")
+        print(f"Closed: {position.is_closed}")
+        ```
+
+    Note:
+        Position changes ONLY through apply_trade() and mark().
+        Direct attribute modification should be avoided.
+    """
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    is_closed: bool = False
+
+    pair: str = ""
+    position_type: PositionType = PositionType.LONG
+    signal_strength: float = 1.0
+
+    entry_time: datetime | None = None
+    last_time: datetime | None = None
+
+    entry_price: float = 0.0   
+    last_price: float = 0.0
+
+    qty: float = 0.0          
+    fees_paid: float = 0.0
+    realized_pnl: float = 0.0
+
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def side_sign(self) -> float:
+        """Position direction multiplier.
+
+        Returns:
+            float: 1.0 for LONG, -1.0 for SHORT.
+
+        Example:
+            ```python
+            long_pos = Position(position_type=PositionType.LONG)
+            assert long_pos.side_sign == 1.0
+
+            short_pos = Position(position_type=PositionType.SHORT)
+            assert short_pos.side_sign == -1.0
+            ```
+        """
+        return 1.0 if self.position_type == PositionType.LONG else -1.0
+
+    @property
+    def unrealized_pnl(self) -> float:
+        """Unrealized profit/loss at current price.
+
+        Calculated as: side_sign * (last_price - entry_price) * qty
+
+        Returns:
+            float: Unrealized PnL in currency units.
+
+        Example:
+            ```python
+            position = Position(
+                position_type=PositionType.LONG,
+                entry_price=45000.0,
+                last_price=46000.0,
+                qty=0.5
+            )
+            # (46000 - 45000) * 0.5 = 500
+            assert position.unrealized_pnl == 500.0
+            ```
+        """
+        return self.side_sign * (self.last_price - self.entry_price) * self.qty
+
+    @property
+    def total_pnl(self) -> float:
+        """Total profit/loss including fees.
+
+        Calculated as: realized_pnl + unrealized_pnl - fees_paid
+
+        Returns:
+            float: Total PnL in currency units.
+
+        Example:
+            ```python
+            position = Position(
+                realized_pnl=100.0,
+                fees_paid=50.0
+            )
+            position.mark(ts=datetime.now(), price=46000.0)
+            total = position.total_pnl  # realized + unrealized - fees
+            ```
+        """
+        return self.realized_pnl + self.unrealized_pnl - self.fees_paid
+
+    def mark(self, *, ts: datetime, price: float) -> None:
+        """Update position to current market price (mark-to-market).
+
+        Updates last_time and last_price without affecting position size.
+        Used for tracking unrealized PnL over time.
+
+        Args:
+            ts (datetime): Update timestamp.
+            price (float): Current market price.
+
+        Example:
+            ```python
+            # Mark position at each bar
+            for bar in bars:
+                position.mark(ts=bar.timestamp, price=bar.close)
+                print(f"Unrealized PnL: ${position.unrealized_pnl:.2f}")
+            ```
+        """
+        self.last_time = ts
+        self.last_price = float(price)
+
+    def apply_trade(self, trade: Trade) -> None:
+        """Apply trade fill to position.
+
+        Updates position state based on trade:
+            - Increases position if trade direction matches position type
+            - Decreases position (partial/full close) if direction opposes
+            - Updates fees, realized PnL, and closing status
+
+        Trade processing:
+            - BUY increases LONG, SELL decreases LONG
+            - SELL increases SHORT, BUY decreases SHORT
+            - Entry price updated as weighted average on increases
+            - Realized PnL computed on decreases
+
+        Args:
+            trade (Trade): Trade to apply. Must have qty > 0.
+
+        Example:
+            ```python
+            # Open position
+            entry_trade = Trade(
+                pair="BTCUSDT",
+                side="BUY",
+                price=45000.0,
+                qty=1.0,
+                fee=45.0
+            )
+            position.apply_trade(entry_trade)
+
+            # Partial close
+            exit_trade = Trade(
+                pair="BTCUSDT",
+                side="SELL",
+                price=46000.0,
+                qty=0.5,
+                fee=23.0
+            )
+            position.apply_trade(exit_trade)
+
+            # Check state
+            assert position.qty == 0.5
+            assert position.realized_pnl == 500.0  # (46000-45000)*0.5
+            assert not position.is_closed
+            ```
+
+        Note:
+            Assumes trade.qty > 0. Position automatically marked as closed
+            when qty reaches 0.
+        """
+        self.last_time = trade.ts
+        self.last_price = float(trade.price)
+        self.fees_paid += float(trade.fee)
+
+        is_increase = self._is_increase(trade.side)
+
+        if is_increase:
+            self._increase(trade)
+        else:
+            self._decrease(trade)
+
+    def _is_increase(self, side: TradeSide) -> bool:
+        """Check if trade increases position size.
+
+        Args:
+            side (TradeSide): Trade side ("BUY" or "SELL").
+
+        Returns:
+            bool: True if trade increases position.
+        """
+        return (
+            (self.position_type == PositionType.LONG and side == "BUY")
+            or (self.position_type == PositionType.SHORT and side == "SELL")
+        )
+
+    def _increase(self, trade: Trade) -> None:
+        """Increase position size with new trade.
+
+        Updates entry_price as weighted average of existing and new position.
+
+        Args:
+            trade (Trade): Trade to add to position.
+        """
+        new_qty = self.qty + trade.qty
+        if new_qty <= 0:
+            return
+
+        if self.qty == 0:
+            self.entry_price = trade.price
+            self.entry_time = trade.ts
+        else:
+            self.entry_price = (
+                self.entry_price * self.qty + trade.price * trade.qty
+            ) / new_qty
+
+        self.qty = new_qty
+
+    def _decrease(self, trade: Trade) -> None:
+        """Decrease position size (partial or full close).
+
+        Computes realized PnL for closed portion.
+        Marks position as closed if qty reaches 0.
+
+        Args:
+            trade (Trade): Trade to close position.
+        """
+        close_qty = min(self.qty, trade.qty)
+        if close_qty <= 0:
+            return
+
+        pnl = self.side_sign * (trade.price - self.entry_price) * close_qty
+        self.realized_pnl += pnl
+        self.qty -= close_qty
+
+        if self.qty == 0:
+            self.is_closed = True

signalflow/core/containers/raw_data.py

@@ -0,0 +1,167 @@
+import pandas as pd
+import polars as pl
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Iterator
+
+
+@dataclass(frozen=True)
+class RawData:
+    """Immutable container for raw market data.
+
+    Acts as a unified in-memory bundle for multiple raw datasets
+    (e.g. spot prices, funding, trades, orderbook, signals).
+
+    Design principles:
+        - Canonical storage is dataset-based (dictionary by name)
+        - Datasets accessed via string keys (e.g. raw_data["spot"])
+        - No business logic or transformations
+        - Immutability ensures reproducibility in pipelines
+
+    Attributes:
+        datetime_start (datetime): Start datetime of the data snapshot.
+        datetime_end (datetime): End datetime of the data snapshot.
+        pairs (list[str]): List of trading pairs in the snapshot.
+        data (dict[str, pl.DataFrame]): Dictionary of datasets keyed by name.
+
+    Example:
+        ```python
+        from signalflow.core import RawData
+        import polars as pl
+        from datetime import datetime
+
+        # Create RawData with spot data
+        raw_data = RawData(
+            datetime_start=datetime(2024, 1, 1),
+            datetime_end=datetime(2024, 12, 31),
+            pairs=["BTCUSDT", "ETHUSDT"],
+            data={
+                "spot": spot_dataframe,
+                "signals": signals_dataframe,
+            }
+        )
+
+        # Access datasets
+        spot_df = raw_data["spot"]
+        signals_df = raw_data.get("signals")
+
+        # Check if dataset exists
+        if "spot" in raw_data:
+            print("Spot data available")
+        ```
+
+    Note:
+        Dataset schemas are defined by convention, not enforced.
+        Views (pandas/polars) should be handled by RawDataView wrapper.
+    """
+
+    datetime_start: datetime
+    datetime_end: datetime
+    pairs: list[str] = field(default_factory=list)
+    data: dict[str, pl.DataFrame] = field(default_factory=dict)
+
+    def get(self, key: str) -> pl.DataFrame:
+        """Get dataset by key.
+
+        Args:
+            key (str): Dataset name (e.g. "spot", "signals").
+
+        Returns:
+            pl.DataFrame: Polars DataFrame if exists, empty DataFrame otherwise.
+
+        Raises:
+            TypeError: If dataset exists but is not a Polars DataFrame.
+
+        Example:
+            ```python
+            spot_df = raw_data.get("spot")
+            
+            # Returns empty DataFrame if key doesn't exist
+            missing_df = raw_data.get("nonexistent")
+            assert missing_df.is_empty()
+            ```
+        """
+        obj = self.data.get(key)
+        if obj is None:
+            return pl.DataFrame()
+        if not isinstance(obj, pl.DataFrame):
+            raise TypeError(
+                f"Dataset '{key}' is not a polars.DataFrame: {type(obj)}"
+            )
+        return obj
+
+    def __getitem__(self, key: str) -> pl.DataFrame:
+        """Dictionary-style access to datasets.
+
+        Args:
+            key (str): Dataset name.
+
+        Returns:
+            pl.DataFrame: Dataset as Polars DataFrame.
+
+        Example:
+            ```python
+            spot_df = raw_data["spot"]
+            ```
+        """
+        return self.get(key)
+
+    def __contains__(self, key: str) -> bool:
+        """Check if dataset exists.
+
+        Args:
+            key (str): Dataset name to check.
+
+        Returns:
+            bool: True if dataset exists, False otherwise.
+
+        Example:
+            ```python
+            if "spot" in raw_data:
+                process_spot_data(raw_data["spot"])
+            ```
+        """
+        return key in self.data
+
+    def keys(self) -> Iterator[str]:
+        """Return available dataset keys.
+
+        Returns:
+            Iterator[str]: Iterator over dataset names.
+
+        Example:
+            ```python
+            for key in raw_data.keys():
+                print(f"Dataset: {key}")
+            ```
+        """
+        return self.data.keys()
+
+    def items(self):
+        """Return (key, dataset) pairs.
+
+        Returns:
+            Iterator: Iterator over (key, DataFrame) tuples.
+
+        Example:
+            ```python
+            for name, df in raw_data.items():
+                print(f"{name}: {df.shape}")
+            ```
+        """
+        return self.data.items()
+
+    def values(self):
+        """Return dataset values.
+
+        Returns:
+            Iterator: Iterator over DataFrames.
+
+        Example:
+            ```python
+            for df in raw_data.values():
+                print(df.columns)
+            ```
+        """
+        return self.data.values()