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

tradepose_client/builder/trading_context.py

@@ -33,9 +33,11 @@ class TradingContextProxy:
         context_type: 上下文类型（"base" 或 "advanced"）
     """
 
-    def __init__(self, context_name: str, context_type: str):
+    def __init__(
+        self,
+        context_name: str,
+    ):
         self._context_name = context_name
-        self._context_type = context_type
 
     @property
     def entry_price(self) -> pl.Expr:
@@ -59,32 +61,8 @@ class TradingContextProxy:
             - base_trading_context 使用 "bars_in_position"
             - advanced 使用 "bars_since_advanced_entry"（请用 .bars_since_entry）
         """
-        if self._context_type != "base":
-            raise AttributeError(
-                f"'bars_in_position' only available for base context. "
-                f"Use '.bars_since_entry' for advanced contexts."
-            )
         return pl.col(self._context_name).struct.field("bars_in_position")
 
-    @property
-    def bars_since_entry(self) -> pl.Expr:
-        """
-        进场后 K 线数（仅适用于 advanced contexts）
-
-        Returns:
-            pl.Expr: Polars 表达式
-
-        Note:
-            - advanced_entry/exit_trading_context 使用 "bars_since_advanced_entry"
-            - base 使用 "bars_in_position"（请用 .bars_in_position）
-        """
-        if self._context_type == "base":
-            raise AttributeError(
-                f"'bars_since_entry' not available for base context. "
-                f"Use '.bars_in_position' for base context."
-            )
-        return pl.col(self._context_name).struct.field("bars_since_advanced_entry")
-
     @property
     def highest_since_entry(self) -> pl.Expr:
         """
@@ -151,9 +129,9 @@ class TradingContext:
         timeout_condition = TradingContext.advanced_entry.bars_since_entry > 100
     """
 
-    base = TradingContextProxy("base_trading_context", "base")
-    advanced_entry = TradingContextProxy("advanced_entry_trading_context", "advanced")
-    advanced_exit = TradingContextProxy("advanced_exit_trading_context", "advanced")
+    base = TradingContextProxy("base_trading_context")
+    advanced_entry = TradingContextProxy("advanced_entry_trading_context")
+    advanced_exit = TradingContextProxy("advanced_exit_trading_context")
 
 
 # 向后兼容的别名

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)$")

tradepose_client/models.py

@@ -9,14 +9,87 @@ Pydantic 模型用於策略配置 (V2 - 自動轉換版本)
 import json
 from enum import Enum
 from io import StringIO
-from typing import Any, Dict, List, Optional, Union
+from typing import Annotated, Any, Dict, List, Optional, Union
 
 import polars as pl
-from pydantic import BaseModel, Field, field_serializer, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
 
 # Import enums from enums.py
 from .enums import Freq, OrderStrategy, Weekday, TradeDirection, TrendType
 
+# Import Indicator models
+from .indicator_models import (
+    SMAIndicator,
+    EMAIndicator,
+    SMMAIndicator,
+    WMAIndicator,
+    ATRIndicator,
+    ATRQuantileIndicator,
+    SuperTrendIndicator,
+    MACDIndicator,
+    ADXIndicator,
+    RSIIndicator,
+    CCIIndicator,
+    StochasticIndicator,
+    BollingerBandsIndicator,
+    MarketProfileIndicator,
+    RawOhlcvIndicator,
+)
+
+
+# ============================================================================
+# Indicator Discriminated Union (强类型 Indicator 配置)
+# ============================================================================
+
+IndicatorConfig = Annotated[
+    Union[
+        # 移动平均类
+        SMAIndicator,
+        EMAIndicator,
+        SMMAIndicator,
+        WMAIndicator,
+        # 波动率类
+        ATRIndicator,
+        ATRQuantileIndicator,
+        # 趋势类
+        SuperTrendIndicator,
+        MACDIndicator,
+        ADXIndicator,
+        # 动量类
+        RSIIndicator,
+        CCIIndicator,
+        StochasticIndicator,
+        # 其他
+        BollingerBandsIndicator,
+        MarketProfileIndicator,
+        RawOhlcvIndicator,
+    ],
+    Field(discriminator='type')
+]
+"""
+强类型 Indicator 配置
+
+使用 Pydantic discriminated union，根据 'type' 字段自动选择正确的模型：
+- type="SMA" → SMAIndicator
+- type="ATR" → ATRIndicator
+- type="SuperTrend" → SuperTrendIndicator
+- ... etc
+
+优点：
+- 编译时类型检查
+- IDE 自动补全
+- 参数验证
+- 自动 JSON 序列化/反序列化
+
+Example:
+    >>> # 方式 1: 直接创建强类型模型
+    >>> atr = ATRIndicator(period=21)
+    >>>
+    >>> # 方式 2: 从 Dict 自动转换（API 兼容）
+    >>> indicator: IndicatorConfig = {"type": "ATR", "period": 21}
+    >>> # Pydantic 自动识别为 ATRIndicator
+"""
+
 
 class PolarsExprField:
     """自定義 Polars Expr 字段處理"""
