tradepose-client 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

tradepose_client/indicator_models.py

@@ -0,0 +1,300 @@
+"""
+Indicator Pydantic Models for Strong Typing
+
+为每个指标类型创建强类型的 Pydantic 模型，提供：
+- 编译时类型检查
+- IDE 自动补全
+- 参数验证
+- 与 Rust backend 对齐的序列化
+
+All models are aligned with Rust Indicator enum variants.
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+from pydantic import BaseModel, Field
+
+
+# ============================================================================
+# 移动平均类指标（Moving Average Indicators）
+# ============================================================================
+
+
+class SMAIndicator(BaseModel):
+    """Simple Moving Average (SMA) 指标
+
+    对应 Rust: Indicator::SMA { period, column }
+
+    Args:
+        period: 计算周期（必须 > 0）
+        column: 计算列名（默认 "close"）
+
+    Example:
+        >>> sma = SMAIndicator(period=20)
+        >>> sma = SMAIndicator(period=50, column="high")
+    """
+    type: Literal["SMA"] = "SMA"
+    period: int = Field(gt=0, le=500, description="Period must be > 0 and <= 500")
+    column: str = Field(
+        default="close",
+        pattern="^(open|high|low|close|volume)$",
+        description="OHLCV column name"
+    )
+
+
+class EMAIndicator(BaseModel):
+    """Exponential Moving Average (EMA) 指标
+
+    对应 Rust: Indicator::EMA { period, column }
+    """
+    type: Literal["EMA"] = "EMA"
+    period: int = Field(gt=0, le=500)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+
+
+class SMMAIndicator(BaseModel):
+    """Smoothed Moving Average (SMMA) 指标
+
+    对应 Rust: Indicator::SMMA { period, column }
+    """
+    type: Literal["SMMA"] = "SMMA"
+    period: int = Field(gt=0, le=500)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+
+
+class WMAIndicator(BaseModel):
+    """Weighted Moving Average (WMA) 指标
+
+    对应 Rust: Indicator::WMA { period, column }
+    """
+    type: Literal["WMA"] = "WMA"
+    period: int = Field(gt=0, le=500)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+
+
+# ============================================================================
+# 波动率类指标（Volatility Indicators）
+# ============================================================================
+
+
+class ATRIndicator(BaseModel):
+    """Average True Range (ATR) 指标
+
+    对应 Rust: Indicator::ATR { period }
+
+    Returns:
+        单一数值字段（不是 struct）
+
+    Example:
+        >>> atr = ATRIndicator(period=14)
+        >>> atr = ATRIndicator(period=21)
+    """
+    type: Literal["ATR"] = "ATR"
+    period: int = Field(gt=0, le=200, description="Period must be > 0 and <= 200")
+
+
+class ATRQuantileIndicator(BaseModel):
+    """ATR Rolling Quantile 指标
+
+    对应 Rust: Indicator::AtrQuantile { atr_column, window, quantile }
+
+    计算 ATR 的滚动分位数，用于动态止损等场景。
+
+    注意：这是依赖指标，必须先定义 ATR 指标。
+
+    Args:
+        atr_column: 引用的 ATR 列名（如 "ATR|14"）
+        window: 滚动窗口大小
+        quantile: 分位数值 (0, 1)，0.5 表示中位数
+
+    Returns:
+        单一数值字段（不是 struct）
+
+    Example:
+        >>> atr_q = ATRQuantileIndicator(
+        ...     atr_column="ATR|21",
+        ...     window=40,
+        ...     quantile=0.75  # 75th percentile
+        ... )
+    """
+    type: Literal["AtrQuantile"] = "AtrQuantile"
+    atr_column: str = Field(min_length=1, description="Reference to existing ATR column")
+    window: int = Field(gt=0, le=500, description="Rolling window size")
+    quantile: float = Field(gt=0, lt=1, description="Quantile value in (0, 1)")
+
+
+# ============================================================================
+# 趋势类指标（Trend Indicators）
+# ============================================================================
+
+
+class SuperTrendIndicator(BaseModel):
+    """SuperTrend 指标
+
+    对应 Rust: Indicator::SuperTrend { multiplier, volatility_column, high, low, close }
+
+    Args:
+        multiplier: ATR 倍数（通常 2.0-3.0）
+        volatility_column: 引用的波动率列名（如 "ATR|14"，注意是列名不是 struct 字段）
+        high: 高价列名（默认 "high"）
+        low: 低价列名（默认 "low"）
+        close: 收盘价列名（默认 "close"）
+
+    Returns:
+        Struct { direction: i32, value: f64, trend: f64, ...}
+
+    Example:
+        >>> st = SuperTrendIndicator(
+        ...     multiplier=3.0,
+        ...     volatility_column="ATR|21"
+        ... )
+    """
+    type: Literal["SuperTrend"] = "SuperTrend"
+    multiplier: float = Field(gt=0, le=10, description="ATR multiplier (typically 2.0-3.0)")
+    volatility_column: str = Field(
+        min_length=1,
+        description="Reference to volatility column (e.g., 'ATR|14')"
+    )
+    high: str = Field(default="high", pattern="^(high|open|low|close)$")
+    low: str = Field(default="low", pattern="^(high|open|low|close)$")
+    close: str = Field(default="close", pattern="^(high|open|low|close)$")
+
+
+class MACDIndicator(BaseModel):
+    """Moving Average Convergence Divergence (MACD) 指标
+
+    对应 Rust: Indicator::MACD { fast_period, slow_period, signal_period, column, fields }
+
+    Returns:
+        Struct { macd: f64, signal: f64, histogram: f64 }
+    """
+    type: Literal["MACD"] = "MACD"
+    fast_period: int = Field(default=12, gt=0, le=100)
+    slow_period: int = Field(default=26, gt=0, le=200)
+    signal_period: int = Field(default=9, gt=0, le=50)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+    fields: Optional[List[str]] = Field(
+        default=None,
+        description="Select specific fields: ['macd', 'signal', 'histogram']"
+    )
+
+
+class ADXIndicator(BaseModel):
+    """Average Directional Index (ADX) 指标
+
+    对应 Rust: Indicator::ADX { period, fields }
+
+    Returns:
+        Struct { adx: f64, plus_di: f64, minus_di: f64 }
+    """
+    type: Literal["ADX"] = "ADX"
+    period: int = Field(default=14, gt=0, le=100)
+    fields: Optional[List[str]] = Field(
+        default=None,
+        description="Select specific fields: ['adx', 'plus_di', 'minus_di']"
+    )
+
+
+# ============================================================================
+# 动量类指标（Momentum Indicators）
+# ============================================================================
+
+
+class RSIIndicator(BaseModel):
+    """Relative Strength Index (RSI) 指标
+
+    对应 Rust: Indicator::RSI { period, column }
+
+    Returns:
+        单一数值字段（0-100 范围）
+    """
+    type: Literal["RSI"] = "RSI"
+    period: int = Field(default=14, gt=0, le=100)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+
+
+class CCIIndicator(BaseModel):
+    """Commodity Channel Index (CCI) 指标
+
+    对应 Rust: Indicator::CCI { period }
+
+    Returns:
+        单一数值字段
+    """
+    type: Literal["CCI"] = "CCI"
+    period: int = Field(default=20, gt=0, le=100)
+
+
+class StochasticIndicator(BaseModel):
+    """Stochastic Oscillator 指标
+
+    对应 Rust: Indicator::Stochastic { k_period, d_period, fields }
+
+    Returns:
+        Struct { k: f64, d: f64 }
+    """
+    type: Literal["Stochastic"] = "Stochastic"
+    k_period: int = Field(default=14, gt=0, le=100, description="%K period")
+    d_period: int = Field(default=3, gt=0, le=50, description="%D period (smoothing)")
+    fields: Optional[List[str]] = Field(
+        default=None,
+        description="Select specific fields: ['k', 'd']"
+    )
+
+
+# ============================================================================
+# 其他指标（Other Indicators）
+# ============================================================================
+
+
+class BollingerBandsIndicator(BaseModel):
+    """Bollinger Bands 指标
+
+    对应 Rust: Indicator::BollingerBands { period, num_std, column, fields }
+
+    Returns:
+        Struct { upper: f64, middle: f64, lower: f64, bandwidth: f64 }
+    """
+    type: Literal["BollingerBands"] = "BollingerBands"
+    period: int = Field(default=20, gt=0, le=200)
+    num_std: float = Field(default=2.0, gt=0, le=5.0, description="Standard deviation multiplier")
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+    fields: Optional[List[str]] = Field(
+        default=None,
+        description="Select specific fields: ['upper', 'middle', 'lower', 'bandwidth']"
+    )
+
+
+class MarketProfileIndicator(BaseModel):
+    """Market Profile 指标
+
+    对应 Rust: Indicator::MarketProfile { anchor_config, tick_size, value_area_pct, fields }
+
+    Returns:
+        Struct { poc: f64, vah: f64, val: f64, value_area: List[f64], total_tpo: i32, ...}
+    """
+    type: Literal["MarketProfile"] = "MarketProfile"
+    anchor_config: Dict[str, Any] = Field(
+        ...,
+        description="Anchor configuration (use create_daily_anchor or create_weekly_anchor)"
+    )
+    tick_size: float = Field(gt=0, description="Tick size for price levels")
+    value_area_pct: float = Field(default=0.7, gt=0, lt=1, description="Value area percentage")
+    fields: Optional[List[str]] = Field(
+        default=None,
+        description="Select specific fields: ['poc', 'vah', 'val', 'value_area', 'total_tpo']"
+    )
+    shape_config: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Profile shape recognition config (advanced feature)"
+    )
+
+
+class RawOhlcvIndicator(BaseModel):
+    """Raw OHLCV Column 指标
+
+    对应 Rust: Indicator::RawOhlcv { column }
+
+    直接引用 OHLCV 列，用于需要原始数据的场景。
+    """
+    type: Literal["RawOhlcv"] = "RawOhlcv"
+    column: str = Field(pattern="^(open|high|low|close|volume)$")