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

tradepose_client/builder/strategy_builder.py

@@ -0,0 +1,312 @@
+"""
+策略构建器（主入口类）
+
+管理整体策略构建流程：
+1. 自动继承 base_instrument 和 base_freq
+2. 添加指标（返回 IndicatorSpecWrapper）
+3. 设置 base blueprint
+4. 添加 advanced blueprints（链式）
+5. 构建最终 StrategyConfig
+
+Usage:
+    from tradepose_client.builder import StrategyBuilder, BlueprintBuilder
+
+    # 1. 创建 builder
+    builder = StrategyBuilder(
+        name="KOG_US100_15T_ST_21_3",
+        base_instrument="US100.cash_M15_FTMO_FUTURE",
+        base_freq="15min"
+    )
+
+    # 2. 添加指标（自动继承 instrument_id）
+    atr = builder.add_indicator("atr", period=21, freq="1D", shift=1)
+    st = builder.add_indicator(
+        "supertrend",
+        multiplier=3.0,
+        volatility_column=atr.display_name,
+        freq="1D",
+        shift=1
+    )
+
+    # 3. 创建并设置 base blueprint
+    base_bp = BlueprintBuilder("base", "Long", "Trend")\
+        .add_entry_trigger(...)\
+        .add_exit_trigger(...)\
+        .build()
+
+    builder.set_base_blueprint(base_bp)
+
+    # 4. 添加 advanced blueprints
+    adv_bp = BlueprintBuilder("risk_mgmt", "Long", "Trend")\
+        .add_exit_trigger(...)\
+        .build()
+
+    builder.add_advanced_blueprint(adv_bp)
+
+    # 5. 构建最终策略
+    strategy = builder.build(
+        volatility_indicator=atr,
+        note="US100 顺势策略"
+    )
+
+    # 6. 保存或注册
+    strategy.save("strategy.json")
+"""
+
+from typing import List, Optional, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tradepose_client.models import StrategyConfig, Blueprint, Freq
+    from tradepose_client.enums import IndicatorType
+
+from .indicator_wrapper import IndicatorSpecWrapper
+
+
+class StrategyBuilder:
+    """
+    策略构建器（主入口类）
+
+    管理整体策略构建流程，自动继承 base_instrument 和 base_freq。
+
+    Attributes:
+        name (str): 策略名称
+        base_instrument (str): 基准商品
+        base_freq (Freq): 基准频率
+
+    Methods:
+        add_indicator(indicator_type, **kwargs) -> IndicatorSpecWrapper:
+            添加指标（自动继承 instrument_id）
+        set_base_blueprint(blueprint) -> StrategyBuilder:
+            设置 Base Blueprint
+        add_advanced_blueprint(blueprint) -> StrategyBuilder:
+            添加 Advanced Blueprint（链式）
+        build(volatility_indicator, note) -> StrategyConfig:
+            构建最终 StrategyConfig
+    """
+
+    def __init__(
+        self,
+        name: str,
+        base_instrument: str,
+        base_freq: str,
+    ):
+        """
+        初始化策略构建器
+
+        Args:
+            name: 策略名称（唯一标识）
+            base_instrument: 基准商品 ID（所有指标自动继承此值）
+            base_freq: 基准频率（支持字符串，如 "15min", "1D"）
+
+        Examples:
+            >>> builder = StrategyBuilder(
+            ...     name="KOG_US100_15T_ST_21_3",
+            ...     base_instrument="US100.cash_M15_FTMO_FUTURE",
+            ...     base_freq="15min"
+            ... )
+        """
+        self.name = name
+        self.base_instrument = base_instrument
+        self.base_freq = base_freq  # 字符串形式，稍后转换
+
+        self._indicators: List[IndicatorSpecWrapper] = []
+        self._base_blueprint: Optional["Blueprint"] = None
+        self._advanced_blueprints: List["Blueprint"] = []
+
+    def add_indicator(
+        self,
+        indicator_type: Union["IndicatorType", str],
+        freq: Union["Freq", str],
+        shift: int = 1,
+        instrument_id: Optional[str] = None,
+        **kwargs,
+    ) -> IndicatorSpecWrapper:
+        """
+        添加指标（支持可选 instrument_id 覆盖）
+
+        Args:
+            indicator_type: 指标类型（支持 IndicatorType enum 或字符串）
+                - IndicatorType.ATR 或 "atr"
+                - IndicatorType.SMA 或 "sma"
+                - IndicatorType.SUPERTREND 或 "supertrend"
+            freq: 指标频率（支持 Freq enum 或字符串）
+                - Freq.DAY_1 或 "1D"
+                - Freq.HOUR_1 或 "1h"
+                - Freq.MIN_15 或 "15min"
+            shift: 位移（默认 1，依赖指标通常使用 0）
+            instrument_id: 商品 ID（默认 None，使用 base_instrument）
+                - None: 使用 self.base_instrument（常见用法）
+                - "OTHER_INSTRUMENT": 使用其他商品（跨商品引用）
+            **kwargs: 指标参数（传递给 Indicator 工厂方法）
+
+        Returns:
+            IndicatorSpecWrapper: 指标包装器，提供 .col() 和 .display_name
+
+        Examples:
+            >>> # 使用 enum（推荐，类型安全）
+            >>> atr = builder.add_indicator(
+            ...     IndicatorType.ATR,
+            ...     period=21,
+            ...     freq=Freq.DAY_1,
+            ...     shift=1
+            ... )
+            >>>
+            >>> # 使用字符串（向后兼容）
+            >>> atr = builder.add_indicator("atr", period=21, freq="1D", shift=1)
+            >>>
+            >>> # 跨商品引用（使用其他商品的指标）
+            >>> vix_atr = builder.add_indicator(
+            ...     IndicatorType.ATR,
+            ...     period=21,
+            ...     freq=Freq.DAY_1,
+            ...     shift=1,
+            ...     instrument_id="VIX.cash"  # 引用 VIX 的 ATR
+            ... )
+            >>>
+            >>> # 依赖指标（SuperTrend 引用 ATR）
+            >>> st = builder.add_indicator(
+            ...     IndicatorType.SUPERTREND,
+            ...     multiplier=3.0,
+            ...     volatility_column=atr.display_name,  # 引用依赖
+            ...     freq=Freq.DAY_1,
+            ...     shift=1
+            ... )
+        """
+        from tradepose_client.models import Indicator, create_indicator_spec, Freq
+        from tradepose_client.enums import IndicatorType
+
+        # 转换 indicator_type 为字符串
+        if isinstance(indicator_type, IndicatorType):
+            indicator_type_str = indicator_type.value
+        else:
+            indicator_type_str = indicator_type
+
+        # 动态调用 Indicator 工厂方法
+        if not hasattr(Indicator, indicator_type_str):
+            raise ValueError(
+                f"Unknown indicator type: '{indicator_type_str}'. "
+                f"Available: {', '.join([e.value for e in IndicatorType])}"
+            )
+
+        indicator_factory = getattr(Indicator, indicator_type_str)
+        indicator_config = indicator_factory(**kwargs)
+
+        # 转换 freq 字符串/enum 为 Freq enum
+        freq_enum = Freq(freq) if isinstance(freq, str) else freq
+
+        # 使用 instrument_id（如果提供），否则使用 base_instrument
+        final_instrument_id = instrument_id if instrument_id is not None else self.base_instrument
+
+        # 创建 IndicatorSpec
+        spec = create_indicator_spec(
+            freq=freq_enum,
+            indicator=indicator_config,
+            instrument_id=final_instrument_id,
+            shift=shift,
+        )
+
+        wrapper = IndicatorSpecWrapper(spec)
+        self._indicators.append(wrapper)
+        return wrapper
+
+    def set_base_blueprint(self, blueprint: "Blueprint") -> "StrategyBuilder":
+        """
+        设置 Base Blueprint
+
+        Args:
+            blueprint: Base Blueprint 对象（通常由 BlueprintBuilder 创建）
+
+        Returns:
+            StrategyBuilder: 返回自身，支持链式调用
+
+        Examples:
+            >>> base_bp = BlueprintBuilder("base", "Long", "Trend")\
+            ...     .add_entry_trigger(...)\
+            ...     .add_exit_trigger(...)\
+            ...     .build()
+            >>>
+            >>> builder.set_base_blueprint(base_bp)
+        """
+        self._base_blueprint = blueprint
+        return self
+
+    def add_advanced_blueprint(self, blueprint: "Blueprint") -> "StrategyBuilder":
+        """
+        添加 Advanced Blueprint（链式调用）
+
+        Args:
+            blueprint: Advanced Blueprint 对象（通常由 BlueprintBuilder 创建）
+
+        Returns:
+            StrategyBuilder: 返回自身，支持链式调用
+
+        Examples:
+            >>> adv_bp = BlueprintBuilder("risk_mgmt", "Long", "Trend")\
+            ...     .add_exit_trigger(...)\
+            ...     .build()
+            >>>
+            >>> builder.add_advanced_blueprint(adv_bp)
+        """
+        self._advanced_blueprints.append(blueprint)
+        return self
+
+    def build(
+        self,
+        volatility_indicator: IndicatorSpecWrapper,
+        note: str = "",
+    ) -> "StrategyConfig":
+        """
+        构建最终 StrategyConfig
+
+        Args:
+            volatility_indicator: 波动率指标（通常是 ATR）
+            note: 策略说明
+
+        Returns:
+            StrategyConfig: 完整的策略配置对象
+
+        Raises:
+            ValueError: 如果未设置 base_blueprint
+
+        Examples:
+            >>> strategy = builder.build(
+            ...     volatility_indicator=atr,
+            ...     note="US100 顺势策略 - SuperTrend(21,3)"
+            ... )
+            >>>
+            >>> # 保存为 JSON
+            >>> strategy.save("strategy.json")
+            >>>
+            >>> # 或注册到 API
+            >>> client.register_strategy(strategy.to_json())
+        """
+        from tradepose_client.models import StrategyConfig, Freq
+
+        if not self._base_blueprint:
+            raise ValueError(
+                "Base blueprint is required. Use .set_base_blueprint() first."
+            )
+
+        # 转换 base_freq 为 Freq enum
+        base_freq_enum = Freq(self.base_freq) if isinstance(self.base_freq, str) else self.base_freq
+
+        return StrategyConfig(
+            name=self.name,
+            base_instrument=self.base_instrument,
+            base_freq=base_freq_enum,
+            volatility_indicator=volatility_indicator.spec,
+            indicators=[ind.spec for ind in self._indicators],
+            base_blueprint=self._base_blueprint,
+            advanced_blueprints=self._advanced_blueprints,
+            note=note,
+        )
+
+    def __repr__(self) -> str:
+        """字符串表示"""
+        return (
+            f"StrategyBuilder(name='{self.name}', "
+            f"base_instrument='{self.base_instrument}', "
+            f"base_freq='{self.base_freq}', "
+            f"indicators={len(self._indicators)}, "
+            f"advanced_blueprints={len(self._advanced_blueprints)})"
+        )