@@ -165,8 +238,8 @@ class Indicator:
     """
 
     @staticmethod
-    def sma(period: int, column: str = "close") -> Dict[str, Any]:
-        """創建 SMA 指標配置
+    def sma(period: int, column: str = "close") -> SMAIndicator:
+        """創建 SMA 指標配置（强类型）
 
         對應 Rust: Indicator::SMA { period, column }
 
@@ -175,72 +248,42 @@ class Indicator:
             column: 計算欄位（預設 "close"）
 
         Returns:
-            SMA 指標配置 dict
+            SMAIndicator 強類型模型
 
         Example:
-            >>> Indicator.sma(period=20)
-            >>> Indicator.sma(period=20, column="high")
+            >>> atr = Indicator.sma(period=20)
+            >>> assert isinstance(atr, SMAIndicator)
+            >>> atr_high = Indicator.sma(period=20, column="high")
         """
-        return {"type": "SMA", "period": period, "column": column}
+        return SMAIndicator(period=period, column=column)
 
     @staticmethod
-    def ema(period: int, column: str = "close") -> Dict[str, Any]:
-        """創建 EMA 指標配置
+    def ema(period: int, column: str = "close") -> EMAIndicator:
+        """創建 EMA 指標配置（强类型）
 
         對應 Rust: Indicator::EMA { period, column }
-
-        Args:
-            period: 週期
-            column: 計算欄位（預設 "close"）
-
-        Returns:
-            EMA 指標配置 dict
-
-        Example:
-            >>> Indicator.ema(period=12)
-            >>> Indicator.ema(period=12, column="low")
         """
-        return {"type": "EMA", "period": period, "column": column}
+        return EMAIndicator(period=period, column=column)
 
     @staticmethod
-    def smma(period: int, column: str = "close") -> Dict[str, Any]:
-        """創建 SMMA 指標配置
+    def smma(period: int, column: str = "close") -> SMMAIndicator:
+        """創建 SMMA 指標配置（强类型）
 
         對應 Rust: Indicator::SMMA { period, column }
-
-        Args:
-            period: 週期
-            column: 計算欄位（預設 "close"）
-
-        Returns:
-            SMMA 指標配置 dict
-
-        Example:
-            >>> Indicator.smma(period=14)
         """
-        return {"type": "SMMA", "period": period, "column": column}
+        return SMMAIndicator(period=period, column=column)
 
     @staticmethod
-    def wma(period: int, column: str = "close") -> Dict[str, Any]:
-        """創建 WMA 指標配置
+    def wma(period: int, column: str = "close") -> WMAIndicator:
+        """創建 WMA 指標配置（强类型）
 
         對應 Rust: Indicator::WMA { period, column }
-
-        Args:
-            period: 週期
-            column: 計算欄位（預設 "close"）
-
-        Returns:
-            WMA 指標配置 dict
-
-        Example:
-            >>> Indicator.wma(period=10)
         """
-        return {"type": "WMA", "period": period, "column": column}
+        return WMAIndicator(period=period, column=column)
 
     @staticmethod
-    def atr(period: int) -> Dict[str, Any]:
-        """創建 ATR 指標配置
+    def atr(period: int) -> ATRIndicator:
+        """創建 ATR 指標配置（强类型）
 
         對應 Rust: Indicator::ATR { period }
 
@@ -270,15 +313,15 @@ class Indicator:
             ...     (pl.col("close") - 2 * pl.col("ATR|14")).alias("stop_loss")
             ... ])
         """
