signalflow-trading 0.2.1__py3-none-any.whl

signalflow/__init__.py

@@ -0,0 +1,21 @@
+import signalflow.core as core
+import signalflow.data as data
+import signalflow.detector as detector
+import signalflow.feature as feature
+import signalflow.target as target
+import signalflow.strategy as strategy
+import signalflow.utils as utils
+import signalflow.validator as validator
+
+
+
+__all__ = [
+    "core",
+    "data",
+    "detector",
+    "feature",
+    "target",
+    "strategy"
+    "utils",
+    "validator",
+]

signalflow/core/__init__.py

@@ -0,0 +1,46 @@
+from signalflow.core.containers import (
+    RawData, 
+    Signals, 
+    RawDataView, 
+    Position, 
+    Trade,  
+    Portfolio, 
+    StrategyState,
+    Order,
+    OrderFill
+)
+from signalflow.core.enums import (
+    SignalType, 
+    PositionType, 
+    SfComponentType, 
+    DataFrameType, 
+    RawDataType
+)
+from signalflow.core.decorators import sf_component
+from signalflow.core.registry import default_registry, SignalFlowRegistry
+from signalflow.core.signal_transforms import SignalsTransform
+from signalflow.core.rolling_aggregator import RollingAggregator
+from signalflow.core.base_mixin import SfTorchModuleMixin
+
+__all__ = [
+    "RawData", 
+    "Signals", 
+    "RawDataView", 
+    "Position", 
+    "Trade", 
+    "Order",
+    "OrderFill",
+    "Portfolio", 
+    "StrategyState",
+    "SignalType",
+    "PositionType",
+    "SfComponentType",
+    "DataFrameType",
+    "RawDataType",
+    "sf_component",
+    "default_registry",
+    "SignalFlowRegistry",
+    "RollingAggregator",
+    "SignalsTransform",
+    "SfTorchModuleMixin",
+]

signalflow/core/base_mixin.py

