feat: signal abstraction layer + sizer + HS300 universe + PnL/IC reports

signals/__init__.py

@@ -0,0 +1,5 @@
+"""Alpha signal abstractions."""
+from signals.base import AlphaSignal
+from signals.reversal import ReversalSignal
+
+__all__ = ["AlphaSignal", "ReversalSignal"]

signals/base.py

@@ -0,0 +1,28 @@
+"""Base class for cross-sectional alpha signals."""
+from abc import ABC, abstractmethod
+
+import pandas as pd
+
+
+class AlphaSignal(ABC):
+    """A signal that maps a single stock's OHLCV history to a per-bar score.
+
+    Higher scores indicate a stronger expected forward return. Implementations
+    operate on one stock at a time; cross-sectional ranking happens downstream.
+    """
+
+    @abstractmethod
+    def compute(self, df: pd.DataFrame) -> pd.Series:
+        """Compute the signal for one stock.
+
+        Args:
+            df: OHLCV DataFrame with at least a ``close`` column, ordered by date.
+
+        Returns:
+            Signal series aligned to ``df`` (NaN where undefined).
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable signal identifier."""

signals/reversal.py

@@ -0,0 +1,22 @@
+"""Short-horizon reversal signal."""
+import pandas as pd
+
+from signals.base import AlphaSignal
+
+
+class ReversalSignal(AlphaSignal):
+    """Negative trailing return: oversold stocks score high.
+
+    The signal is ``-close.pct_change(lookback)``, so a stock that fell over the
+    lookback window gets a positive (bullish) score.
+    """
+
+    def __init__(self, lookback: int = 5):
+        self.lookback = lookback
+
+    def compute(self, df: pd.DataFrame) -> pd.Series:
+        return -df["close"].pct_change(self.lookback)
+
+    @property
+    def name(self) -> str:
+        return f"reversal_{self.lookback}d"