-        return {"type": "ATR", "period": period}
+        return ATRIndicator(period=period)
 
     @staticmethod
     def atr_quantile(
         atr_column: str,
         window: int,
         quantile: float,
-    ) -> Dict[str, Any]:
-        """創建 AtrQuantile 指標配置
+    ) -> ATRQuantileIndicator:
+        """創建 AtrQuantile 指標配置（强类型）
 
         對應 Rust: Indicator::AtrQuantile { atr_column, window, quantile }
 
@@ -350,12 +393,11 @@ class Indicator:
             ...     order_strategy="ImmediateEntry"
             ... )
         """
-        return {
-            "type": "AtrQuantile",
-            "atr_column": atr_column,
-            "window": window,
-            "quantile": quantile,
-        }
+        return ATRQuantileIndicator(
+            atr_column=atr_column,
+            window=window,
+            quantile=quantile,
+        )
 
     @staticmethod
     def supertrend(
@@ -365,8 +407,8 @@ class Indicator:
         low: str = "low",
         close: str = "close",
         fields: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """創建 SuperTrend 指標配置
+    ) -> SuperTrendIndicator:
+        """創建 SuperTrend 指標配置（强类型）
 
         對應 Rust: Indicator::SuperTrend { multiplier, volatility_column, high, low, close, fields }
 
@@ -408,17 +450,14 @@ class Indicator:
             ...     fields=["direction", "supertrend"]
             ... )
         """
-        config = {
-            "type": "SuperTrend",
-            "multiplier": float(multiplier),
-            "volatility_column": volatility_column,
-            "high": high,
-            "low": low,
-            "close": close,
-        }
-        if fields is not None:
-            config["fields"] = fields
-        return config
+        return SuperTrendIndicator(
+            multiplier=float(multiplier),
+            volatility_column=volatility_column,
+            high=high,
+            low=low,
+            close=close,
+            fields=fields,
+        )
 
     @staticmethod
     def market_profile(
@@ -427,8 +466,8 @@ class Indicator:
         value_area_pct: float = 0.7,
         fields: Optional[List[str]] = None,
         shape_config: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """創建 Market Profile 指標配置
+    ) -> MarketProfileIndicator:
+        """創建 Market Profile 指標配置（强类型）
 
         對應 Rust: Indicator::MarketProfile { anchor_config, tick_size, ... }
 
@@ -486,21 +525,17 @@ class Indicator:
             ...     shape_config=shape_cfg.model_dump()
             ... )
         """
-        config = {
-            "type": "MarketProfile",
-            "anchor_config": anchor_config,
-            "tick_size": tick_size,
-            "value_area_pct": value_area_pct,
-        }
-        if fields is not None:
-            config["fields"] = fields
-        if shape_config is not None:
-            config["shape_config"] = shape_config
-        return config
+        return MarketProfileIndicator(
+            anchor_config=anchor_config,
+            tick_size=tick_size,
+            value_area_pct=value_area_pct,
+            fields=fields,
+            shape_config=shape_config,
+        )
 
     @staticmethod
-    def cci(period: int = 20) -> Dict[str, Any]:
-        """創建 CCI 指標配置
+    def cci(period: int = 20) -> CCIIndicator:
+        """創建 CCI 指標配置（强类型）
 
         對應 Rust: Indicator::CCI { period }
 
@@ -535,11 +570,11 @@ class Indicator:
             >>> overbought = pl.col("1h_CCI|14") > 100
             >>> oversold = pl.col("1h_CCI|14") < -100
         """
-        return {"type": "CCI", "period": period}
+        return CCIIndicator(period=period)
 
     @staticmethod