tradepose_client/builder/trading_context.py

@@ -0,0 +1,140 @@
+"""
+Trading Context 固定字段访问器
+
+基于 schema.py 中定义的 struct 字段，提供简洁的属性访问方式，
+避免繁琐的 `.struct.field()` 调用。
+
+Usage:
+    from tradepose_client.builder import TradingContext
+    import polars as pl
+
+    # 简洁访问（返回 pl.Expr）
+    entry_price = TradingContext.base.entry_price
+    highest = TradingContext.advanced_entry.highest_since_entry
+    bars = TradingContext.advanced_exit.bars_since_entry
+
+    # 用于策略条件表达式
+    condition = TradingContext.base.bars_in_position > 50
+    stop_loss_price = TradingContext.advanced_entry.entry_price - pl.col("atr") * 2
+"""
+
+import polars as pl
+
+
+class TradingContextProxy:
+    """
+    Trading Context 字段访问代理
+
+    为 base_trading_context, advanced_entry_trading_context,
+    advanced_exit_trading_context 提供统一的属性访问接口。
+
+    Args:
+        context_name: 上下文字段名称（如 "base_trading_context"）
+        context_type: 上下文类型（"base" 或 "advanced"）
+    """
+
+    def __init__(
+        self,
+        context_name: str,
+    ):
+        self._context_name = context_name
+
+    @property
+    def entry_price(self) -> pl.Expr:
+        """
+        进场价格
+
+        Returns:
+            pl.Expr: Polars 表达式，可直接用于条件或价格计算
+        """
+        return pl.col(self._context_name).struct.field("position_entry_price")
+
+    @property
+    def bars_in_position(self) -> pl.Expr:
+        """
+        持仓 K 线数（仅适用于 base_trading_context）
+
+        Returns:
+            pl.Expr: Polars 表达式
+
+        Note:
+            - base_trading_context 使用 "bars_in_position"
+            - advanced 使用 "bars_since_advanced_entry"（请用 .bars_since_entry）
+        """
+        return pl.col(self._context_name).struct.field("bars_in_position")
+
+    @property
+    def highest_since_entry(self) -> pl.Expr:
+        """
+        进场以来最高价
+
+        Returns:
+            pl.Expr: Polars 表达式，可用于 trailing stop 计算
+        """
+        return pl.col(self._context_name).struct.field("highest_since_entry")
+
+    @property
+    def lowest_since_entry(self) -> pl.Expr:
+        """
+        进场以来最低价
+
+        Returns:
+            pl.Expr: Polars 表达式，可用于 short position trailing stop 计算
+        """
+        return pl.col(self._context_name).struct.field("lowest_since_entry")
+
+
+class TradingContext:
+    """
+    Trading Context 统一访问器
+
+    提供三种 trading context 的属性访问：
+    - base: base_trading_context
+    - advanced_entry: advanced_entry_trading_context
+    - advanced_exit: advanced_exit_trading_context
+
+    Usage:
+        # Base context（Base Blueprint 生成）
+        TradingContext.base.entry_price
+        TradingContext.base.bars_in_position
+        TradingContext.base.highest_since_entry
+        TradingContext.base.lowest_since_entry
+
+        # Advanced Entry context（Advanced Entry Triggers 使用）
+        TradingContext.advanced_entry.entry_price
+        TradingContext.advanced_entry.bars_since_entry
+        TradingContext.advanced_entry.highest_since_entry
+        TradingContext.advanced_entry.lowest_since_entry
+
+        # Advanced Exit context（Advanced Exit Triggers 使用）
+        TradingContext.advanced_exit.entry_price
+        TradingContext.advanced_exit.bars_since_entry
+        TradingContext.advanced_exit.highest_since_entry
+        TradingContext.advanced_exit.lowest_since_entry
+
+    Examples:
+        # Stop Loss（Long）
+        stop_loss_price = (
+            TradingContext.advanced_entry.entry_price -
+            pl.col("atr") * 2
+        )
+
+        # Trailing Stop（Long）
+        trailing_stop_price = (
+            TradingContext.advanced_entry.highest_since_entry -
+            pl.col("atr") * 2
+        )
+
+        # 持倉時間過濾
+        timeout_condition = TradingContext.advanced_entry.bars_since_entry > 100
+    """
+
+    base = TradingContextProxy("base_trading_context")
+    advanced_entry = TradingContextProxy("advanced_entry_trading_context")
+    advanced_exit = TradingContextProxy("advanced_exit_trading_context")
+
+
+# 向后兼容的别名
+BaseContext = TradingContext.base
+AdvancedEntryContext = TradingContext.advanced_entry
+AdvancedExitContext = TradingContext.advanced_exit

