signalflow-trading 0.2.1__py3-none-any.whl

signalflow/core/decorators.py

@@ -0,0 +1,103 @@
+from typing import Any, Type
+from signalflow.core.registry import default_registry
+from signalflow.core.enums import SfComponentType
+
+
+def sf_component(*, name: str, override: bool = False):
+    """Register class as SignalFlow component.
+
+    Decorator that registers a class in the global component registry,
+    making it discoverable by name for dynamic instantiation.
+
+    The decorated class must have a `component_type` class attribute
+    of type `SfComponentType` to indicate what kind of component it is
+    (e.g., DETECTOR, EXTRACTOR, LABELER, ENTRY_RULE, EXIT_RULE).
+
+    Args:
+        name (str): Registry name for the component (case-insensitive).
+        override (bool): Allow overriding existing registration. Default: False.
+
+    Returns:
+        Callable: Decorator function that registers and returns the class unchanged.
+
+    Raises:
+        ValueError: If class doesn't define component_type attribute.
+        ValueError: If name already registered and override=False.
+
+    Example:
+        ```python
+        from signalflow.core import sf_component
+        from signalflow.core.enums import SfComponentType
+        from signalflow.detector import SignalDetector
+
+        @sf_component(name="my_detector")
+        class MyDetector(SignalDetector):
+            component_type = SfComponentType.DETECTOR
+            
+            def detect(self, df):
+                # Detection logic
+                return signals
+
+        # Later, instantiate by name
+        from signalflow.core.registry import default_registry
+        
+        detector_cls = default_registry.get(
+            SfComponentType.DETECTOR,
+            "my_detector"
+        )
+        detector = detector_cls(params={"window": 20})
+
+        # Override existing registration
+        @sf_component(name="my_detector", override=True)
+        class ImprovedDetector(SignalDetector):
+            component_type = SfComponentType.DETECTOR
+            # ... improved implementation
+        ```
+
+    Example:
+        ```python
+        # Register multiple component types
+        
+        @sf_component(name="sma_cross")
+        class SmaCrossDetector(SignalDetector):
+            component_type = SfComponentType.DETECTOR
+            # ...
+
+        @sf_component(name="rsi")
+        class RsiExtractor(FeatureExtractor):
+            component_type = SfComponentType.EXTRACTOR
+            # ...
+
+        @sf_component(name="fixed_size")
+        class FixedSizeEntry(SignalEntryRule):
+            component_type = SfComponentType.ENTRY_RULE
+            # ...
+
+        @sf_component(name="take_profit")
+        class TakeProfitExit(ExitRule):
+            component_type = SfComponentType.EXIT_RULE
+            # ...
+        ```
+
+    Note:
+        Component names are case-insensitive for lookup.
+        The class itself is not modified - only registered.
+        Use override=True carefully to avoid accidental overrides.
+    """
+    def decorator(cls: Type[Any]) -> Type[Any]:
+        component_type = getattr(cls, "component_type", None)
+        if not isinstance(component_type, SfComponentType):
+            raise ValueError(
+                f"{cls.__name__} must define class attribute "
+                f"'component_type: SfComponentType'"
+            )
+
+        default_registry.register(
+            component_type,
+            name=name,
+            cls=cls,
+            override=override,
+        )
+        return cls
+
+    return decorator

signalflow/core/enums.py