@@ -0,0 +1,232 @@
+from abc import ABC, abstractmethod
+import optuna
+from signalflow.core.enums import SfComponentType
+from typing import Literal
+
+
+class SfTorchModuleMixin(ABC):
+    """Mixin for all SignalFlow neural network modules.
+
+    Provides standardized interface for PyTorch modules used in SignalFlow,
+    including default parameters and hyperparameter tuning via Optuna.
+
+    All neural network modules (detectors, validators, etc.) should inherit
+    from this mixin to ensure consistent configuration and tuning interfaces.
+
+    Key features:
+        - Automatic component type registration
+        - Standardized parameter interface
+        - Built-in Optuna integration for hyperparameter tuning
+        - Size-based architecture variants (small, medium, large)
+
+    Attributes:
+        component_type (SfComponentType): Always set to TORCH_MODULE for registry.
+
+    Example:
+        ```python
+        import torch
+        import torch.nn as nn
+        import optuna
+        from signalflow.core import SfTorchModuleMixin
+
+        class MyLSTMDetector(nn.Module, SfTorchModuleMixin):
+            def __init__(self, input_size: int, hidden_size: int, num_layers: int):
+                super().__init__()
+                self.lstm = nn.LSTM(input_size, hidden_size, num_layers)
+                self.fc = nn.Linear(hidden_size, 3)  # 3 classes
+
+            def forward(self, x):
+                out, _ = self.lstm(x)
+                return self.fc(out[:, -1, :])
+
+            @classmethod
+            def default_params(cls) -> dict:
+                return {
+                    "input_size": 10,
+                    "hidden_size": 64,
+                    "num_layers": 2
+                }
+
+            @classmethod
+            def tune(cls, trial: optuna.Trial, model_size: str = "small") -> dict:
+                if model_size == "small":
+                    hidden_range = (32, 64)
+                    layers_range = (1, 2)
+                elif model_size == "medium":
+                    hidden_range = (64, 128)
+                    layers_range = (2, 3)
+                else:  # large
+                    hidden_range = (128, 256)
+                    layers_range = (3, 4)
+
+                return {
+                    "input_size": 10,
+                    "hidden_size": trial.suggest_int("hidden_size", *hidden_range),
+                    "num_layers": trial.suggest_int("num_layers", *layers_range)
+                }
+
+        # Use default params
+        model = MyLSTMDetector(**MyLSTMDetector.default_params())
+
+        # Hyperparameter tuning
+        study = optuna.create_study()
+        
+        def objective(trial):
+            params = MyLSTMDetector.tune(trial, model_size="medium")
+            model = MyLSTMDetector(**params)
+            # ... train and evaluate model ...
+            return validation_loss
+
+        study.optimize(objective, n_trials=100)
+        ```
+
+    Note:
+        Classes inheriting this mixin must implement both abstract methods.
+        The component_type is automatically set for registry integration.
+
+    See Also:
+        sf_component: Decorator for registering modules in the registry.
+        SfComponentType: Enum of all component types including TORCH_MODULE.
+    """
+    
+    component_type: SfComponentType = SfComponentType.TORCH_MODULE
+    
+    @classmethod
+    @abstractmethod
+    def default_params(cls) -> dict:
+        """Get default parameters for module instantiation.
+
+        Provides sensible defaults for quick prototyping and baseline comparisons.
+        These parameters should work reasonably well out-of-the-box.
+
+        Returns:
+            dict: Dictionary of parameter names and default values.
+                Keys match constructor argument names.
+
+        Example:
+            ```python
+            class MyTransformer(nn.Module, SfTorchModuleMixin):
+                def __init__(self, d_model: int, nhead: int, num_layers: int):
+                    super().__init__()
+                    # ... initialization ...
+
+                @classmethod
+                def default_params(cls) -> dict:
+                    return {
+                        "d_model": 128,
+                        "nhead": 8,
+                        "num_layers": 3
+                    }
+
+            # Instantiate with defaults
+            model = MyTransformer(**MyTransformer.default_params())
+
+            # Override specific params
+            params = MyTransformer.default_params()
+            params["d_model"] = 256
+            model = MyTransformer(**params)
+            ```
+
+        Note:
+            Should be comprehensive - include all constructor parameters.
+            Consider computational constraints when setting defaults.
+        """
+        ...
+    
+    @classmethod
+    @abstractmethod
+    def tune(cls, trial: optuna.Trial, model_size: Literal["small", "medium", "large"] = "small") -> dict:
+        """Define Optuna hyperparameter search space.
+
+        Provides size-based architecture variants for different computational budgets:
+            - small: Fast training, limited capacity
+            - medium: Balanced performance/speed
+            - large: Maximum capacity, slower training
+
+        Args:
+            trial (optuna.Trial): Optuna trial object for suggesting hyperparameters.
+            model_size (Literal["small", "medium", "large"]): Architecture size variant.
+                Default: "small".
+
+        Returns:
+            dict: Dictionary of hyperparameters sampled from search space.
+                Keys match constructor argument names.
+
+        Example:
+            ```python
+            class MyRNN(nn.Module, SfTorchModuleMixin):
+                def __init__(self, input_size: int, hidden_size: int, 
+                           num_layers: int, dropout: float):
+                    super().__init__()
+                    # ... initialization ...
+
+                @classmethod
+                def default_params(cls) -> dict:
+                    return {
+                        "input_size": 20,
+                        "hidden_size": 64,
+                        "num_layers": 2,
+                        "dropout": 0.1
+                    }
+
+                @classmethod
+                def tune(cls, trial: optuna.Trial, model_size: str = "small") -> dict:
+                    # Size-based ranges
+                    size_config = {
+                        "small": {
+                            "hidden": (32, 64),
+                            "layers": (1, 2)
+                        },
+                        "medium": {
+                            "hidden": (64, 128),
+                            "layers": (2, 3)
+                        },
+                        "large": {
+                            "hidden": (128, 256),
+                            "layers": (3, 5)
+                        }
+                    }
+                    
+                    config = size_config[model_size]
+                    
+                    return {
+                        "input_size": 20,
+                        "hidden_size": trial.suggest_int(
+                            "hidden_size", 
+                            *config["hidden"]
+                        ),
+                        "num_layers": trial.suggest_int(
+                            "num_layers", 
+                            *config["layers"]
+                        ),
+                        "dropout": trial.suggest_float("dropout", 0.0, 0.5)
+                    }
+
+            # Run hyperparameter search
+            import optuna
+
+            def objective(trial):
+                params = MyRNN.tune(trial, model_size="medium")
+                model = MyRNN(**params)
+                
+                # Train model
+                trainer = Trainer(model, train_data, val_data)
+                val_loss = trainer.train()
+                
+                return val_loss
+
+            study = optuna.create_study(direction="minimize")
+            study.optimize(objective, n_trials=50)
+
+            # Get best params
+            best_params = study.best_params
+            best_model = MyRNN(**MyRNN.tune(study.best_trial, "medium"))
+            ```
+
+        Note:
+            Search space should be tailored to model_size.
+            Use trial.suggest_* methods (int, float, categorical).
+            Return dict must be compatible with constructor.
+            Consider pruning for early stopping of poor trials.
+        """
+        ...

