signalflow-trading 0.2.1__py3-none-any.whl

signalflow/feature/base.py

@@ -0,0 +1,330 @@
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import polars as pl
+
+from signalflow.core import RawDataType, RollingAggregator, SfComponentType
+from typing import ClassVar
+
+
+@dataclass
+class FeatureExtractor(ABC):
+    """Base class for Polars-first feature extraction.
+
+    Extracts technical indicators and derived features from raw OHLCV data
+    with optional sliding window resampling for multi-timeframe features.
+
+    Key features:
+        - Polars-native for performance
+        - Optional sliding window resampling (e.g., 5m bars from 1m bars)
+        - Per-pair, per-offset-window processing
+        - Length-preserving operations
+        - Automatic projection (keep only new features)
+
+    Processing pipeline:
+        1. Sort by (pair, timestamp)
+        2. Add resample_offset column
+        3. (optional) Apply sliding resample
+        4. (optional) Filter to last offset
+        5. Group by (pair, resample_offset) and compute features
+        6. Sort output
+        7. Project columns (keep input or features only)
+
+    Attributes:
+        offset_window (int): Sliding window size in bars. Default: 1.
+        compute_last_offset (bool): Keep only last offset. Default: False.
+        pair_col (str): Trading pair column. Default: "pair".
+        ts_col (str): Timestamp column. Default: "timestamp".
+        offset_col (str): Offset tracking column. Default: "resample_offset".
+        use_resample (bool): Apply sliding resample. Default: False.
+        resample_mode (Literal["add", "replace"]): Resample mode. Default: "add".
+        resample_prefix (str | None): Prefix for resampled columns. Default: None.
+        raw_data_type (RawDataType): Type of raw data. Default: SPOT.
+        component_type (ClassVar[SfComponentType]): Always FEATURE_EXTRACTOR.
+        keep_input_columns (bool): Keep all input columns. Default: False.
+
+    Example:
+        ```python
+        from signalflow.feature import FeatureExtractor
+        import polars as pl
+
+        class RsiExtractor(FeatureExtractor):
+            '''RSI indicator extractor'''
+            
+            def __init__(self, window: int = 14, column: str = "close"):
+                super().__init__()
+                self.window = window
+                self.column = column
+            
+            def compute_group(self, group_df, data_context=None):
+                # Compute RSI per group
+                delta = group_df.select(pl.col(self.column).diff().alias("delta"))
+                
+                gain = delta.select(
+                    pl.when(pl.col("delta") > 0)
+                    .then(pl.col("delta"))
+                    .otherwise(0)
+                    .alias("gain")
+                )
+                
+                loss = delta.select(
+                    pl.when(pl.col("delta") < 0)
+                    .then(-pl.col("delta"))
+                    .otherwise(0)
+                    .alias("loss")
+                )
+                
+                avg_gain = gain.select(
+                    pl.col("gain").rolling_mean(self.window).alias("avg_gain")
+                )
+                
+                avg_loss = loss.select(
+                    pl.col("loss").rolling_mean(self.window).alias("avg_loss")
+                )
+                
+                rs = avg_gain.select(
+                    (pl.col("avg_gain") / pl.col("avg_loss")).alias("rs")
+                )
+                
+                rsi = group_df.with_columns([
+                    (100 - (100 / (1 + rs.get_column("rs")))).alias(f"rsi_{self.window}")
+                ])
+                
+                return rsi
+
+        # Usage
+        extractor = RsiExtractor(window=14)
+        features = extractor.extract(ohlcv_df)
+        ```
+
+    Note:
+        compute_group() must preserve row count (length-preserving).
+        All timestamps must be timezone-naive.
+        For multi-timeframe features, use use_resample=True.
+
+    See Also:
+        RollingAggregator: Sliding window resampler.
+        FeatureSet: Orchestrates multiple extractors.
+    """
+
+    offset_window: int = 1
+    compute_last_offset: bool = False
+
+    pair_col: str = "pair"
+    ts_col: str = "timestamp"
+    offset_col: str = "resample_offset"
+
+    use_resample: bool = False
+    resample_mode: Literal["add", "replace"] = "add"
+    resample_prefix: str | None = None
+    raw_data_type: RawDataType = RawDataType.SPOT
+    component_type: ClassVar[SfComponentType] = SfComponentType.FEATURE_EXTRACTOR
+    keep_input_columns: bool = False
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization.
+
+        Raises:
+            ValueError: If offset_window <= 0, invalid resample_mode, or wrong offset_col.
+            TypeError: If column names not strings.
+        """
+        if self.offset_window <= 0:
+            raise ValueError(f"offset_window must be > 0, got {self.offset_window}")
+
+        if self.resample_mode not in ("add", "replace"):
+            raise ValueError(f"Invalid resample_mode: {self.resample_mode}")
+
+        if self.offset_col != RollingAggregator.OFFSET_COL:
+            raise ValueError(
+                f"offset_col must be '{RollingAggregator.OFFSET_COL}', got '{self.offset_col}'"
+            )
+
+        if not isinstance(self.pair_col, str) or not isinstance(self.ts_col, str) or not isinstance(self.offset_col, str):
+            raise TypeError("pair_col/ts_col/offset_col must be str")
+
+    @property
+    def _resampler(self) -> RollingAggregator:
+        """Get configured RollingAggregator instance.
+
+        Returns:
+            RollingAggregator: Resampler with current configuration.
+        """
+        return RollingAggregator(
+            offset_window=self.offset_window,
+            ts_col=self.ts_col,
+            pair_col=self.pair_col,
+            mode=self.resample_mode,
+            prefix=self.resample_prefix,
+            raw_data_type=self.raw_data_type,
+        )
+
+    def extract(self, df: pl.DataFrame, data_context: dict[str, Any] | None = None) -> pl.DataFrame:
+        """Extract features from input DataFrame.
+
+        Main entry point - handles sorting, resampling, grouping, and projection.
+
+        Processing pipeline:
+            1. Validate input (required columns)
+            2. Sort by (pair, timestamp)
+            3. Add resample_offset column if missing
+            4. (optional) Apply sliding resample
+            5. (optional) Filter to last offset
+            6. Group by (pair, resample_offset) and compute features
+            7. Sort output
+            8. Project to output columns
+
+        Args:
+            df (pl.DataFrame): Input OHLCV data with pair and timestamp columns.
+            data_context (dict[str, Any] | None): Additional context for computation.
+
+        Returns:
+            pl.DataFrame: Features DataFrame with columns:
+                - pair, timestamp (always included)
+                - feature columns (from compute_group)
+
+        Raises:
+            TypeError: If df not pl.DataFrame or compute_group returns wrong type.
+            ValueError: If compute_group changes row count or columns missing.
+
+        Example:
+            ```python
+            # Basic extraction
+            features = extractor.extract(ohlcv_df)
+
+            # With resampling (5m from 1m)
+            extractor = RsiExtractor(
+                window=14,
+                offset_window=5,
+                use_resample=True
+            )
+            features = extractor.extract(ohlcv_df)
+
+            # Keep input columns
+            extractor.keep_input_columns = True
+            features_with_ohlcv = extractor.extract(ohlcv_df)
+            ```
+
+        Note:
+            Only accepts pl.DataFrame (Polars-first design).
+            Use PandasFeatureExtractor adapter for Pandas data.
+        """
+        if not isinstance(df, pl.DataFrame):
+            raise TypeError(
+                f"{self.__class__.__name__} is polars-first and accepts only pl.DataFrame. "
+                f"Got: {type(df)}. Use an adapter for other dataframe types."
+            )
+        self._validate_input(df)
+
+        df0 = df.sort([self.pair_col, self.ts_col])
+
+        if self.offset_col not in df0.columns:
+            df0 = self._resampler.add_offset_column(df0)
+
+        if self.use_resample:
+            df0 = self._resampler.resample(df0)
+
+        if self.compute_last_offset:
+            last_off = self._resampler.get_last_offset(df0)
+            df0 = df0.filter(pl.col(self.offset_col) == last_off)
+
+        prepared_cols = set(df0.columns)
+        inferred_features: set[str] = set()
+
+        def _wrapped(g: pl.DataFrame) -> pl.DataFrame:
+            nonlocal inferred_features
+
+            in_cols = set(g.columns)
+            out = self.compute_group(g, data_context=data_context)
+
+            if not isinstance(out, pl.DataFrame):
+                raise TypeError(f"{self.__class__.__name__}.compute_pl_group must return pl.DataFrame")
+
+            if out.height != g.height:
+                raise ValueError(
+                    f"{self.__class__.__name__}: len(output_group)={out.height} != len(input_group)={g.height}"
+                )
+
+            if not inferred_features:
+                inferred_features = set(out.columns) - in_cols
+
+            return out
+
+        out = (
+            df0.group_by(self.pair_col, self.offset_col, maintain_order=True)
+            .map_groups(_wrapped)
+            .sort([self.pair_col, self.ts_col])
+        )
+
+        if self.keep_input_columns:
+            return out
+
+        feature_cols = sorted(set(out.columns) - prepared_cols)
+        keep_cols = [self.pair_col, self.ts_col] + feature_cols
+
+        missing = [c for c in keep_cols if c not in out.columns]
+        if missing:
+            raise ValueError(f"Projection error, missing columns: {missing}")
+
+        return out.select(keep_cols)
+
+    def compute_group(
+        self,
+        group_df: pl.DataFrame,
+        data_context: dict[str, Any] | None,
+    ) -> pl.DataFrame:
+        """Compute features for single (pair, resample_offset) group.
+
+        Core feature extraction logic - must be implemented by subclasses.
+
+        CRITICAL: Must preserve row count (len(output) == len(input)).
+        Should preserve ordering within group.
+
+        Args:
+            group_df (pl.DataFrame): Single group's data, sorted by timestamp.
+            data_context (dict[str, Any] | None): Additional context.
+
+        Returns:
+            pl.DataFrame: Same length as input with added feature columns.
+
+        Example:
+            ```python
+            def compute_group(self, group_df, data_context=None):
+                # Simple moving average
+                return group_df.with_columns([
+                    pl.col("close")
+                    .rolling_mean(self.window)
+                    .alias(f"sma_{self.window}")
+                ])
+            
+            # Multiple features
+            def compute_group(self, group_df, data_context=None):
+                return group_df.with_columns([
+                    pl.col("close").rolling_mean(10).alias("sma_10"),
+                    pl.col("close").rolling_mean(20).alias("sma_20"),
+                    pl.col("high").rolling_max(14).alias("high_14"),
+                    pl.col("low").rolling_min(14).alias("low_14")
+                ])
+            ```
+
+        Note:
+            Output must have same height as input (length-preserving).
+            Use rolling operations for windowed features.
+            First N-1 bars may have null values for N-period indicators.
+        """
+        raise NotImplementedError
+
+    def _validate_input(self, df: pl.DataFrame) -> None:
+        """Validate input DataFrame has required columns.
+
+        Args:
+            df (pl.DataFrame): Input to validate.
+
+        Raises:
+            ValueError: If required columns missing.
+        """
+        missing = [c for c in (self.pair_col, self.ts_col) if c not in df.columns]
+        if missing:
+            raise ValueError(f"Missing required columns: {missing}")

signalflow/feature/feature_set.py

@@ -0,0 +1,286 @@
+# IMPORTANT
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import polars as pl
+
+from signalflow.feature.base import FeatureExtractor
+from signalflow.core import RawDataView, RawDataType, DataFrameType
+
+
+@dataclass
+class FeatureSet:
+    """Polars-first orchestrator for multiple feature extractors.
+
+    Combines independent feature extractors via outer join on (pair, timestamp).
+    Each extractor fetches its required data, computes features, and results
+    are merged into single DataFrame.
+
+    Key features:
+        - Automatic data fetching per extractor
+        - Timezone normalization (all → naive)
+        - Outer join on (pair, timestamp) for alignment
+        - Duplicate feature column detection
+        - Consistent index columns across extractors
+
+    Processing flow:
+        For each extractor:
+            1. Fetch appropriate raw data as Polars
+            2. Run extractor.extract()
+            3. Normalize timestamps to timezone-naive
+            4. Validate index columns present
+        Then:
+            5. Outer join all results on (pair, timestamp)
+
+    Attributes:
+        extractors (list[FeatureExtractor]): Feature extractors to orchestrate.
+        parallel (bool): Parallel execution flag (not yet implemented). Default: False.
+        pair_col (str): Trading pair column name. Default: "pair".
+        ts_col (str): Timestamp column name. Default: "timestamp".
+
+    Example:
+        ```python
+        from signalflow.feature import FeatureSet, SmaExtractor, RsiExtractor
+
+        # Create feature set
+        feature_set = FeatureSet([
+            SmaExtractor(window=10, column="close"),
+            SmaExtractor(window=20, column="close"),
+            RsiExtractor(window=14, column="close")
+        ])
+
+        # Extract all features at once
+        from signalflow.core import RawDataView
+        view = RawDataView(raw=raw_data)
+        features = feature_set.extract(view)
+
+        # Result has: pair, timestamp, sma_10, sma_20, rsi_14
+        print(features.columns)
+        # ['pair', 'timestamp', 'sma_10', 'sma_20', 'rsi_14']
+        ```
+
+    Example:
+        ```python
+        # With multi-timeframe features
+        feature_set = FeatureSet([
+            # 1-minute features
+            SmaExtractor(window=10, offset_window=1),
+            # 5-minute features
+            SmaExtractor(
+                window=10,
+                offset_window=5,
+                use_resample=True,
+                resample_prefix="5m_"
+            )
+        ])
+
+        features = feature_set.extract(view)
+        # Has both 1m and 5m features aligned
+        ```
+
+    Note:
+        All extractors must use same pair_col and ts_col.
+        Feature column names must be unique across extractors.
+        Timestamps automatically normalized to timezone-naive.
+
+    See Also:
+        FeatureExtractor: Base class for individual extractors.
+        RawDataView: Provides data in required format.
+    """
+
+    extractors: list[FeatureExtractor]
+    parallel: bool = False
+
+    pair_col: str = "pair"
+    ts_col: str = "timestamp"
+
+    def __post_init__(self) -> None:
+        """Validate extractors configuration.
+
+        Checks:
+            - At least one extractor provided
+            - All extractors use same pair_col
+            - All extractors use same ts_col
+
+        Raises:
+            ValueError: If validation fails.
+        """
+        if not self.extractors:
+            raise ValueError("At least one extractor must be provided")
+
+        for ex in self.extractors:
+            if getattr(ex, "pair_col", self.pair_col) != self.pair_col:
+                raise ValueError(
+                    f"All extractors must use pair_col='{self.pair_col}'. "
+                    f"{ex.__class__.__name__} uses '{getattr(ex, 'pair_col', None)}'"
+                )
+            if getattr(ex, "ts_col", self.ts_col) != self.ts_col:
+                raise ValueError(
+                    f"All extractors must use ts_col='{self.ts_col}'. "
+                    f"{ex.__class__.__name__} uses '{getattr(ex, 'ts_col', None)}'"
+                )
+
+    def extract(self, raw_data: RawDataView, context: dict[str, Any] | None = None) -> pl.DataFrame:
+        """Extract and combine features from all extractors.
+
+        Main entry point - orchestrates extraction and merging.
+
+        Processing:
+            1. For each extractor:
+                - Fetch appropriate data format
+                - Run extraction
+                - Normalize timestamps
+                - Validate output
+            2. Outer join all results on (pair, timestamp)
+            3. Detect duplicate feature columns
+
+        Args:
+            raw_data (RawDataView): View to raw market data.
+            context (dict[str, Any] | None): Additional context passed to extractors.
+
+        Returns:
+            pl.DataFrame: Combined features with columns:
+                - pair, timestamp (index)
+                - feature columns from all extractors
+
+        Raises:
+            ValueError: If no extractors or duplicate feature columns.
+            TypeError: If extractor doesn't return pl.DataFrame.
+
+        Example:
+            ```python
+            from signalflow.core import RawData, RawDataView
+
+            # Create view
+            view = RawDataView(raw=raw_data)
+
+            # Extract features
+            features = feature_set.extract(view)
+
+            # Check result
+            print(f"Features: {features.columns}")
+            print(f"Shape: {features.shape}")
+
+            # With context
+            features = feature_set.extract(
+                view,
+                context={"lookback_bars": 100}
+            )
+            ```
+
+        Note:
+            Outer join means all (pair, timestamp) combinations preserved.
+            Missing features filled with null for non-matching timestamps.
+        """
+        feature_dfs: list[pl.DataFrame] = []
+
+        for extractor in self.extractors:
+            input_df = self._get_input_df(raw_data, extractor)
+
+            result_df = extractor.extract(input_df, data_context=context)
+            if not isinstance(result_df, pl.DataFrame):
+                raise TypeError(
+                    f"{extractor.__class__.__name__}.extract must return pl.DataFrame, got {type(result_df)}"
+                )
+
+            result_df = self._normalize_index(result_df)
+
+            if self.pair_col not in result_df.columns or self.ts_col not in result_df.columns:
+                raise ValueError(
+                    f"{extractor.__class__.__name__} returned no index columns "
+                    f"('{self.pair_col}', '{self.ts_col}'). "
+                    f"FeatureSet requires index columns to combine features."
+                )
+
+            feature_dfs.append(result_df)
+
+        return self._combine_features(feature_dfs)
+
+    def _get_input_df(self, raw_data: RawDataView, extractor: FeatureExtractor) -> pl.DataFrame:
+        """Fetch input data for extractor in Polars format.
+
+        Determines required data type from extractor.raw_data_type and
+        fetches as Polars DataFrame (canonical format).
+
+        Args:
+            raw_data (RawDataView): Data view.
+            extractor (FeatureExtractor): Extractor needing data.
+
+        Returns:
+            pl.DataFrame: Raw data in Polars format.
+
+        Note:
+            Always returns Polars (Polars-first design).
+            Falls back to string "polars" for backward compatibility.
+        """
+        raw_data_type = getattr(extractor, "raw_data_type", RawDataType.SPOT)
+
+        try:
+            return raw_data.get_data(raw_data_type, DataFrameType.POLARS)
+        except TypeError:
+            return raw_data.get_data(raw_data_type, "polars")
+
+    def _normalize_index(self, df: pl.DataFrame) -> pl.DataFrame:
+        """Normalize timestamp to timezone-naive.
+
+        Ensures consistent timezone handling across all extractors.
+
+        Args:
+            df (pl.DataFrame): DataFrame to normalize.
+
+        Returns:
+            pl.DataFrame: DataFrame with timezone-naive timestamps.
+        """
+        if self.ts_col in df.columns:
+            ts_dtype = df.schema.get(self.ts_col)
+            if isinstance(ts_dtype, pl.Datetime) and ts_dtype.time_zone is not None:
+                df = df.with_columns(pl.col(self.ts_col).dt.replace_time_zone(None))
+        return df
+
+    def _combine_features(self, feature_dfs: list[pl.DataFrame]) -> pl.DataFrame:
+        """Combine feature DataFrames via outer join.
+
+        Merges all feature DataFrames on (pair, timestamp) index.
+        Detects and rejects duplicate feature column names.
+
+        Args:
+            feature_dfs (list[pl.DataFrame]): Feature DataFrames to combine.
+
+        Returns:
+            pl.DataFrame: Combined features with outer join semantics.
+
+        Raises:
+            ValueError: If no DataFrames or duplicate feature columns found.
+
+        Example:
+            ```python
+            # Internal usage
+            df1 = pl.DataFrame({"pair": ["BTC"], "timestamp": [t1], "sma_10": [45000]})
+            df2 = pl.DataFrame({"pair": ["BTC"], "timestamp": [t1], "rsi_14": [50]})
+            combined = self._combine_features([df1, df2])
+            # Result: pair, timestamp, sma_10, rsi_14
+            ```
+
+        Note:
+            Outer join preserves all (pair, timestamp) from all extractors.
+            Duplicate columns trigger error - use unique prefixes.
+        """
+        if not feature_dfs:
+            raise ValueError("No feature DataFrames to combine")
+
+        combined = feature_dfs[0]
+
+        for right in feature_dfs[1:]:
+            right_feature_cols = [c for c in right.columns if c not in (self.pair_col, self.ts_col)]
+            dup = set(right_feature_cols).intersection(set(combined.columns))
+            if dup:
+                raise ValueError(
+                    f"Duplicate feature columns during FeatureSet combine: {sorted(dup)}. "
+                    f"Rename features or set unique prefixes."
+                )
+
+            combined = combined.join(right, on=[self.pair_col, self.ts_col], how="outer", coalesce=True)
+
+        return combined

signalflow/feature/oscillator/__init__.py

@@ -0,0 +1,5 @@
+from signalflow.feature.oscillator.rsi_extractor import RsiExtractor
+
+__all__ = [
+    "RsiExtractor"
+]

signalflow/feature/oscillator/rsi_extractor.py

@@ -0,0 +1,42 @@
+# IMPORTANT
+
+from dataclasses import dataclass
+import polars as pl
+from signalflow.feature.base import FeatureExtractor
+from signalflow.core import sf_component
+
+
+@dataclass
+@sf_component(name="rsi")
+class RsiExtractor(FeatureExtractor):
+    rsi_period: int = 14
+    price_col: str = "close"
+    out_col: str = "rsi"
+    use_resample:bool = True
+
+    def compute_group(self, group_df: pl.DataFrame, data_context: dict | None) -> pl.DataFrame:
+        price = pl.col(self.price_col)
+        delta = price.diff()
+
+        gain = delta.clip(lower_bound=0.0)
+        loss = (-delta).clip(lower_bound=0.0)
+
+        avg_gain = gain.rolling_mean(
+            window_size=self.rsi_period,
+            min_samples=self.rsi_period,
+        )
+        avg_loss = loss.rolling_mean(
+            window_size=self.rsi_period,
+            min_samples=self.rsi_period,
+        )
+
+
+        rs = avg_gain / avg_loss
+
+        rsi = (
+            pl.when((avg_loss == 0) & (avg_gain == 0)).then(50.0)
+            .when(avg_loss == 0).then(100.0)
+            .otherwise(100.0 - (100.0 / (1.0 + rs)))
+        )
+
+        return group_df.with_columns(rsi.alias(self.out_col))

signalflow/feature/pandasta/__init__.py

@@ -0,0 +1,10 @@
+from signalflow.feature.pandasta.pandas_ta_extractor import PandasTaExtractor
+from signalflow.feature.pandasta.top_pandasta_extractors import PandasTaRsiExtractor, PandasTaBbandsExtractor, PandasTaMacdExtractor, PandasTaAtrExtractor
+
+__all__ = [
+    "PandasTaExtractor",
+    "PandasTaRsiExtractor",
+    "PandasTaBbandsExtractor",
+    "PandasTaMacdExtractor",
+    "PandasTaAtrExtractor",
+]