"""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."""