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

tradepose_client/__init__.py

@@ -19,14 +19,25 @@ from .models import (
     Blueprint,
     Trigger,
     IndicatorSpec,
-    Freq,
-    OrderStrategy,
     Indicator,
     create_trigger,
     create_blueprint,
     create_indicator_spec,
     parse_strategy,
 )
+from .enums import (
+    Freq,
+    OrderStrategy,
+    TradeDirection,
+    TrendType,
+    Weekday,
+    IndicatorType,
+)
+from .builder import (
+    TradingContext,
+    BlueprintBuilder,
+    StrategyBuilder,
+)
 from .schema import (
     enhanced_ohlcv_schema,
     trades_schema,
@@ -68,13 +79,22 @@ __all__ = [
     "Blueprint",
     "Trigger",
     "IndicatorSpec",
-    "Freq",
-    "OrderStrategy",
     "Indicator",
     "create_trigger",
     "create_blueprint",
     "create_indicator_spec",
     "parse_strategy",
+    # Enums
+    "Freq",
+    "OrderStrategy",
+    "TradeDirection",
+    "TrendType",
+    "Weekday",
+    "IndicatorType",
+    # Builder API (New)
+    "TradingContext",
+    "BlueprintBuilder",
+    "StrategyBuilder",
     # Schema
     "enhanced_ohlcv_schema",
     "trades_schema",

tradepose_client/builder/__init__.py

@@ -0,0 +1,22 @@
+"""Strategy Builder API
+
+Provides a more concise and user-friendly strategy building interface.
+
+Core classes:
+- TradingContext: Trading Context fixed field accessor
+- IndicatorSpecWrapper: Indicator wrapper (.col(), .display_name)
+- BlueprintBuilder: Blueprint builder with chain calls
+- StrategyBuilder: Strategy builder (main entry)
+"""
+
+from .trading_context import TradingContext
+from .indicator_wrapper import IndicatorSpecWrapper
+from .blueprint_builder import BlueprintBuilder
+from .strategy_builder import StrategyBuilder
+
+__all__ = [
+    "TradingContext",
+    "IndicatorSpecWrapper",
+    "BlueprintBuilder",
+    "StrategyBuilder",
+]

tradepose_client/builder/blueprint_builder.py

@@ -0,0 +1,276 @@
+"""
+Blueprint 链式构建器
+
+支持链式添加 entry/exit triggers，最后通过 .build() 返回 BlueprintConfig。
+
+Usage:
+    from tradepose_client.builder import BlueprintBuilder, TradingContext
+    import polars as pl
+
+    # 创建 Base Blueprint
+    base_bp = BlueprintBuilder(
+        name="base_trend",
+        direction="Long",
+        trend_type="Trend",
+        note="基础趋势策略"
+    ).add_entry_trigger(
+        name="entry",
+        conditions=[pl.col("ema_20") > pl.col("ema_50")],
+        price_expr=pl.col("open"),
+        order_strategy="ImmediateEntry",
+        priority=1,
+        note="EMA 金叉"
+    ).add_exit_trigger(
+        name="exit",
+        conditions=[pl.col("ema_20") < pl.col("ema_50")],
+        price_expr=pl.col("open"),
+        order_strategy="ImmediateExit",
+        priority=1,
+        note="EMA 死叉"
+    ).build()
+
+    # 创建 Advanced Blueprint
+    adv_bp = BlueprintBuilder("risk_mgmt", "Long", "Trend")\
+        .add_exit_trigger(
+            name="stop_loss",
+            conditions=[],
+            price_expr=TradingContext.advanced_entry.entry_price - pl.col("atr") * 2,
+            order_strategy="StopLoss",
+            priority=1
+        )\
+        .add_exit_trigger(
+            name="take_profit",
+            conditions=[],
+            price_expr=TradingContext.advanced_entry.entry_price + pl.col("atr") * 3,
+            order_strategy="TakeProfit",
+            priority=2
+        )\
+        .build()
+"""
+
+import polars as pl
+from typing import List, Literal, Optional, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tradepose_client.models import Blueprint, Trigger, OrderStrategy
+    from tradepose_client.enums import TradeDirection, TrendType
+
+
+class BlueprintBuilder:
+    """
+    Blueprint 链式构建器
+
+    支持链式添加 entry/exit triggers，提供流畅的 API 体验。
+
+    Attributes:
+        name (str): Blueprint 名称
+        direction (str): 交易方向（"Long", "Short", "Both"）
+        trend_type (str): 趋势类型（"Trend", "Range", "Reversal"）
+        entry_first (bool): 是否必须先进场才能出场
+        note (str): 备注
+
+    Methods:
+        add_entry_trigger(...) -> BlueprintBuilder: 添加进场触发器（链式）
+        add_exit_trigger(...) -> BlueprintBuilder: 添加出场触发器（链式）
+        build() -> Blueprint: 构建最终 Blueprint 对象
+    """
+
+    def __init__(
+        self,
+        name: str,
+        direction: Union["TradeDirection", str],
+        trend_type: Union["TrendType", str] = "Trend",
+        entry_first: bool = True,
+        note: str = "",
+    ):
+        """
+        初始化 Blueprint 构建器
+
+        Args:
+            name: Blueprint 名称（唯一标识）
+            direction: 交易方向
+                - "Long": 做多
+                - "Short": 做空
+                - "Both": 双向（暂不支持）
+            trend_type: 趋势类型
+                - "Trend": 趋势跟随
+                - "Range": 区间震荡
+                - "Reversal": 反转交易
+            entry_first: 是否必须先进场才能出场（推荐 True）
+            note: Blueprint 说明
+
+        Examples:
+            >>> # Base Blueprint（简洁形式）
+            >>> bp = BlueprintBuilder("base", "Long", "Trend")
+            >>>
+            >>> # Advanced Blueprint（完整形式）
+            >>> adv_bp = BlueprintBuilder(
+            ...     name="risk_management",
+            ...     direction="Long",
+            ...     trend_type="Trend",
+            ...     entry_first=True,
+            ...     note="Stop Loss + Take Profit"
+            ... )
+        """
+        self.name = name
+        self.direction = direction
+        self.trend_type = trend_type
+        self.entry_first = entry_first
+        self.note = note
+
+        self._entry_triggers: List["Trigger"] = []
+        self._exit_triggers: List["Trigger"] = []
+
+    def add_entry_trigger(
+        self,
+        name: str,
+        conditions: List[pl.Expr],
+        price_expr: pl.Expr,
+        order_strategy: Union["OrderStrategy", str],
+        priority: int,
+        note: str = "",
+    ) -> "BlueprintBuilder":
+        """
+        添加进场触发器（链式调用）
+
+        Args:
+            name: 触发器名称（唯一标识）
+            conditions: 条件表达式列表（全部为 True 才触发）
+            price_expr: 价格表达式（Polars Expr）
+            order_strategy: 订单策略
+                - Base Blueprint 必须使用 "ImmediateEntry"
+                - Advanced Blueprint 可使用 "FavorableDelayEntry", "AdverseDelayEntry" 等
+            priority: 优先级（1-100，越小优先级越高）
+            note: 触发器说明
+
+        Returns:
+            BlueprintBuilder: 返回自身，支持链式调用
+
+        Examples:
+            >>> bp = BlueprintBuilder("base", "Long", "Trend")\
+            ...     .add_entry_trigger(
+            ...         name="entry",
+            ...         conditions=[pl.col("ema_20") > pl.col("ema_50")],
+            ...         price_expr=pl.col("open"),
+            ...         order_strategy="ImmediateEntry",
+            ...         priority=1,
+            ...         note="EMA 金叉"
+            ...     )
+        """
+        from tradepose_client.models import create_trigger
+
+        trigger = create_trigger(
+            name=name,
+            conditions=conditions,
+            price_expr=price_expr,
+            order_strategy=order_strategy,
+            priority=priority,
+            note=note,
+        )
+        self._entry_triggers.append(trigger)
+        return self
+
+    def add_exit_trigger(
+        self,
+        name: str,
+        conditions: List[pl.Expr],
+        price_expr: pl.Expr,
+        order_strategy: Union["OrderStrategy", str],
+        priority: int,
+        note: str = "",
+    ) -> "BlueprintBuilder":
+        """
+        添加出场触发器（链式调用）
+
+        Args:
+            name: 触发器名称（唯一标识）
+            conditions: 条件表达式列表（全部为 True 才触发）
+            price_expr: 价格表达式（Polars Expr）
+            order_strategy: 订单策略
+                - Base Blueprint 必须使用 "ImmediateExit"
+                - Advanced Blueprint 可使用 "StopLoss", "TakeProfit", "TrailingStop",
+                  "Breakeven", "TimeoutExit" 等
+            priority: 优先级（1-100，越小优先级越高）
+            note: 触发器说明
+
+        Returns:
+            BlueprintBuilder: 返回自身，支持链式调用
+
+        Examples:
+            >>> bp = BlueprintBuilder("risk_mgmt", "Long", "Trend")\
+            ...     .add_exit_trigger(
+            ...         name="stop_loss",
+            ...         conditions=[],
+            ...         price_expr=TradingContext.advanced_entry.entry_price - pl.col("atr") * 2,
+            ...         order_strategy="StopLoss",
+            ...         priority=1,
+            ...         note="固定止损 2 ATR"
+            ...     )\
+            ...     .add_exit_trigger(
+            ...         name="take_profit",
+            ...         conditions=[],
+            ...         price_expr=TradingContext.advanced_entry.entry_price + pl.col("atr") * 3,
+            ...         order_strategy="TakeProfit",
+            ...         priority=2,
+            ...         note="目标止盈 3 ATR"
+            ...     )
+        """
+        from tradepose_client.models import create_trigger
+
+        trigger = create_trigger(
+            name=name,
+            conditions=conditions,
+            price_expr=price_expr,
+            order_strategy=order_strategy,
+            priority=priority,
+            note=note,
+        )
+        self._exit_triggers.append(trigger)
+        return self
+
+    def build(self) -> "Blueprint":
+        """
+        构建最终 Blueprint 对象
+
+        Returns:
+            Blueprint: 完整的 Blueprint 配置对象
+
+        Raises:
+            ValueError: 如果未添加任何 trigger
+
+        Examples:
+            >>> bp = BlueprintBuilder("base", "Long", "Trend")\
+            ...     .add_entry_trigger(...)\
+            ...     .add_exit_trigger(...)\
+            ...     .build()
+            >>>
+            >>> # 用于 StrategyBuilder
+            >>> builder.set_base_blueprint(bp)
+            >>> builder.add_advanced_blueprint(adv_bp)
+        """
+        from tradepose_client.models import create_blueprint
+
+        if not self._entry_triggers and not self._exit_triggers:
+            raise ValueError(
+                f"Blueprint '{self.name}' must have at least one entry or exit trigger. "
+                f"Use .add_entry_trigger() or .add_exit_trigger() before calling .build()"
+            )
+
+        return create_blueprint(
+            name=self.name,
+            direction=self.direction,
+            entry_triggers=self._entry_triggers,
+            exit_triggers=self._exit_triggers,
+            trend_type=self.trend_type,
+            entry_first=self.entry_first,
+            note=self.note,
+        )
+
+    def __repr__(self) -> str:
+        """字符串表示"""
+        return (
+            f"BlueprintBuilder(name='{self.name}', "
+            f"direction='{self.direction}', "
+            f"entry_triggers={len(self._entry_triggers)}, "
+            f"exit_triggers={len(self._exit_triggers)})"
+        )

tradepose_client/builder/indicator_wrapper.py

@@ -0,0 +1,126 @@
+"""
+IndicatorSpec 包装器
+
+提供更便捷的指标访问方式：
+- .col() -> pl.Expr（用于条件表达式）
+- .display_name -> str（用于依赖引用，作为属性访问）
+- .spec -> IndicatorSpec（返回原始对象，用于最终 build）
+
+Usage:
+    from tradepose_client.builder import StrategyBuilder
+
+    builder = StrategyBuilder(...)
+    atr = builder.add_indicator("atr", period=21, freq="1D", shift=1)
+
+    # 使用 .col() 在条件表达式中
+    condition = atr.col() > 100
+    stop_loss_price = entry_price - atr.col() * 2
+
+    # 使用 .display_name 引用依赖（SuperTrend 引用 ATR）
+    st = builder.add_indicator(
+        "supertrend",
+        multiplier=3.0,
+        volatility_column=atr.display_name,  # 属性访问
+        freq="1D",
+        shift=1
+    )
+"""
+
+import polars as pl
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tradepose_client.models import IndicatorSpec
+
+
+class IndicatorSpecWrapper:
+    """
+    IndicatorSpec 包装器
+
+    封装 IndicatorSpec，提供更便捷的访问方式。
+
+    Attributes:
+        display_name (str): 完整列名（属性访问）
+        spec (IndicatorSpec): 原始 IndicatorSpec 对象
+
+    Methods:
+        col() -> pl.Expr: 返回 Polars 表达式
+    """
+
+    def __init__(self, spec: "IndicatorSpec"):
+        """
+        初始化包装器
+
+        Args:
+            spec: IndicatorSpec 对象
+        """
+        self._spec = spec
+
+    def col(self) -> pl.Expr:
+        """
+        返回 Polars 表达式
+
+        用于条件表达式或价格计算。
+
+        Returns:
+            pl.Expr: Polars 列表达式，等价于 pl.col(display_name)
+
+        Examples:
+            >>> atr = builder.add_indicator("atr", period=21, freq="1D", shift=1)
+            >>>
+            >>> # 在条件中使用
+            >>> condition = atr.col() > 100
+            >>>
+            >>> # 在价格表达式中使用
+            >>> stop_loss_price = entry_price - atr.col() * 2
+            >>>
+            >>> # 访问 struct 字段（如 SuperTrend）
+            >>> st = builder.add_indicator("supertrend", ...)
+            >>> direction = st.col().struct.field("direction")
+        """
+        return self._spec.col()
+
+    @property
+    def display_name(self) -> str:
+        """
+        完整列名（属性访问）
+
+        用于指标依赖引用（如 SuperTrend 引用 ATR 的列名）。
+
+        Returns:
+            str: 完整的列名，格式为 "{instrument_id}_{freq}_{indicator_short_name}"
+
+        Examples:
+            >>> atr = builder.add_indicator("atr", period=21, freq="1D", shift=1)
+            >>> print(atr.display_name)
+            "US100.cash_M15_FTMO_FUTURE_1D_ATR|21"
+            >>>
+            >>> # 用于依赖引用
+            >>> st = builder.add_indicator(
+            ...     "supertrend",
+            ...     multiplier=3.0,
+            ...     volatility_column=atr.display_name,  # 引用 ATR 列名
+            ...     freq="1D",
+            ...     shift=1
+            ... )
+        """
+        return self._spec.display_name()
+
+    @property
+    def spec(self) -> "IndicatorSpec":
+        """
+        返回原始 IndicatorSpec 对象
+
+        用于最终构建 StrategyConfig。
+
+        Returns:
+            IndicatorSpec: 原始指标规范对象
+
+        Note:
+            用户通常不需要直接访问此属性，仅在高级场景下使用。
+        """
+        return self._spec
+
+    def __repr__(self) -> str:
+        """字符串表示"""
+        return f"IndicatorSpecWrapper(display_name='{self.display_name}')"

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,162 @@
+"""
+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, context_type: str):
+        self._context_name = context_name
+        self._context_type = context_type
+
+    @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）
+        """
+        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:
+        """
+        进场以来最高价
+
+        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", "base")
+    advanced_entry = TradingContextProxy("advanced_entry_trading_context", "advanced")
+    advanced_exit = TradingContextProxy("advanced_exit_trading_context", "advanced")
+
+
+# 向后兼容的别名
+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"

tradepose_client/models.py

@@ -9,79 +9,13 @@ Pydantic 模型用於策略配置 (V2 - 自動轉換版本)
 import json
 from enum import Enum
 from io import StringIO
-from typing import Any, Dict, List, Literal, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
 import polars as pl
 from pydantic import BaseModel, Field, field_serializer, field_validator
 
-
-class Freq(str, Enum):
-    """時間頻率枚舉（與 Rust Freq enum 一致）
-
-    對應 Rust 的 Freq enum
-    """
-
-    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):
-    """訂單策略枚舉（與 Rust OrderStrategy enum 一致）
-
-    對應 Rust 的 OrderStrategy enum，使用字符串值以便 JSON 序列化
-
-    Rust 對應關係:
-    - 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)
-    """
-
-    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):
-    """星期列舉（與 Rust Weekday enum 一致）
-
-    用於 Market Profile 的 WeeklyTime 配置
-
-    對應關係：
-    - 0 (週一) → "Mon"
-    - 1 (週二) → "Tue"
-    - 2 (週三) → "Wed"
-    - 3 (週四) → "Thu"
-    - 4 (週五) → "Fri"
-    - 5 (週六) → "Sat"
-    - 6 (週日) → "Sun"
-    """
-
-    MON = "Mon"
-    TUE = "Tue"
-    WED = "Wed"
-    THU = "Thu"
-    FRI = "Fri"
-    SAT = "Sat"
-    SUN = "Sun"
+# Import enums from enums.py
+from .enums import Freq, OrderStrategy, Weekday, TradeDirection, TrendType
 
 
 class PolarsExprField:
@@ -1425,8 +1359,8 @@ class Blueprint(BaseModel):
     """策略藍圖"""
 
     name: str = Field(..., description="藍圖名稱")
-    direction: Literal["Long", "Short", "Both"] = Field(..., description="方向")
-    trend_type: Literal["Trend", "Range", "Reversal"] = Field(
+    direction: Union[TradeDirection, str] = Field(..., description="方向")
+    trend_type: Union[TrendType, str] = Field(
         ..., description="趨勢類型"
     )
     entry_first: bool = Field(..., description="是否優先進場")
@@ -1654,10 +1588,10 @@ def create_trigger(
 
 def create_blueprint(
     name: str,
-    direction: Literal["Long", "Short", "Both"],
+    direction: Union[TradeDirection, str],
     entry_triggers: List[Trigger],
     exit_triggers: List[Trigger],
-    trend_type: Literal["Trend", "Range", "Reversal"] = "Trend",
+    trend_type: Union[TrendType, str] = "Trend",
     entry_first: bool = True,
     note: str = "",
 ) -> Blueprint:

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

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

tradepose_client-0.1.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+tradepose_client/__init__.py,sha256=51JWgNgRTfKzm52NVCb9VT7rQcGd20f2DoLuF6RzReA,3907
+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/schema.py,sha256=lPcJU-1xKcGFRoeuvqovrg4LUiOLO5bRZiMVyDkKHUQ,6357
+tradepose_client/viz.py,sha256=qu9zyAXa_Q7D4rxdgN55JyYiY24ZD3r0jf2SWtqGZYg,22989
+tradepose_client/api/__init__.py,sha256=ezeMxOBrUDRhlqZNO-X0X9KbNJGccDseKQ95zAvyhFY,218
+tradepose_client/api/engine.py,sha256=IRmQPu7ECfFeIkve2b3txxt_D--v4arHvsVRZ0orx1w,1423
+tradepose_client/api/export.py,sha256=gYW6yIHm1e0HZxvUA4k15tYqLfrihmssosJ2vXimT5k,27838
+tradepose_client/api/health.py,sha256=NBZstYvVQszxDOstCmBt3A3anjNv7wuCsMOjup0DS5g,1889
+tradepose_client/api/strategy.py,sha256=7cPurXqf9XCxyxSHaG_78GmEtg-KNJJhzNZNdn93ji8,7316
+tradepose_client/builder/__init__.py,sha256=PIrsZcxP5cEa2_K1Zzpcf2FVc62iavKCNT6D8JbXaGU,643
+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-0.1.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-tradepose_client/__init__.py,sha256=cZL8Feo-ZkQ5bR7E-G7afg740Cu-oXaZ_s1ox6bPDqs,3549
-tradepose_client/analysis.py,sha256=RNpk3i9_1uUXM_-K-xYbG3Ckg-MoOwQ6gSExua2N4N8,7563
-tradepose_client/client.py,sha256=1qD4pnIjCXKgE3VXeB6EgkNuCXvDJEbmPldIjIzAVmk,1798
-tradepose_client/models.py,sha256=j1UmUqGEIHObyAxfTETg5Kc83ipylr-Y0IivGuJB16M,66374
-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
-tradepose_client/api/engine.py,sha256=IRmQPu7ECfFeIkve2b3txxt_D--v4arHvsVRZ0orx1w,1423
-tradepose_client/api/export.py,sha256=gYW6yIHm1e0HZxvUA4k15tYqLfrihmssosJ2vXimT5k,27838
-tradepose_client/api/health.py,sha256=NBZstYvVQszxDOstCmBt3A3anjNv7wuCsMOjup0DS5g,1889
-tradepose_client/api/strategy.py,sha256=7cPurXqf9XCxyxSHaG_78GmEtg-KNJJhzNZNdn93ji8,7316
-tradepose_client-0.1.0.dist-info/METADATA,sha256=Ked6fn17kxv90zUewN9-cGiv-wzCqFyT27YQMXhfv88,14056
-tradepose_client-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-tradepose_client-0.1.0.dist-info/licenses/LICENSE,sha256=6qYWNkUbxmJl1iN7c4DoM1_8ASsZyXemFO1D0wXtiHk,1071
-tradepose_client-0.1.0.dist-info/RECORD,,