@@ -0,0 +1,270 @@
+from enum import Enum
+
+
+class SignalType(str, Enum):
+    """Enumeration of signal types.
+
+    Represents the direction of a trading signal detected by signal detectors.
+
+    Values:
+        NONE: No signal detected or neutral state.
+        RISE: Bullish signal indicating potential price increase.
+        FALL: Bearish signal indicating potential price decrease.
+
+    Example:
+        ```python
+        from signalflow.core.enums import SignalType
+
+        # Check signal type
+        if signal_type == SignalType.RISE:
+            print("Bullish signal detected")
+        elif signal_type == SignalType.FALL:
+            print("Bearish signal detected")
+        else:
+            print("No signal")
+
+        # Use in DataFrame
+        import polars as pl
+        signals_df = pl.DataFrame({
+            "pair": ["BTCUSDT"],
+            "timestamp": [datetime.now()],
+            "signal_type": [SignalType.RISE.value]
+        })
+
+        # Compare with enum
+        is_rise = signals_df.filter(
+            pl.col("signal_type") == SignalType.RISE.value
+        )
+        ```
+
+    Note:
+        Stored as string values in DataFrames for serialization.
+        Use .value to get string representation.
+    """
+    NONE = "none"
+    RISE = "rise"
+    FALL = "fall"
+
+
+class PositionType(str, Enum):
+    """Enumeration of position types.
+
+    Represents the direction of a trading position.
+
+    Values:
+        LONG: Long position (profit from price increase).
+        SHORT: Short position (profit from price decrease).
+
+    Example:
+        ```python
+        from signalflow.core import Position, PositionType
+
+        # Create long position
+        long_position = Position(
+            pair="BTCUSDT",
+            position_type=PositionType.LONG,
+            entry_price=45000.0,
+            qty=0.5
+        )
+
+        # Check position type
+        if position.position_type == PositionType.LONG:
+            print("Long position")
+            assert position.side_sign == 1.0
+        else:
+            print("Short position")
+            assert position.side_sign == -1.0
+
+        # Store in DataFrame
+        positions_df = pl.DataFrame({
+            "pair": ["BTCUSDT"],
+            "position_type": [PositionType.LONG.value],
+            "qty": [0.5]
+        })
+        ```
+
+    Note:
+        Currently only LONG positions are fully implemented.
+        SHORT positions planned for future versions.
+    """
+    LONG = "long"
+    SHORT = "short"
+
+
+class SfComponentType(str, Enum):
+    """Enumeration of SignalFlow component types.
+
+    Defines all component types that can be registered in the component registry.
+    Used by sf_component decorator and SignalFlowRegistry for type-safe registration.
+
+    Component categories:
+        - Data: Raw data loading and storage
+        - Feature: Feature extraction
+        - Signals: Signal detection, transformation, labeling, validation
+        - Strategy: Execution, rules, metrics
+
+    Values:
+        RAW_DATA_STORE: Raw data storage backends (e.g., DuckDB, Parquet).
+        RAW_DATA_SOURCE: Raw data sources (e.g., Binance API).
+        RAW_DATA_LOADER: Raw data loaders combining source + store.
+        FEATURE_EXTRACTOR: Feature extraction classes (e.g., RSI, SMA).
+        SIGNALS_TRANSFORM: Signal transformation functions.
+        LABELER: Signal labeling strategies (e.g., triple barrier).
+        DETECTOR: Signal detection algorithms (e.g., SMA cross).
+        VALIDATOR: Signal validation models.
+        TORCH_MODULE: PyTorch neural network modules.
+        VALIDATOR_MODEL: Pre-trained validator models.
+        STRATEGY_STORE: Strategy state persistence backends.
+        STRATEGY_RUNNER: Backtest/live runner implementations.
+        STRATEGY_BROKER: Order management and position tracking.
+        STRATEGY_EXECUTOR: Order execution engines (backtest/live).
+        STRATEGY_EXIT_RULE: Position exit rules (e.g., take profit, stop loss).
+        STRATEGY_ENTRY_RULE: Position entry rules (e.g., fixed size).
+        STRATEGY_METRIC: Strategy performance metrics.
+
+    Example:
+        ```python
+        from signalflow.core import sf_component
+        from signalflow.core.enums import SfComponentType
+        from signalflow.detector import SignalDetector
+
+        # Register detector
+        @sf_component(name="my_detector")
+        class MyDetector(SignalDetector):
+            component_type = SfComponentType.DETECTOR
+            # ... implementation
+
+        # Register extractor
+        @sf_component(name="my_feature")
+        class MyExtractor(FeatureExtractor):
+            component_type = SfComponentType.FEATURE_EXTRACTOR
+            # ... implementation
+
+        # Register exit rule
+        @sf_component(name="my_exit")
+        class MyExit(ExitRule):
+            component_type = SfComponentType.STRATEGY_EXIT_RULE
+            # ... implementation
+
+        # Use in registry
+        from signalflow.core.registry import default_registry
+
+        detector = default_registry.create(
+            SfComponentType.DETECTOR,
+            "my_detector"
+        )
+        ```
+
+    Note:
+        All registered components must have component_type class attribute.
+        Component types are organized hierarchically (category/subcategory).
+    """
+    RAW_DATA_STORE = "data/store"
+    RAW_DATA_SOURCE = "data/source"
+    RAW_DATA_LOADER = "data/loader"
+
+    FEATURE_EXTRACTOR = "feature/extractor"
+
+    SIGNALS_TRANSFORM = "signals/transform"
+    LABELER = "signals/labeler"
+    DETECTOR = "signals/detector"
+    VALIDATOR = "signals/validator"
+    TORCH_MODULE = "torch_module"
+    VALIDATOR_MODEL = "signals/validator/model"
+
+    STRATEGY_STORE = "strategy/store"
+    STRATEGY_RUNNER = "strategy/runner"
+    STRATEGY_BROKER = "strategy/broker"
+    STRATEGY_EXECUTOR = "strategy/executor"
+    STRATEGY_EXIT_RULE = "strategy/exit"
+    STRATEGY_ENTRY_RULE = "strategy/entry"
+    STRATEGY_METRIC = "strategy/metric"
+
+
+class DataFrameType(str, Enum):
+    """Supported DataFrame backends.
+
+    Specifies which DataFrame library to use for data processing.
+    Used by FeatureExtractor and other components to determine input/output format.
+
+    Values:
+        POLARS: Polars DataFrame (faster, modern).
+        PANDAS: Pandas DataFrame (legacy compatibility).
+
+    Example:
+        ```python
+        from signalflow.core.enums import DataFrameType
+        from signalflow.feature import FeatureExtractor
+
+        # Polars-based extractor
+        class MyExtractor(FeatureExtractor):
+            df_type = DataFrameType.POLARS
+            
+            def extract(self, df: pl.DataFrame) -> pl.DataFrame:
+                return df.with_columns(
+                    pl.col("close").rolling_mean(20).alias("sma_20")
+                )
+
+        # Pandas-based extractor
+        class LegacyExtractor(FeatureExtractor):
+            df_type = DataFrameType.PANDAS
+            
+            def extract(self, df: pd.DataFrame) -> pd.DataFrame:
+                df["sma_20"] = df["close"].rolling(20).mean()
+                return df
+
+        # Use in RawDataView
+        from signalflow.core import RawDataView
+
+        view = RawDataView(raw=raw_data)
+        
+        # Get data in required format
+        df_polars = view.get_data("spot", DataFrameType.POLARS)
+        df_pandas = view.get_data("spot", DataFrameType.PANDAS)
+        ```
+
+    Note:
+        New code should prefer POLARS for better performance.
+        PANDAS supported for backward compatibility and legacy libraries.
+    """
+    POLARS = "polars"
+    PANDAS = "pandas"
+
+class RawDataType(str, Enum):
+    """Supported raw data types.
+
+    Defines types of market data that can be loaded and processed.
+
+    Values:
+        SPOT: Spot trading data (OHLCV).
+
+    Example:
+        ```python
+        from signalflow.core.enums import RawDataType
+
+        # Load spot data
+        loader = BinanceLoader(
+            pairs=["BTCUSDT", "ETHUSDT"],
+            data_type=RawDataType.SPOT
+        )
+
+        raw_data = loader.load(
+            datetime_start=datetime(2024, 1, 1),
+            datetime_end=datetime(2024, 12, 31)
+        )
+
+        # Access spot data
+        spot_df = raw_data[RawDataType.SPOT.value]
+
+        # Check data type
+        if raw_data_type == RawDataType.SPOT:
+            print("Processing spot data")
+        ```
+
+    Note:
+        Future versions will add:
+        - FUTURES: Futures trading data
+        - PERPETUAL: Perpetual swaps data
+        - LOB: Limit order book data
+    """
+    SPOT = "spot"