-    def rsi(period: int = 14, column: str = "close") -> Dict[str, Any]:
-        """創建 RSI 指標配置
+    def rsi(period: int = 14, column: str = "close") -> RSIIndicator:
+        """創建 RSI 指標配置（强类型）
 
         對應 Rust: Indicator::RSI { period, column }
 
@@ -579,7 +614,7 @@ class Indicator:
             >>> entry_long = pl.col("15min_RSI|14") < 30  # RSI < 30 做多
             >>> entry_short = pl.col("15min_RSI|14") > 70  # RSI > 70 做空
         """
-        return {"type": "RSI", "period": period, "column": column}
+        return RSIIndicator(period=period, column=column)
 
     @staticmethod
     def bollinger_bands(
@@ -587,8 +622,8 @@ class Indicator:
         num_std: float = 2.0,
         column: str = "close",
         fields: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """創建 Bollinger Bands 指標配置
+    ) -> BollingerBandsIndicator:
+        """創建 Bollinger Bands 指標配置（强类型）
 
         對應 Rust: Indicator::BollingerBands { period, num_std, column, fields }
 
@@ -645,15 +680,12 @@ class Indicator:
             >>> breakout_up = pl.col("close") > upper
             >>> breakout_down = pl.col("close") < lower
         """
-        config = {
-            "type": "BollingerBands",
-            "period": period,
-            "num_std": float(num_std),
-            "column": column,
-        }
-        if fields is not None:
-            config["fields"] = fields
-        return config
+        return BollingerBandsIndicator(
+            period=period,
+            num_std=float(num_std),
+            column=column,
+            fields=fields,
+        )
 
     @staticmethod
     def macd(
@@ -662,8 +694,8 @@ class Indicator:
         signal_period: int = 9,
         column: str = "close",
         fields: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """創建 MACD 指標配置
+    ) -> MACDIndicator:
+        """創建 MACD 指標配置（强类型）
 
         對應 Rust: Indicator::MACD { fast_period, slow_period, signal_period, column, fields }
 
@@ -720,24 +752,21 @@ class Indicator:
             >>> golden_cross = macd_line > signal_line  # 金叉（做多）
             >>> death_cross = macd_line < signal_line   # 死叉（做空）
         """
-        config = {
-            "type": "MACD",
-            "fast_period": fast_period,
-            "slow_period": slow_period,
-            "signal_period": signal_period,
-            "column": column,
-        }
-        if fields is not None:
-            config["fields"] = fields
-        return config
+        return MACDIndicator(
+            fast_period=fast_period,
+            slow_period=slow_period,
+            signal_period=signal_period,
+            column=column,
+            fields=fields,
+        )
 
     @staticmethod
     def stochastic(
         k_period: int = 14,
         d_period: int = 3,
         fields: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """創建 Stochastic 指標配置
+    ) -> StochasticIndicator:
+        """創建 Stochastic 指標配置（强类型）
 
         對應 Rust: Indicator::Stochastic { k_period, d_period, fields }
 
@@ -790,18 +819,15 @@ class Indicator:
             >>> golden_cross = k_line > d_line  # 金叉（做多）
             >>> death_cross = k_line < d_line   # 死叉（做空）
         """
-        config = {
-            "type": "Stochastic",
-            "k_period": k_period,
-            "d_period": d_period,
-        }
-        if fields is not None:
-            config["fields"] = fields
-        return config
+        return StochasticIndicator(
+            k_period=k_period,
+            d_period=d_period,
+            fields=fields,
+        )
 
     @staticmethod
-    def adx(period: int = 14, fields: Optional[List[str]] = None) -> Dict[str, Any]:
-        """創建 ADX 指標配置
+    def adx(period: int = 14, fields: Optional[List[str]] = None) -> ADXIndicator:
+        """創建 ADX 指標配置（强类型）
 
         對應 Rust: Indicator::ADX { period, fields }
 