signalflow/core/containers/__init__.py

@@ -0,0 +1,21 @@
+from signalflow.core.containers.raw_data import RawData
+from signalflow.core.containers.raw_data_view import RawDataView
+from signalflow.core.containers.signals import Signals
+from signalflow.core.containers.position import Position
+from signalflow.core.containers.trade import Trade
+from signalflow.core.containers.portfolio import Portfolio
+from signalflow.core.containers.strategy_state import StrategyState 
+from signalflow.core.containers.order import Order, OrderFill
+
+
+__all__ = [
+    "RawData", 
+    "RawDataView", 
+    "Signals", 
+    "Position", 
+    "Trade", 
+    "Portfolio",
+    "StrategyState",
+    "Order",
+    "OrderFill",
+]

signalflow/core/containers/order.py

@@ -0,0 +1,216 @@
+"""Order and OrderFill containers for strategy execution."""
+from __future__ import annotations
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+OrderSide = Literal['BUY', 'SELL']
+OrderType = Literal['MARKET', 'LIMIT']
+OrderStatus = Literal['NEW', 'FILLED', 'PARTIALLY_FILLED', 'CANCELLED', 'REJECTED']
+
+
+@dataclass(slots=True)
+class Order:
+    """Trading order intent (mutable).
+
+    Represents the intent to trade. Orders are instructions that may or may not
+    be filled by the executor.
+
+    Order lifecycle:
+        NEW → PARTIALLY_FILLED → FILLED
+                              → CANCELLED
+                              → REJECTED
+
+    Attributes:
+        id (str): Unique order identifier.
+        pair (str): Trading pair (e.g. "BTCUSDT").
+        side (OrderSide): Order side - "BUY" or "SELL".
+        order_type (OrderType): Order type - "MARKET" or "LIMIT".
+        qty (float): Order quantity (always positive).
+        price (float | None): Limit price (None for MARKET orders).
+        created_at (datetime | None): Order creation timestamp.
+        status (OrderStatus): Current order status.
+        position_id (str | None): ID of position this order affects.
+        signal_strength (float): Strength of signal triggering order (0-1).
+        meta (dict[str, Any]): Additional metadata (e.g., signal info, exit reason).
+
+    Example:
+        ```python
+        from signalflow.core import Order
+
+        # Market buy order
+        market_order = Order(
+            pair="BTCUSDT",
+            side="BUY",
+            order_type="MARKET",
+            qty=0.5,
+            position_id="pos_123",
+            signal_strength=0.85,
+            meta={"type": "entry", "signal": "sma_cross"}
+        )
+
+        # Limit sell order
+        limit_order = Order(
+            pair="BTCUSDT",
+            side="SELL",
+            order_type="LIMIT",
+            qty=0.5,
+            price=46000.0,
+            position_id="pos_123",
+            meta={"type": "exit", "reason": "take_profit"}
+        )
+
+        # Check order properties
+        assert market_order.is_buy
+        assert market_order.is_market
+        assert limit_order.is_sell
+        ```
+
+    Note:
+        Orders are mutable to allow status updates.
+        Not all orders result in fills (e.g., insufficient liquidity, rejected).
+    """
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    pair: str = ''
+    side: OrderSide = 'BUY'
+    order_type: OrderType = 'MARKET'
+    qty: float = 0.0
+    price: float | None = None 
+    created_at: datetime | None = None
+    status: OrderStatus = 'NEW'
+    position_id: str | None = None  
+    signal_strength: float = 1.0
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_buy(self) -> bool:
+        """Check if order is a buy order.
+
+        Returns:
+            bool: True if side is "BUY".
+
+        Example:
+            ```python
+            order = Order(side="BUY")
+            assert order.is_buy
+            ```
+        """
+        return self.side == 'BUY'
+
+    @property
+    def is_sell(self) -> bool:
+        """Check if order is a sell order.
+
+        Returns:
+            bool: True if side is "SELL".
+
+        Example:
+            ```python
+            order = Order(side="SELL")
+            assert order.is_sell
+            ```
+        """
+        return self.side == 'SELL'
+
+    @property
+    def is_market(self) -> bool:
+        """Check if order is a market order.
+
+        Returns:
+            bool: True if order_type is "MARKET".
+
+        Example:
+            ```python
+            order = Order(order_type="MARKET")
+            assert order.is_market
+            ```
+        """
+        return self.order_type == 'MARKET'
+
+
+@dataclass(frozen=True, slots=True)
+class OrderFill:
+    """Order execution result (immutable).
+
+    Represents the actual execution of an order. Maps directly to trade(s).
+    OrderFill is the bridge between order intent and executed trades.
+
+    Attributes:
+        id (str): Unique fill identifier.
+        order_id (str): ID of the order that was filled.
+        pair (str): Trading pair.
+        side (OrderSide): Fill side - "BUY" or "SELL".
+        ts (datetime | None): Fill timestamp.
+        price (float): Execution price.
+        qty (float): Filled quantity (may differ from order qty for partial fills).
+        fee (float): Transaction fee for this fill.
+        position_id (str | None): ID of the position affected.
+        meta (dict[str, Any]): Additional fill metadata.
+
+    Example:
+        ```python
+        from signalflow.core import OrderFill
+        from datetime import datetime
+
+        # Complete fill
+        fill = OrderFill(
+            order_id="order_123",
+            pair="BTCUSDT",
+            side="BUY",
+            ts=datetime.now(),
+            price=45000.0,
+            qty=0.5,
+            fee=22.5,
+            position_id="pos_123"
+        )
+
+        # Check fill details
+        print(f"Notional: ${fill.notional:.2f}")
+        print(f"Fee: ${fill.fee:.2f}")
+
+        # Partial fill
+        partial_fill = OrderFill(
+            order_id="order_456",
+            pair="BTCUSDT",
+            side="BUY",
+            ts=datetime.now(),
+            price=45100.0,
+            qty=0.3,  # Order was for 0.5
+            fee=13.53,
+            position_id="pos_123",
+            meta={"status": "partial", "remaining": 0.2}
+        )
+        ```
+
+    Note:
+        OrderFill.qty may be less than Order.qty (partial fills).
+        Always check fills to update accounting correctly.
+    """
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    order_id: str = ''
+    pair: str = ''
+    side: OrderSide = 'BUY'
+    ts: datetime | None = None
+    price: float = 0.0
+    qty: float = 0.0
+    fee: float = 0.0
+    position_id: str | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def notional(self) -> float:
+        """Calculate notional value of the fill.
+
+        Notional = price * qty
+
+        Returns:
+            float: Notional value in currency units.
+
+        Example:
+            ```python
+            fill = OrderFill(price=45000.0, qty=0.5)
+            assert fill.notional == 22500.0  # 45000 * 0.5
+            ```
+        """
+        return self.price * self.qty