tradepose_client/enums.py

@@ -0,0 +1,176 @@
+"""
+Enumerations for Tradepose strategy configuration
+
+All enums are aligned with Rust backend types for JSON serialization.
+"""
+
+from enum import Enum
+
+
+class Freq(str, Enum):
+    """
+    Time frequency enum (aligned with Rust Freq enum)
+
+    Values:
+        MIN_1: 1 minute
+        MIN_5: 5 minutes
+        MIN_15: 15 minutes
+        MIN_30: 30 minutes
+        HOUR_1: 1 hour
+        HOUR_4: 4 hours
+        DAY_1: 1 day
+        WEEK_1: 1 week
+        MONTH_1: 1 month
+    """
+
+    MIN_1 = "1min"
+    MIN_5 = "5min"
+    MIN_15 = "15min"
+    MIN_30 = "30min"
+    HOUR_1 = "1h"
+    HOUR_4 = "4h"
+    DAY_1 = "1D"
+    WEEK_1 = "1W"
+    MONTH_1 = "1M"
+
+
+class OrderStrategy(str, Enum):
+    """
+    Order strategy enum (aligned with Rust OrderStrategy enum)
+
+    Used to specify the execution strategy for entry/exit triggers.
+
+    Rust mapping:
+    - Rust: OrderStrategy::ImmediateEntry      → Python: OrderStrategy.IMMEDIATE_ENTRY      (u32: 0)
+    - Rust: OrderStrategy::FavorableDelayEntry → Python: OrderStrategy.FAVORABLE_DELAY_ENTRY (u32: 1)
+    - Rust: OrderStrategy::AdverseDelayEntry   → Python: OrderStrategy.ADVERSE_DELAY_ENTRY   (u32: 2)
+    - Rust: OrderStrategy::ImmediateExit       → Python: OrderStrategy.IMMEDIATE_EXIT        (u32: 3)
+    - Rust: OrderStrategy::StopLoss            → Python: OrderStrategy.STOP_LOSS             (u32: 4)
+    - Rust: OrderStrategy::TakeProfit          → Python: OrderStrategy.TAKE_PROFIT           (u32: 5)
+    - Rust: OrderStrategy::TrailingStop        → Python: OrderStrategy.TRAILING_STOP         (u32: 6)
+    - Rust: OrderStrategy::Breakeven           → Python: OrderStrategy.BREAKEVEN             (u32: 7)
+    - Rust: OrderStrategy::TimeoutExit         → Python: OrderStrategy.TIMEOUT_EXIT          (u32: 8)
+
+    Entry Strategies:
+        IMMEDIATE_ENTRY: Immediate entry on signal (required for Base Blueprint)
+        FAVORABLE_DELAY_ENTRY: Wait for favorable price (pullback/retracement)
+        ADVERSE_DELAY_ENTRY: Wait for breakout/aggressive entry
+
+    Exit Strategies:
+        IMMEDIATE_EXIT: Immediate exit on signal (required for Base Blueprint)
+        STOP_LOSS: Fixed stop loss
+        TAKE_PROFIT: Fixed take profit
+        TRAILING_STOP: Dynamic trailing stop
+        BREAKEVEN: Move stop to breakeven after profit
+        TIMEOUT_EXIT: Exit after time limit
+    """
+
+    IMMEDIATE_ENTRY = "ImmediateEntry"
+    FAVORABLE_DELAY_ENTRY = "FavorableDelayEntry"
+    ADVERSE_DELAY_ENTRY = "AdverseDelayEntry"
+    IMMEDIATE_EXIT = "ImmediateExit"
+    STOP_LOSS = "StopLoss"
+    TAKE_PROFIT = "TakeProfit"
+    TRAILING_STOP = "TrailingStop"
+    BREAKEVEN = "Breakeven"
+    TIMEOUT_EXIT = "TimeoutExit"
+
+
+class Weekday(str, Enum):
+    """
+    Weekday enum (aligned with Rust Weekday enum)
+
+    Used for Market Profile WeeklyTime configuration.
+
+    Mapping:
+        MON (Monday) = 0
+        TUE (Tuesday) = 1
+        WED (Wednesday) = 2
+        THU (Thursday) = 3
+        FRI (Friday) = 4
+        SAT (Saturday) = 5
+        SUN (Sunday) = 6
+    """
+
+    MON = "Mon"
+    TUE = "Tue"
+    WED = "Wed"
+    THU = "Thu"
+    FRI = "Fri"
+    SAT = "Sat"
+    SUN = "Sun"
+
+
+class IndicatorType(str, Enum):
+    """
+    Indicator type enum
+
+    Maps to Indicator factory methods in models.py.
+
+    Values:
+        SMA: Simple Moving Average
+        EMA: Exponential Moving Average
+        SMMA: Smoothed Moving Average
+        WMA: Weighted Moving Average
+        ATR: Average True Range
+        ATR_QUANTILE: ATR Rolling Quantile
+        SUPERTREND: SuperTrend
+        MARKET_PROFILE: Market Profile
+        CCI: Commodity Channel Index
+        RSI: Relative Strength Index
+        BOLLINGER_BANDS: Bollinger Bands
+        MACD: Moving Average Convergence Divergence
+        STOCHASTIC: Stochastic Oscillator
+        ADX: Average Directional Index
+        RAW_OHLCV: Raw OHLCV column
+    """
+
+    SMA = "sma"
+    EMA = "ema"
+    SMMA = "smma"
+    WMA = "wma"
+    ATR = "atr"
+    ATR_QUANTILE = "atr_quantile"
+    SUPERTREND = "supertrend"
+    MARKET_PROFILE = "market_profile"
+    CCI = "cci"
+    RSI = "rsi"
+    BOLLINGER_BANDS = "bollinger_bands"
+    MACD = "macd"
+    STOCHASTIC = "stochastic"
+    ADX = "adx"
+    RAW_OHLCV = "raw_ohlcv"
+
+
+class TradeDirection(str, Enum):
+    """
+    Trade direction enum
+
+    Used to specify the trading direction in Blueprint.
+
+    Values:
+        LONG: Long trades only
+        SHORT: Short trades only
+        BOTH: Both long and short trades (currently not fully supported)
+    """
+
+    LONG = "Long"
+    SHORT = "Short"
+    BOTH = "Both"
+
+
+class TrendType(str, Enum):
+    """
+    Trend type enum
+
+    Used to categorize strategy trading style.
+
+    Values:
+        TREND: Trend-following strategies
+        RANGE: Range-bound/mean-reversion strategies
+        REVERSAL: Reversal/counter-trend strategies
+    """
+
+    TREND = "Trend"
+    RANGE = "Range"
+    REVERSAL = "Reversal"