@@ -864,17 +890,14 @@ class Indicator:
             >>> uptrend = (plus_di > minus_di) & (adx_value > 25)  # 上升趨勢 + 強度足夠
             >>> downtrend = (plus_di < minus_di) & (adx_value > 25)  # 下降趨勢 + 強度足夠
         """
-        config = {
-            "type": "ADX",
-            "period": period,
-        }
-        if fields is not None:
-            config["fields"] = fields
-        return config
+        return ADXIndicator(
+            period=period,
+            fields=fields,
+        )
 
     @staticmethod
-    def raw_ohlcv(column: str) -> Dict[str, Any]:
-        """創建 RawOhlcv 指標配置
+    def raw_ohlcv(column: str) -> RawOhlcvIndicator:
+        """創建 RawOhlcv 指標配置（强类型）
 
         對應 Rust: Indicator::RawOhlcv { column }
 
@@ -913,7 +936,7 @@ class Indicator:
             >>> # 輸出列名: "TXF_M1_SHIOAJI_FUTURE_open_1D"
             >>> # 策略條件: if price > daily_open.col(): ...
         """
-        return {"type": "RawOhlcv", "column": column}
+        return RawOhlcvIndicator(column=column)
 
 
 # ============================================================================
@@ -1075,17 +1098,47 @@ def create_profile_shape_config(
 
 
 class IndicatorSpec(BaseModel):
-    """指標規範"""
+    """指標規範（强类型版本）"""
 
     instrument_id: Optional[str] = Field(
         None, description="交易標的 ID（可選，用於多商品場景）"
     )
-    freq: Union[Freq, str] = Field(..., description="頻率 (使用 Freq enum 或自訂字串)")
+    freq: Freq = Field(..., description="頻率 (Freq enum)")
     shift: int = Field(1, description="位移（預設 1）")
-    indicator: Dict[str, Any] = Field(
-        ..., description="指標配置 (使用 indicator 工廠函數建立)"
+    indicator: IndicatorConfig = Field(
+        ..., description="指標配置（强类型 Pydantic 模型）"
     )
 
+    @field_validator("freq", mode="before")
+    @classmethod
+    def convert_freq(cls, v: Any) -> Freq:
+        """自動轉換字串為 Freq enum（保持 API 兼容性）"""
+        if isinstance(v, str):
+            try:
+                return Freq(v)
+            except ValueError:
+                valid_values = [e.value for e in Freq]
+                raise ValueError(
+                    f"Invalid freq: '{v}'. "
+                    f"Valid values: {', '.join(valid_values)}"
+                )
+        return v
+
+    @field_validator("indicator", mode="before")
+    @classmethod
+    def convert_indicator(cls, v: Any) -> IndicatorConfig:
+        """自動轉換 Dict 為強類型 Indicator 模型（保持 API 兼容性）
+
+        接受：
+        - Dict[str, Any]: 從 API 返回或舊代碼（自動轉換）
+        - IndicatorConfig: 新代碼使用強類型模型
+
+        Pydantic 會根據 'type' 字段自動選擇正確的模型。
+        """
+        # Dict 會被 Pydantic 自動轉換為對應的 Indicator 模型
+        # 強類型模型直接返回
+        return v
+
     def short_name(self) -> str:
         """生成指標簡短名稱（與 Rust 的 short_name 一致）
 
@@ -1101,53 +1154,39 @@ class IndicatorSpec(BaseModel):
         Raises:
             ValueError: 未知的指標類型
         """
-        indicator_type = self.indicator.get("type")
+        indicator_type = self.indicator.type
 
         if indicator_type == "SMA":
-            period = self.indicator.get("period")
-            column = self.indicator.get("column", "close")
-            return f"SMA|{period}.{column}"
+            return f"SMA|{self.indicator.period}.{self.indicator.column}"
 
         elif indicator_type == "EMA":
-            period = self.indicator.get("period")
-            column = self.indicator.get("column", "close")
-            return f"EMA|{period}.{column}"
+            return f"EMA|{self.indicator.period}.{self.indicator.column}"
 
         elif indicator_type == "SMMA":
-            period = self.indicator.get("period")
-            column = self.indicator.get("column", "close")
-            return f"SMMA|{period}.{column}"
+            return f"SMMA|{self.indicator.period}.{self.indicator.column}"
 
         elif indicator_type == "WMA":
-            period = self.indicator.get("period")
-            column = self.indicator.get("column", "close")
-            return f"WMA|{period}.{column}"
+            return f"WMA|{self.indicator.period}.{self.indicator.column}"
 
         elif indicator_type == "ATR":
-            period = self.indicator.get("period")
             # ATR 始終返回單一數值欄位，無 quantile
-            return f"ATR|{period}"
+            return f"ATR|{self.indicator.period}"
 
         elif indicator_type == "AtrQuantile":
-            atr_column = self.indicator.get("atr_column")
-            window = self.indicator.get("window")
-            quantile = self.indicator.get("quantile")
             # 將 quantile 轉為百分比（例如 0.5 -> 50）
-            quantile_pct = int(quantile * 100)
+            quantile_pct = int(self.indicator.quantile * 100)
             # 格式：ATRQ|{atr_column}_Q{quantile%}_{window}
-            return f"ATRQ|{atr_column}_Q{quantile_pct}_{window}"
+            return f"ATRQ|{self.indicator.atr_column}_Q{quantile_pct}_{self.indicator.window}"
 
         elif indicator_type == "SuperTrend":
-            multiplier = self.indicator.get("multiplier")
-            volatility_column = self.indicator.get("volatility_column")
-            return f"ST|{multiplier}x_{volatility_column}"
+            return f"ST|{self.indicator.multiplier}x_{self.indicator.volatility_column}"
 
         elif indicator_type == "MarketProfile":
             # 提取 anchor_config 資訊
-            anchor_config = self.indicator.get("anchor_config", {})
+            anchor_config = self.indicator.anchor_config
             end_rule = anchor_config.get("end_rule", {})
             lookback_days = anchor_config.get("lookback_days", 1)
-            tick_size = self.indicator.get("tick_size")
+            tick_size = self.indicator.tick_size
 
             # 格式化時間字串（支持新舊兩種格式）
             rule_type = end_rule.get("type")
@@ -1212,37 +1251,26 @@ class IndicatorSpec(BaseModel):
             return f"MP|{time_str}_{lookback_days}_{tick_size}"
 
         elif indicator_type == "CCI":
-            period = self.indicator.get("period")
-            return f"CCI|{period}"
+            return f"CCI|{self.indicator.period}"
 
         elif indicator_type == "RSI":
-            period = self.indicator.get("period")
-            return f"RSI|{period}"
+            return f"RSI|{self.indicator.period}"
 
         elif indicator_type == "BollingerBands":
-            period = self.indicator.get("period")
-            num_std = self.indicator.get("num_std")
-            return f"BB|{period}_{num_std}"
+            return f"BB|{self.indicator.period}_{self.indicator.num_std}"
 
         elif indicator_type == "MACD":
-            fast_period = self.indicator.get("fast_period")
-            slow_period = self.indicator.get("slow_period")
-            signal_period = self.indicator.get("signal_period")
-            return f"MACD|{fast_period}_{slow_period}_{signal_period}"
+            return f"MACD|{self.indicator.fast_period}_{self.indicator.slow_period}_{self.indicator.signal_period}"
 
         elif indicator_type == "Stochastic":
-            k_period = self.indicator.get("k_period")
-            d_period = self.indicator.get("d_period")
-            return f"STOCH|{k_period}_{d_period}"
+            return f"STOCH|{self.indicator.k_period}_{self.indicator.d_period}"
 
         elif indicator_type == "ADX":
-            period = self.indicator.get("period")
-            return f"ADX|{period}"
+            return f"ADX|{self.indicator.period}"
 
         elif indicator_type == "RawOhlcv":
             # RawOhlcv 只返回 column 名稱
-            column = self.indicator.get("column")
-            return column
+            return self.indicator.column
 
         else:
             raise ValueError(f"未知的指標類型: {indicator_type}")
@@ -1312,8 +1340,8 @@ class Trigger(BaseModel):
     """
 
     name: str = Field(..., description="觸發器名稱")
-    order_strategy: Union[OrderStrategy, str] = Field(
-        ..., description="訂單策略（OrderStrategy enum 或字串）"
+    order_strategy: OrderStrategy = Field(
+        ..., description="訂單策略（OrderStrategy enum）"
     )
     priority: int = Field(..., description="優先級")
     note: Optional[str] = Field(None, description="備註")
@@ -1322,6 +1350,21 @@ class Trigger(BaseModel):
     conditions: List[pl.Expr] = Field(..., description="條件列表（Polars Expr）")
     price_expr: pl.Expr = Field(..., description="價格表達式（Polars Expr）")
 
+    @field_validator("order_strategy", mode="before")
+    @classmethod
+    def convert_order_strategy(cls, v: Any) -> OrderStrategy:
+        """自動轉換字串為 OrderStrategy enum（保持 API 兼容性）"""
+        if isinstance(v, str):
+            try:
+                return OrderStrategy(v)
+            except ValueError:
+                valid_values = [e.value for e in OrderStrategy]
+                raise ValueError(
+                    f"Invalid order_strategy: '{v}'. "
+                    f"Valid values: {', '.join(valid_values)}"
+                )
+        return v
+
     @field_validator("conditions", mode="before")
     @classmethod
     def validate_conditions(cls, v: Any) -> List[pl.Expr]:
@@ -1350,25 +1393,53 @@ class Trigger(BaseModel):
         """序列化 price_expr 為 dict（與服務器格式一致）"""
         return PolarsExprField.serialize(price_expr)
 
-    class Config:
-        # 允許 pl.Expr 這種自定義類型
-        arbitrary_types_allowed = True
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True  # 允許 pl.Expr 這種自定義類型
+    )
 
 
 class Blueprint(BaseModel):
     """策略藍圖"""
 
     name: str = Field(..., description="藍圖名稱")
-    direction: Union[TradeDirection, str] = Field(..., description="方向")
-    trend_type: Union[TrendType, str] = Field(
-        ..., description="趨勢類型"
-    )
+    direction: TradeDirection = Field(..., description="方向")
+    trend_type: TrendType = Field(..., description="趨勢類型")
     entry_first: bool = Field(..., description="是否優先進場")
     note: str = Field(..., description="備註")
 
     entry_triggers: List[Trigger] = Field(..., description="進場觸發器列表")
     exit_triggers: List[Trigger] = Field(..., description="出場觸發器列表")
 
+    @field_validator("direction", mode="before")
+    @classmethod
+    def convert_direction(cls, v: Any) -> TradeDirection:
+        """自動轉換字串為 TradeDirection enum（保持 API 兼容性）"""
+        if isinstance(v, str):
+            try:
+                return TradeDirection(v)
+            except ValueError:
+                valid_values = [e.value for e in TradeDirection]
+                raise ValueError(
+                    f"Invalid direction: '{v}'. "
+                    f"Valid values: {', '.join(valid_values)}"
+                )
+        return v
+
+    @field_validator("trend_type", mode="before")
+    @classmethod
+    def convert_trend_type(cls, v: Any) -> TrendType:
+        """自動轉換字串為 TrendType enum（保持 API 兼容性）"""
+        if isinstance(v, str):
+            try:
+                return TrendType(v)
+            except ValueError:
+                valid_values = [e.value for e in TrendType]
+                raise ValueError(
+                    f"Invalid trend_type: '{v}'. "
+                    f"Valid values: {', '.join(valid_values)}"
+                )
+        return v
+
 
 class StrategyConfig(BaseModel):
     """完整策略配置"""
@@ -1536,7 +1607,7 @@ def create_trigger(
     name: str,
     conditions: List[pl.Expr],
     price_expr: pl.Expr,
-    order_strategy: Union[OrderStrategy, str] = OrderStrategy.IMMEDIATE_ENTRY,
+    order_strategy: OrderStrategy = OrderStrategy.IMMEDIATE_ENTRY,
     priority: int = 1,
     note: Optional[str] = None,
 ) -> Trigger:
@@ -1588,10 +1659,10 @@ def create_trigger(
 
 def create_blueprint(
     name: str,
-    direction: Union[TradeDirection, str],
+    direction: TradeDirection,
     entry_triggers: List[Trigger],
     exit_triggers: List[Trigger],
-    trend_type: Union[TrendType, str] = "Trend",
+    trend_type: TrendType = TrendType.TREND,
     entry_first: bool = True,
     note: str = "",
 ) -> Blueprint:

{tradepose_client-0.1.1.dist-info → tradepose_client-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradepose-client
-Version: 0.1.1
+Version: 0.1.2
 Summary: Python client for Tradepose quantitative trading API
 Author: Tradepose Team
 License: MIT

{tradepose_client-0.1.1.dist-info → tradepose_client-0.1.2.dist-info}/RECORD

@@ -2,7 +2,8 @@ tradepose_client/__init__.py,sha256=51JWgNgRTfKzm52NVCb9VT7rQcGd20f2DoLuF6RzReA,
 tradepose_client/analysis.py,sha256=RNpk3i9_1uUXM_-K-xYbG3Ckg-MoOwQ6gSExua2N4N8,7563
 tradepose_client/client.py,sha256=1qD4pnIjCXKgE3VXeB6EgkNuCXvDJEbmPldIjIzAVmk,1798
 tradepose_client/enums.py,sha256=Dhvwj_diX8r_ByerwZpDSqAsquRI5FMOctm7RxQ1CDA,4887
-tradepose_client/models.py,sha256=Fp2Brop-5R5Oo-HmWk_JXvB6oS21wH5bvEM0Akj4FWM,64196
+tradepose_client/indicator_models.py,sha256=PKJAPYgRhlWGUgK346Mlyv7ZKN_Wi_8Hc5hhPKl3QUA,9727
+tradepose_client/models.py,sha256=47D7kkmpBjxvLwLrk2a_Crvuh2BKLx0z10Q46p7FiLs,66669
 tradepose_client/schema.py,sha256=lPcJU-1xKcGFRoeuvqovrg4LUiOLO5bRZiMVyDkKHUQ,6357
 tradepose_client/viz.py,sha256=qu9zyAXa_Q7D4rxdgN55JyYiY24ZD3r0jf2SWtqGZYg,22989
 tradepose_client/api/__init__.py,sha256=ezeMxOBrUDRhlqZNO-X0X9KbNJGccDseKQ95zAvyhFY,218
@@ -14,8 +15,8 @@ tradepose_client/builder/__init__.py,sha256=PIrsZcxP5cEa2_K1Zzpcf2FVc62iavKCNT6D
 tradepose_client/builder/blueprint_builder.py,sha256=7ssa3J3AMezZlWEyGbkaSfwhIyGPIzgl1bOKY7owZg4,9347
 tradepose_client/builder/indicator_wrapper.py,sha256=zfVZE1fX-2emUg8bSjlukP9rF47j8s7h2efo_fSVWWM,3581
 tradepose_client/builder/strategy_builder.py,sha256=gEeNytZepy3t4jmPKFcZZv3lGSBC0SMQ1QCTcv-qOO0,10433
-tradepose_client/builder/trading_context.py,sha256=Z8ueMqAyUQmiUQsAQ8qrAipWkOMFdnEkpeazhFpnf1A,5318
-tradepose_client-0.1.1.dist-info/METADATA,sha256=ar2oTs6oLE7SWXCMBSP8cGldrjfu3c5Ve6MBgn38-YI,14056
-tradepose_client-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-tradepose_client-0.1.1.dist-info/licenses/LICENSE,sha256=6qYWNkUbxmJl1iN7c4DoM1_8ASsZyXemFO1D0wXtiHk,1071
-tradepose_client-0.1.1.dist-info/RECORD,,
+tradepose_client/builder/trading_context.py,sha256=6KQEFlMxh8IVT25XoEc-uU65zHpwjCRmkU1NHiy9cck,4340
+tradepose_client-0.1.2.dist-info/METADATA,sha256=Y8jH2qNVBYs1brHfwbExMQQOd-1U92MeTT8IVyqrd4g,14056
+tradepose_client-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+tradepose_client-0.1.2.dist-info/licenses/LICENSE,sha256=6qYWNkUbxmJl1iN7c4DoM1_8ASsZyXemFO1D0wXtiHk,1071
+tradepose_client-0.1.2.dist-info/RECORD,,