signalflow/core/registry.py

@@ -0,0 +1,322 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Type
+from loguru import logger
+from .enums import SfComponentType
+
+
+@dataclass
+class SignalFlowRegistry:
+    """Component registry for dynamic component discovery and instantiation.
+
+    Provides centralized registration and lookup for SignalFlow components.
+    Components are organized by type (DETECTOR, EXTRACTOR, etc.) and 
+    accessed by case-insensitive names.
+
+    Registry structure:
+        component_type -> name -> class
+
+    Supported component types:
+        - DETECTOR: Signal detection classes
+        - EXTRACTOR: Feature extraction classes
+        - LABELER: Signal labeling classes
+        - ENTRY_RULE: Position entry rules
+        - EXIT_RULE: Position exit rules
+        - METRIC: Strategy metrics
+        - EXECUTOR: Order execution engines
+
+    Attributes:
+        _items (dict[SfComponentType, dict[str, Type[Any]]]): 
+            Internal storage mapping component types to name-class pairs.
+
+    Example:
+        ```python
+        from signalflow.core.registry import SignalFlowRegistry
+        from signalflow.core.enums import SfComponentType
+
+        # Create registry
+        registry = SignalFlowRegistry()
+
+        # Register component
+        registry.register(
+            SfComponentType.DETECTOR,
+            name="sma_cross",
+            cls=SmaCrossDetector
+        )
+
+        # Get component class
+        detector_cls = registry.get(SfComponentType.DETECTOR, "sma_cross")
+
+        # Instantiate component
+        detector = registry.create(
+            SfComponentType.DETECTOR,
+            "sma_cross",
+            fast_window=10,
+            slow_window=20
+        )
+
+        # List available components
+        detectors = registry.list(SfComponentType.DETECTOR)
+        print(f"Available detectors: {detectors}")
+
+        # Full snapshot
+        snapshot = registry.snapshot()
+        print(snapshot)
+        ```
+
+    Note:
+        Component names are stored and looked up in lowercase.
+        Use default_registry singleton for application-wide registration.
+
+    See Also:
+        sf_component: Decorator for automatic component registration.
+    """
+    #TODO: Registry autodiscover
+
+    _items: Dict[SfComponentType, Dict[str, Type[Any]]] = field(default_factory=dict)
+
+    def _ensure(self, component_type: SfComponentType) -> None:
+        """Ensure component type exists in registry.
+
+        Initializes empty dict for component_type if not present.
+
+        Args:
+            component_type (SfComponentType): Component type to ensure.
+        """
+        self._items.setdefault(component_type, {})
+
+    def register(self, component_type: SfComponentType, name: str, cls: Type[Any], *, override: bool = False) -> None:
+        """Register a class under (component_type, name).
+
+        Stores class in registry for later lookup and instantiation.
+        Names are normalized to lowercase for case-insensitive lookup.
+
+        Args:
+            component_type (SfComponentType): Type of component (DETECTOR, EXTRACTOR, etc.).
+            name (str): Registry name (case-insensitive, will be lowercased).
+            cls (Type[Any]): Class to register.
+            override (bool): Allow overriding existing registration. Default: False.
+
+        Raises:
+            ValueError: If name is empty or already registered (when override=False).
+
+        Example:
+            ```python
+            # Register new component
+            registry.register(
+                SfComponentType.DETECTOR,
+                name="my_detector",
+                cls=MyDetector
+            )
+
+            # Override existing component
+            registry.register(
+                SfComponentType.DETECTOR,
+                name="my_detector",
+                cls=ImprovedDetector,
+                override=True  # Logs warning
+            )
+
+            # Register multiple types
+            registry.register(SfComponentType.EXTRACTOR, "rsi", RsiExtractor)
+            registry.register(SfComponentType.LABELER, "fixed", FixedHorizonLabeler)
+            ```
+        """
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("name must be a non-empty string")
+
+        key = name.strip().lower()
+        self._ensure(component_type)
+
+        if key in self._items[component_type] and not override:
+            raise ValueError(f"{component_type.value}:{key} already registered")
+
+        if key in self._items[component_type] and override:
+            logger.warning(f"Overriding {component_type.value}:{key} with {cls.__name__}")
+
+        self._items[component_type][key] = cls
+
+    def get(self, component_type: SfComponentType, name: str) -> Type[Any]:
+        """Get a registered class by key.
+
+        Lookup is case-insensitive. Raises helpful error with available
+        components if key not found.
+
+        Args:
+            component_type (SfComponentType): Type of component to lookup.
+            name (str): Component name (case-insensitive).
+
+        Returns:
+            Type[Any]: Registered class.
+
+        Raises:
+            KeyError: If component not found. Error message includes available components.
+
+        Example:
+            ```python
+            # Get component class
+            detector_cls = registry.get(SfComponentType.DETECTOR, "sma_cross")
+
+            # Case-insensitive
+            detector_cls = registry.get(SfComponentType.DETECTOR, "SMA_Cross")
+
+            # Instantiate manually
+            detector = detector_cls(fast_window=10, slow_window=20)
+
+            # Handle missing component
+            try:
+                cls = registry.get(SfComponentType.DETECTOR, "unknown")
+            except KeyError as e:
+                print(f"Component not found: {e}")
+                # Shows: "Component not found: DETECTOR:unknown. Available: [sma_cross, ...]"
+            ```
+        """
+        self._ensure(component_type)
+        key = name.lower()
+        try:
+            return self._items[component_type][key]
+        except KeyError as e:
+            available = ", ".join(sorted(self._items[component_type]))
+            raise KeyError(
+                f"Component not found: {component_type.value}:{key}. Available: [{available}]"
+            ) from e
+
+    def create(self, component_type: SfComponentType, name: str, **kwargs: Any) -> Any:
+        """Instantiate a component by registry key.
+
+        Convenient method that combines get() and instantiation.
+
+        Args:
+            component_type (SfComponentType): Type of component to create.
+            name (str): Component name (case-insensitive).
+            **kwargs: Arguments to pass to component constructor.
+
+        Returns:
+            Any: Instantiated component.
+
+        Raises:
+            KeyError: If component not found.
+            TypeError: If kwargs don't match component constructor.
+
+        Example:
+            ```python
+            # Create detector with params
+            detector = registry.create(
+                SfComponentType.DETECTOR,
+                "sma_cross",
+                fast_window=10,
+                slow_window=20
+            )
+
+            # Create extractor
+            extractor = registry.create(
+                SfComponentType.EXTRACTOR,
+                "rsi",
+                window=14
+            )
+
+            # Create with config dict
+            config = {"window": 20, "threshold": 0.7}
+            labeler = registry.create(
+                SfComponentType.LABELER,
+                "fixed",
+                **config
+            )
+            ```
+        """
+        cls = self.get(component_type, name)
+        return cls(**kwargs)
+
+    def list(self, component_type: SfComponentType) -> list[str]:
+        """List registered components for a type.
+
+        Returns sorted list of component names for given type.
+
+        Args:
+            component_type (SfComponentType): Type of components to list.
+
+        Returns:
+            list[str]: Sorted list of registered component names.
+
+        Example:
+            ```python
+            # List all detectors
+            detectors = registry.list(SfComponentType.DETECTOR)
+            print(f"Available detectors: {detectors}")
+            # Output: ['ema_cross', 'macd', 'rsi_threshold', 'sma_cross']
+
+            # Check if component exists
+            if "sma_cross" in registry.list(SfComponentType.DETECTOR):
+                detector = registry.create(SfComponentType.DETECTOR, "sma_cross")
+
+            # List all component types
+            from signalflow.core.enums import SfComponentType
+            for component_type in SfComponentType:
+                components = registry.list(component_type)
+                print(f"{component_type.value}: {components}")
+            ```
+        """
+        self._ensure(component_type)
+        return sorted(self._items[component_type])
+
+    def snapshot(self) -> dict[str, list[str]]:
+        """Snapshot of registry for debugging.
+
+        Returns complete registry state organized by component type.
+
+        Returns:
+            dict[str, list[str]]: Dictionary mapping component type names 
+                to sorted lists of registered component names.
+
+        Example:
+            ```python
+            # Get full registry snapshot
+            snapshot = registry.snapshot()
+            print(snapshot)
+            # Output:
+            # {
+            #     'DETECTOR': ['ema_cross', 'sma_cross'],
+            #     'EXTRACTOR': ['rsi', 'sma'],
+            #     'LABELER': ['fixed', 'triple_barrier'],
+            #     'ENTRY_RULE': ['fixed_size'],
+            #     'EXIT_RULE': ['take_profit', 'time_based']
+            # }
+
+            # Use for debugging
+            import json
+            print(json.dumps(registry.snapshot(), indent=2))
+
+            # Check registration status
+            snapshot = registry.snapshot()
+            if 'DETECTOR' in snapshot and 'sma_cross' in snapshot['DETECTOR']:
+                print("SMA detector is registered")
+            ```
+        """
+        return {t.value: sorted(v.keys()) for t, v in self._items.items()}
+
+
+default_registry = SignalFlowRegistry()
+"""Global default registry instance.
+
+Use this singleton for application-wide component registration.
+
+Example:
+    ```python
+    from signalflow.core.registry import default_registry
+    from signalflow.core.enums import SfComponentType
+
+    # Register to default registry
+    default_registry.register(
+        SfComponentType.DETECTOR,
+        "my_detector",
+        MyDetector
+    )
+
+    # Access from anywhere
+    detector = default_registry.create(
+        SfComponentType.DETECTOR,
+        "my_detector"
+    )
+    ```
+"""