quantmllibrary 0.1.0__py3-none-any.whl

quantml/features/base.py

@@ -0,0 +1,104 @@
+"""
+Base feature class for plugin-based feature system.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class FeatureMetadata:
+    """Metadata for a feature."""
+    name: str
+    description: str
+    formula: Optional[str] = None
+    expected_range: Optional[tuple] = None
+    unit: Optional[str] = None
+
+
+class BaseFeature(ABC):
+    """
+    Base class for all features.
+    
+    All features should inherit from this class and implement the compute method.
+    """
+    
+    def __init__(self, name: str, description: str = "", **kwargs):
+        """
+        Initialize feature.
+        
+        Args:
+            name: Feature name
+            description: Feature description
+            **kwargs: Feature-specific parameters
+        """
+        self.name = name
+        self.description = description
+        self.params = kwargs
+        self.metadata = FeatureMetadata(
+            name=name,
+            description=description
+        )
+    
+    @abstractmethod
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """
+        Compute feature values.
+        
+        Args:
+            data: Dictionary with required data (e.g., {'price': [...], 'volume': [...]})
+        
+        Returns:
+            List of feature values
+        """
+        pass
+    
+    def get_metadata(self) -> FeatureMetadata:
+        """Get feature metadata."""
+        return self.metadata
+    
+    def validate_data(self, data: Dict[str, List[float]], required_keys: List[str]) -> bool:
+        """
+        Validate that required data keys are present.
+        
+        Args:
+            data: Data dictionary
+            required_keys: List of required keys
+        
+        Returns:
+            True if all required keys present
+        """
+        return all(key in data for key in required_keys)
+
+
+class Feature(BaseFeature):
+    """
+    Simple feature implementation.
+    
+    Use this for simple features that don't need complex logic.
+    """
+    
+    def __init__(
+        self,
+        name: str,
+        compute_fn: callable,
+        description: str = "",
+        **kwargs
+    ):
+        """
+        Initialize feature with compute function.
+        
+        Args:
+            name: Feature name
+            compute_fn: Function to compute feature: compute_fn(data) -> List[float]
+            description: Feature description
+            **kwargs: Additional parameters
+        """
+        super().__init__(name, description, **kwargs)
+        self.compute_fn = compute_fn
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """Compute feature using provided function."""
+        return self.compute_fn(data, **self.params)
+

quantml/features/gap_features.py

@@ -0,0 +1,124 @@
+"""
+Overnight gap features for futures trading.
+"""
+
+from typing import List, Dict
+from quantml.features.base import BaseFeature, FeatureMetadata
+
+
+class OvernightGapFeature(BaseFeature):
+    """
+    Overnight gap feature.
+    
+    Computes the gap between previous day's close and current day's open.
+    """
+    
+    def __init__(self, normalize: bool = True):
+        """
+        Initialize overnight gap feature.
+        
+        Args:
+            normalize: Whether to normalize gap by previous close
+        """
+        super().__init__(
+            name="overnight_gap",
+            description="Gap between previous close and current open",
+            normalize=normalize
+        )
+        self.metadata.formula = "gap = (open(t) - close(t-1)) / close(t-1) if normalize else open(t) - close(t-1)"
+        self.metadata.expected_range = (-0.1, 0.1) if normalize else None
+        self.metadata.unit = "fraction" if normalize else "price_units"
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """Compute overnight gaps."""
+        if not self.validate_data(data, ['open', 'close']):
+            raise ValueError("OvernightGapFeature requires 'open' and 'close' in data")
+        
+        opens = data['open']
+        closes = data['close']
+        
+        gaps = [0.0]  # First gap is 0 (no previous close)
+        
+        for i in range(1, len(opens)):
+            if closes[i-1] > 0:
+                if self.params.get('normalize', True):
+                    gap = (opens[i] - closes[i-1]) / closes[i-1]
+                else:
+                    gap = opens[i] - closes[i-1]
+            else:
+                gap = 0.0
+            gaps.append(gap)
+        
+        return gaps
+
+
+class GapSizeFeature(BaseFeature):
+    """
+    Gap size feature (absolute value of gap).
+    """
+    
+    def __init__(self, normalize: bool = True):
+        """
+        Initialize gap size feature.
+        
+        Args:
+            normalize: Whether to normalize by previous close
+        """
+        super().__init__(
+            name="gap_size",
+            description="Absolute size of overnight gap",
+            normalize=normalize
+        )
+        self.metadata.formula = "gap_size = |gap|"
+        self.metadata.expected_range = (0.0, 0.1) if normalize else None
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]):
+        """Compute gap sizes."""
+        gap_feature = OvernightGapFeature(normalize=self.params.get('normalize', True))
+        gaps = gap_feature.compute(data)
+        return [abs(g) for g in gaps]
+
+
+class GapClosureFeature(BaseFeature):
+    """
+    Gap closure feature (whether gap closed during the day).
+    """
+    
+    def __init__(self):
+        """Initialize gap closure feature."""
+        super().__init__(
+            name="gap_closure",
+            description="Binary indicator if overnight gap closed during day"
+        )
+        self.metadata.formula = "gap_closed = 1 if gap closed, 0 otherwise"
+        self.metadata.expected_range = (0, 1)
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """Compute gap closure indicators."""
+        if not self.validate_data(data, ['open', 'close', 'high', 'low']):
+            raise ValueError("GapClosureFeature requires 'open', 'close', 'high', 'low'")
+        
+        opens = data['open']
+        closes = data['close']
+        highs = data['high']
+        lows = data['low']
+        
+        closures = [0.0]  # First day has no gap
+        
+        for i in range(1, len(opens)):
+            prev_close = closes[i-1]
+            gap = opens[i] - prev_close
+            
+            if abs(gap) < 0.0001:  # No gap
+                closures.append(0.0)
+            elif gap > 0:  # Gap up
+                # Gap closed if low <= prev_close
+                closed = 1.0 if lows[i] <= prev_close else 0.0
+                closures.append(closed)
+            else:  # Gap down
+                # Gap closed if high >= prev_close
+                closed = 1.0 if highs[i] >= prev_close else 0.0
+                closures.append(closed)
+        
+        return closures
+

quantml/features/registry.py

@@ -0,0 +1,138 @@
+"""
+Feature registry for plugin-based feature system.
+"""
+
+from typing import Dict, List, Optional, Callable
+from quantml.features.base import BaseFeature, FeatureMetadata
+
+
+class FeatureRegistry:
+    """Registry for managing features."""
+    
+    _instance = None
+    _features: Dict[str, BaseFeature] = {}
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def register(self, feature: BaseFeature, name: Optional[str] = None):
+        """
+        Register a feature.
+        
+        Args:
+            feature: Feature instance
+            name: Optional name override (default: feature.name)
+        """
+        feature_name = name or feature.name
+        self._features[feature_name] = feature
+    
+    def get(self, name: str) -> Optional[BaseFeature]:
+        """
+        Get feature by name.
+        
+        Args:
+            name: Feature name
+        
+        Returns:
+            Feature instance or None
+        """
+        return self._features.get(name)
+    
+    def list_features(self) -> List[str]:
+        """List all registered feature names."""
+        return list(self._features.keys())
+    
+    def get_all(self) -> Dict[str, BaseFeature]:
+        """Get all registered features."""
+        return self._features.copy()
+    
+    def compute_features(
+        self,
+        feature_names: List[str],
+        data: Dict[str, List[float]]
+    ) -> Dict[str, List[float]]:
+        """
+        Compute multiple features.
+        
+        Args:
+            feature_names: List of feature names to compute
+            data: Input data dictionary
+        
+        Returns:
+            Dictionary of feature name -> feature values
+        """
+        results = {}
+        
+        for name in feature_names:
+            feature = self.get(name)
+            if feature is None:
+                raise ValueError(f"Feature not found: {name}")
+            
+            try:
+                values = feature.compute(data)
+                results[name] = values
+            except Exception as e:
+                raise RuntimeError(f"Error computing feature {name}: {e}")
+        
+        return results
+    
+    def get_metadata(self, name: str) -> Optional[FeatureMetadata]:
+        """
+        Get feature metadata.
+        
+        Args:
+            name: Feature name
+        
+        Returns:
+            FeatureMetadata or None
+        """
+        feature = self.get(name)
+        return feature.get_metadata() if feature else None
+
+
+# Global registry instance
+_registry = FeatureRegistry()
+
+
+def register_feature(feature: BaseFeature, name: Optional[str] = None):
+    """
+    Register a feature in the global registry.
+    
+    Args:
+        feature: Feature instance
+        name: Optional name override
+    """
+    _registry.register(feature, name)
+
+
+def get_feature(name: str) -> Optional[BaseFeature]:
+    """
+    Get feature from global registry.
+    
+    Args:
+        name: Feature name
+    
+    Returns:
+        Feature instance or None
+    """
+    return _registry.get(name)
+
+
+def compute_features(
+    feature_names: List[str],
+    data: Dict[str, List[float]]
+) -> Dict[str, List[float]]:
+    """
+    Compute multiple features from registry.
+    
+    Args:
+        feature_names: List of feature names
+        data: Input data
+    
+    Returns:
+        Dictionary of computed features
+    """
+    return _registry.compute_features(feature_names, data)
+

quantml/features/volatility_features.py

@@ -0,0 +1,140 @@
+"""
+Volatility-based features.
+"""
+
+from typing import List, Dict
+from quantml.features.base import BaseFeature, FeatureMetadata
+
+
+class VolatilityRegimeFeature(BaseFeature):
+    """
+    Volatility regime feature (low/normal/high volatility).
+    """
+    
+    def __init__(self, window: int = 20, low_threshold: float = 0.25, high_threshold: float = 0.75):
+        """
+        Initialize volatility regime feature.
+        
+        Args:
+            window: Window for volatility calculation
+            low_threshold: Percentile for low volatility
+            high_threshold: Percentile for high volatility
+        """
+        super().__init__(
+            name="volatility_regime",
+            description="Volatility regime (0=low, 1=normal, 2=high)",
+            window=window,
+            low_threshold=low_threshold,
+            high_threshold=high_threshold
+        )
+        self.metadata.formula = "regime based on realized volatility percentiles"
+        self.metadata.expected_range = (0, 2)
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """Compute volatility regimes."""
+        if not self.validate_data(data, ['price']):
+            raise ValueError("VolatilityRegimeFeature requires 'price' in data")
+        
+        prices = data['price']
+        window = self.params.get('window', 20)
+        
+        # Calculate returns
+        returns = []
+        for i in range(1, len(prices)):
+            if prices[i-1] > 0:
+                ret = (prices[i] - prices[i-1]) / prices[i-1]
+            else:
+                ret = 0.0
+            returns.append(ret)
+        
+        # Calculate rolling volatility
+        volatilities = []
+        for i in range(window, len(returns)):
+            window_rets = returns[i-window:i]
+            mean_ret = sum(window_rets) / len(window_rets)
+            variance = sum((r - mean_ret) ** 2 for r in window_rets) / len(window_rets)
+            vol = variance ** 0.5
+            volatilities.append(vol)
+        
+        if len(volatilities) < 2:
+            return [1.0] * len(prices)  # Default to normal
+        
+        # Calculate percentiles
+        sorted_vols = sorted(volatilities)
+        low_idx = int(len(sorted_vols) * self.params['low_threshold'])
+        high_idx = int(len(sorted_vols) * self.params['high_threshold'])
+        
+        low_threshold = sorted_vols[low_idx]
+        high_threshold = sorted_vols[high_idx]
+        
+        # Map to regimes
+        regimes = [1.0] * window  # Not enough data
+        
+        for vol in volatilities:
+            if vol < low_threshold:
+                regimes.append(0.0)
+            elif vol >= high_threshold:
+                regimes.append(2.0)
+            else:
+                regimes.append(1.0)
+        
+        return regimes
+
+
+class RealizedVolatilityFeature(BaseFeature):
+    """
+    Realized volatility feature.
+    """
+    
+    def __init__(self, window: int = 20, annualize: bool = True):
+        """
+        Initialize realized volatility feature.
+        
+        Args:
+            window: Rolling window
+            annualize: Whether to annualize (multiply by sqrt(252))
+        """
+        super().__init__(
+            name="realized_volatility",
+            description="Realized volatility (std of returns)",
+            window=window,
+            annualize=annualize
+        )
+        self.metadata.formula = "vol = std(returns) * sqrt(252) if annualize"
+        self.metadata.expected_range = (0.0, 1.0)
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """Compute realized volatility."""
+        if not self.validate_data(data, ['price']):
+            raise ValueError("RealizedVolatilityFeature requires 'price' in data")
+        
+        prices = data['price']
+        window = self.params.get('window', 20)
+        annualize = self.params.get('annualize', True)
+        
+        # Calculate returns
+        returns = []
+        for i in range(1, len(prices)):
+            if prices[i-1] > 0:
+                ret = (prices[i] - prices[i-1]) / prices[i-1]
+            else:
+                ret = 0.0
+            returns.append(ret)
+        
+        # Calculate rolling volatility
+        volatilities = [0.0] * min(window, len(prices))
+        
+        for i in range(window, len(returns)):
+            window_rets = returns[i-window:i]
+            mean_ret = sum(window_rets) / len(window_rets)
+            variance = sum((r - mean_ret) ** 2 for r in window_rets) / len(window_rets)
+            vol = variance ** 0.5
+            
+            if annualize:
+                import math
+                vol = vol * math.sqrt(252)
+            
+            volatilities.append(vol)
+        
+        return volatilities
+

quantml/features/volume_features.py

@@ -0,0 +1,142 @@
+"""
+Volume-based features.
+"""
+
+from typing import List, Dict
+from quantml.features.base import BaseFeature, FeatureMetadata
+
+
+class VolumeRegimeFeature(BaseFeature):
+    """
+    Volume regime feature (low/normal/high volume).
+    """
+    
+    def __init__(self, low_threshold: float = 0.25, high_threshold: float = 0.75):
+        """
+        Initialize volume regime feature.
+        
+        Args:
+            low_threshold: Percentile for low volume (default: 25th)
+            high_threshold: Percentile for high volume (default: 75th)
+        """
+        super().__init__(
+            name="volume_regime",
+            description="Volume regime classification (0=low, 1=normal, 2=high)",
+            low_threshold=low_threshold,
+            high_threshold=high_threshold
+        )
+        self.metadata.formula = "regime = 0 if volume < p25, 1 if p25 <= volume < p75, 2 if volume >= p75"
+        self.metadata.expected_range = (0, 2)
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """Compute volume regimes."""
+        if not self.validate_data(data, ['volume']):
+            raise ValueError("VolumeRegimeFeature requires 'volume' in data")
+        
+        volumes = data['volume']
+        
+        if len(volumes) < 20:
+            return [1.0] * len(volumes)  # Default to normal
+        
+        # Calculate percentiles
+        sorted_vols = sorted(volumes)
+        low_idx = int(len(sorted_vols) * self.params['low_threshold'])
+        high_idx = int(len(sorted_vols) * self.params['high_threshold'])
+        
+        low_threshold = sorted_vols[low_idx]
+        high_threshold = sorted_vols[high_idx]
+        
+        regimes = []
+        for vol in volumes:
+            if vol < low_threshold:
+                regimes.append(0.0)
+            elif vol >= high_threshold:
+                regimes.append(2.0)
+            else:
+                regimes.append(1.0)
+        
+        return regimes
+
+
+class VolumeShockFeature(BaseFeature):
+    """
+    Volume shock feature (unusual volume).
+    """
+    
+    def __init__(self, window: int = 20, threshold: float = 2.0):
+        """
+        Initialize volume shock feature.
+        
+        Args:
+            window: Rolling window for volume average
+            threshold: Multiplier threshold for shock (default: 2x average)
+        """
+        super().__init__(
+            name="volume_shock",
+            description="Binary indicator for volume shock (1 if volume > threshold * avg)",
+            window=window,
+            threshold=threshold
+        )
+        self.metadata.formula = "shock = 1 if volume > threshold * rolling_mean(volume, window)"
+        self.metadata.expected_range = (0, 1)
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """Compute volume shocks."""
+        if not self.validate_data(data, ['volume']):
+            raise ValueError("VolumeShockFeature requires 'volume' in data")
+        
+        volumes = data['volume']
+        window = self.params.get('window', 20)
+        threshold = self.params.get('threshold', 2.0)
+        
+        shocks = [0.0] * min(window, len(volumes))  # Not enough data
+        
+        for i in range(window, len(volumes)):
+            window_vols = volumes[i-window:i]
+            avg_volume = sum(window_vols) / len(window_vols)
+            
+            shock = 1.0 if volumes[i] > threshold * avg_volume else 0.0
+            shocks.append(shock)
+        
+        return shocks
+
+
+class VolumeRatioFeature(BaseFeature):
+    """
+    Volume ratio feature (current volume / average volume).
+    """
+    
+    def __init__(self, window: int = 20):
+        """
+        Initialize volume ratio feature.
+        
+        Args:
+            window: Rolling window for average volume
+        """
+        super().__init__(
+            name="volume_ratio",
+            description="Ratio of current volume to rolling average",
+            window=window
+        )
+        self.metadata.formula = "volume_ratio = volume(t) / mean(volume(t-window:t))"
+        self.metadata.expected_range = (0.0, 10.0)
+    
+    def compute(self, data: Dict[str, List[float]]) -> List[float]:
+        """Compute volume ratios."""
+        if not self.validate_data(data, ['volume']):
+            raise ValueError("VolumeRatioFeature requires 'volume' in data")
+        
+        volumes = data['volume']
+        window = self.params.get('window', 20)
+        
+        ratios = [1.0] * min(window, len(volumes))
+        
+        for i in range(window, len(volumes)):
+            window_vols = volumes[i-window:i]
+            avg_volume = sum(window_vols) / len(window_vols)
+            
+            ratio = volumes[i] / avg_volume if avg_volume > 0 else 1.0
+            ratios.append(ratio)
+        
+        return ratios
+

quantml/functional.py

@@ -0,0 +1,37 @@
+"""
+Functional API for QuantML operations.
+
+This module provides a convenient functional interface to all operations,
+similar to PyTorch's functional API. Use this for a cleaner API when
+composing operations.
+"""
+
+from typing import Union, Optional
+from quantml.tensor import Tensor
+from quantml import ops
+
+# Re-export all operations with F. prefix
+add = ops.add
+sub = ops.sub
+mul = ops.mul
+div = ops.div
+pow = ops.pow
+matmul = ops.matmul
+dot = ops.dot
+sum = ops.sum
+mean = ops.mean
+std = ops.std
+relu = ops.relu
+sigmoid = ops.sigmoid
+tanh = ops.tanh
+abs = ops.abs
+maximum = ops.maximum
+
+__all__ = [
+    'add', 'sub', 'mul', 'div', 'pow',
+    'matmul', 'dot',
+    'sum', 'mean', 'std',
+    'relu', 'sigmoid', 'tanh',
+    'abs', 'maximum'
+]
+