tradepose-models 1.1.0__py3-none-any.whl

tradepose_models/strategy/performance.py

@@ -0,0 +1,66 @@
+"""
+Strategy Performance Model
+
+Provides StrategyPerformance for caching strategy metrics in Redis.
+Used for position size calculation and performance monitoring.
+"""
+
+from datetime import datetime
+from decimal import Decimal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class StrategyPerformance(BaseModel):
+    """Strategy performance metrics (Redis cache).
+
+    Stores calculated performance metrics for a strategy+blueprint combination.
+    Used by TradingDecisionJob for position size calculation.
+
+    Redis Key Pattern: performance:{user_id}:{strategy_name}:{blueprint_name}
+    """
+
+    strategy_name: str = Field(..., description="Strategy name")
+    blueprint_name: str = Field(..., description="Blueprint name")
+    user_id: UUID = Field(..., description="User UUID")
+    instrument: str = Field(..., description="Trading instrument (e.g., XAUUSD)")
+
+    # Performance metrics
+    win_rate: float = Field(..., description="Win rate (0-1)")
+    avg_pnl_pct: float = Field(..., description="Average PnL percentage")
+    mae_q90: float = Field(..., description="Maximum Adverse Excursion 90th percentile (%)")
+    mfe_q90: float = Field(..., description="Maximum Favorable Excursion 90th percentile (%)")
+    recovery_factor: float = Field(..., description="Recovery factor")
+
+    # Position size calculation
+    expected_loss_per_contract: Decimal = Field(
+        ...,
+        description="Expected loss per contract in quote currency (e.g., 40000 USD)",
+    )
+    quote_currency: str = Field(..., description="Quote currency (e.g., USD)")
+    contract_size: Decimal = Field(..., description="Contract size per lot")
+
+    # Cache metadata
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+    def calculate_position_size(self, risk_capital: Decimal) -> Decimal:
+        """Calculate position size based on risk capital.
+
+        Args:
+            risk_capital: User's risk capital in portfolio currency
+
+        Returns:
+            Number of contracts/lots to trade
+
+        Example:
+            >>> perf = StrategyPerformance(
+            ...     expected_loss_per_contract=Decimal("40000"),
+            ...     ...
+            ... )
+            >>> qty = perf.calculate_position_size(Decimal("80000"))
+            >>> # qty = 80000 / 40000 = 2 contracts
+        """
+        if self.expected_loss_per_contract <= 0:
+            return Decimal("0")
+        return risk_capital / self.expected_loss_per_contract

tradepose_models/strategy/portfolio.py

@@ -0,0 +1,171 @@
+"""
+Portfolio Module
+
+Provides Portfolio class as a selection view for indexing backtest results.
+"""
+
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+
+from pydantic import BaseModel, Field
+
+from tradepose_models.enums import BrokerType
+
+from .registry import BlueprintSelection
+
+if TYPE_CHECKING:
+    from .config import StrategyConfig
+    from .registry import StrategyRegistry
+
+
+class Portfolio(BaseModel):
+    """
+    Portfolio - 選取視圖，用於索引回測結果
+
+    Portfolio 儲存 BlueprintSelection 引用（而非資料複製），
+    需要 StrategyRegistry 來解析實際的 StrategyConfig。
+
+    Example:
+        >>> portfolio = registry.select(
+        ...     name="Q1_Portfolio",
+        ...     selections=[("VA_Breakout", "va_long"), ("VA_Breakout", "va_short")],
+        ...     capital=100000,
+        ... )
+        >>> configs = portfolio.get_configs(registry)
+        >>> batch = tester.submit(strategies=configs, periods=[...])
+    """
+
+    name: str = Field(..., description="Portfolio 名稱")
+    selections: List[BlueprintSelection] = Field(
+        default_factory=list, description="選取的 (strategy_name, blueprint_name) 列表"
+    )
+
+    # 帳戶配置
+    capital: Decimal = Field(default=Decimal("0"), description="資金")
+    currency: str = Field(default="USD", description="貨幣")
+    account_source: Optional[str] = Field(None, description="帳戶來源")
+    broker_type: Optional[BrokerType] = Field(None, description="交易平台/Broker 類型")
+    instrument_mapping: Optional[Dict[str, str]] = Field(
+        None, description="商品映射 (base_instrument → target_symbol)，例如 {'BTC': 'BTCUSDT'}"
+    )
+
+    def get_configs(self, registry: "StrategyRegistry") -> List["StrategyConfig"]:
+        """
+        取得選取的 configs（用於傳給 BatchTester）
+
+        Args:
+            registry: StrategyRegistry 實例
+
+        Returns:
+            單一 blueprint 的 StrategyConfig 列表
+
+        Raises:
+            KeyError: 如果任何選取不存在於 registry
+        """
+        configs = []
+        for sel in self.selections:
+            entry = registry.get(sel.strategy_name, sel.blueprint_name)
+            if entry is None:
+                raise KeyError(
+                    f"Selection not found in registry: "
+                    f"strategy='{sel.strategy_name}', blueprint='{sel.blueprint_name}'"
+                )
+            configs.append(entry.to_single_blueprint_config())
+        return configs
+
+    def add_selection(
+        self,
+        strategy_name: str,
+        blueprint_name: str,
+    ) -> "Portfolio":
+        """
+        新增選取（返回新實例）
+
+        Args:
+            strategy_name: 策略名稱
+            blueprint_name: Blueprint 名稱
+
+        Returns:
+            新的 Portfolio 實例
+        """
+        selection = BlueprintSelection(strategy_name=strategy_name, blueprint_name=blueprint_name)
+        if selection in self.selections:
+            return self
+        return self.model_copy(update={"selections": [*self.selections, selection]})
+
+    def remove_selection(
+        self,
+        strategy_name: str,
+        blueprint_name: str,
+    ) -> "Portfolio":
+        """
+        移除選取（返回新實例）
+
+        Args:
+            strategy_name: 策略名稱
+            blueprint_name: Blueprint 名稱
+
+        Returns:
+            新的 Portfolio 實例
+        """
+        selection = BlueprintSelection(strategy_name=strategy_name, blueprint_name=blueprint_name)
+        if selection not in self.selections:
+            return self
+        return self.model_copy(
+            update={"selections": [s for s in self.selections if s != selection]}
+        )
+
+    @property
+    def strategy_names(self) -> List[str]:
+        """取得所有策略名稱（去重）"""
+        return list(set(sel.strategy_name for sel in self.selections))
+
+    @property
+    def selection_count(self) -> int:
+        """選取數量"""
+        return len(self.selections)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """轉換為字典"""
+        return self.model_dump(mode="json", exclude_none=True)
+
+    def to_json(self, indent: int = 2) -> str:
+        """序列化為 JSON 字串"""
+        return self.model_dump_json(indent=indent, exclude_none=True)
+
+    def save(self, filepath: str) -> None:
+        """儲存至 JSON 檔案"""
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(self.to_json())
+
+    @classmethod
+    def load(cls, filepath: str) -> "Portfolio":
+        """從 JSON 檔案載入"""
+        with open(filepath, "r", encoding="utf-8") as f:
+            return cls.model_validate_json(f.read())
+
+    @classmethod
+    def from_api(cls, api_response: Union[Dict[str, Any], str]) -> "Portfolio":
+        """從 API 響應建立"""
+        if isinstance(api_response, str):
+            return cls.model_validate_json(api_response)
+        return cls.model_validate(api_response)
+
+    def __len__(self) -> int:
+        """選取數量"""
+        return len(self.selections)
+
+    def __contains__(self, item: Tuple[str, str]) -> bool:
+        """檢查選取是否存在"""
+        selection = BlueprintSelection(strategy_name=item[0], blueprint_name=item[1])
+        return selection in self.selections
+
+    def __iter__(self):
+        """迭代選取"""
+        return iter(self.selections)
+
+    def __repr__(self) -> str:
+        return (
+            f"Portfolio(name={self.name!r}, selections={len(self.selections)}, "
+            f"capital={self.capital}, currency={self.currency!r})"
+        )

tradepose_models/strategy/registry.py

@@ -0,0 +1,249 @@
+"""
+Strategy Registry Module
+
+Provides StrategyRegistry for managing strategies with (strategy_name, blueprint_name)
+as unique keys. Low-coupling design - does not call external objects directly.
+"""
+
+from typing import TYPE_CHECKING, Dict, Iterator, List, Optional, Tuple
+
+from pydantic import BaseModel, PrivateAttr
+
+from .blueprint import Blueprint
+from .config import StrategyConfig
+
+if TYPE_CHECKING:
+    from .portfolio import Portfolio
+
+
+class BlueprintSelection(BaseModel):
+    """選取鍵，代表 Registry 中的一個 entry"""
+
+    strategy_name: str
+    blueprint_name: str
+
+    def to_tuple(self) -> Tuple[str, str]:
+        """轉換為 tuple"""
+        return (self.strategy_name, self.blueprint_name)
+
+    @classmethod
+    def from_tuple(cls, t: Tuple[str, str]) -> "BlueprintSelection":
+        """從 tuple 建立"""
+        return cls(strategy_name=t[0], blueprint_name=t[1])
+
+    def __hash__(self) -> int:
+        return hash(self.to_tuple())
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, BlueprintSelection):
+            return self.to_tuple() == other.to_tuple()
+        return False
+
+    def __repr__(self) -> str:
+        return f"BlueprintSelection({self.strategy_name!r}, {self.blueprint_name!r})"
+
+
+class RegistryEntry(BaseModel):
+    """Registry entry，儲存對原始 StrategyConfig 的引用"""
+
+    strategy: StrategyConfig
+    blueprint_name: str
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    @property
+    def key(self) -> BlueprintSelection:
+        """取得選取鍵"""
+        return BlueprintSelection(
+            strategy_name=self.strategy.name, blueprint_name=self.blueprint_name
+        )
+
+    @property
+    def blueprint(self) -> Blueprint:
+        """取得此 entry 對應的 Blueprint"""
+        if self.strategy.base_blueprint.name == self.blueprint_name:
+            return self.strategy.base_blueprint
+        for bp in self.strategy.advanced_blueprints:
+            if bp.name == self.blueprint_name:
+                return bp
+        raise ValueError(
+            f"Blueprint '{self.blueprint_name}' not found in strategy '{self.strategy.name}'"
+        )
+
+    def to_single_blueprint_config(self) -> StrategyConfig:
+        """轉換為單一 blueprint 的 StrategyConfig"""
+        return StrategyConfig(
+            name=f"{self.strategy.name}__{self.blueprint_name}",
+            base_instrument=self.strategy.base_instrument,
+            base_freq=self.strategy.base_freq,
+            note=self.strategy.note,
+            volatility_indicator=self.strategy.volatility_indicator,
+            indicators=self.strategy.indicators,
+            base_blueprint=self.blueprint,
+            advanced_blueprints=[],
+        )
+
+    def __repr__(self) -> str:
+        return f"RegistryEntry({self.strategy.name!r}, {self.blueprint_name!r})"
+
+
+class StrategyRegistry(BaseModel):
+    """
+    策略註冊表 - 低耦合設計，只負責儲存和保證唯一性
+
+    使用 (strategy_name, blueprint_name) 作為唯一 key。
+    當加入有多個 blueprints 的 StrategyConfig 時，自動拆成多個 entries。
+
+    Example:
+        >>> registry = StrategyRegistry()
+        >>> strategy = StrategyConfig.load("va_breakout.json")
+        >>> registry.add(strategy)  # 自動拆成多個 entries
+        >>> configs = registry.get_configs()  # 取得所有 configs
+        >>> # 使用者自己傳給 BatchTester
+        >>> batch = tester.submit(strategies=configs, periods=[...])
+    """
+
+    _entries: Dict[Tuple[str, str], RegistryEntry] = PrivateAttr(default_factory=dict)
+    _strategies: Dict[str, StrategyConfig] = PrivateAttr(default_factory=dict)
+
+    def add(self, strategy: StrategyConfig) -> List[BlueprintSelection]:
+        """
+        加入策略，自動拆分所有 blueprints
+
+        Args:
+            strategy: 要加入的 StrategyConfig
+
+        Returns:
+            建立的 BlueprintSelection 列表
+
+        Raises:
+            ValueError: 如果任何 (strategy_name, blueprint_name) 已存在
+        """
+        all_bps = [strategy.base_blueprint] + list(strategy.advanced_blueprints)
+
+        # 檢查重複
+        for bp in all_bps:
+            key = (strategy.name, bp.name)
+            if key in self._entries:
+                raise ValueError(
+                    f"Entry already exists: strategy='{strategy.name}', blueprint='{bp.name}'"
+                )
+
+        # 儲存原始策略
+        self._strategies[strategy.name] = strategy
+
+        # 建立 entries
+        created = []
+        for bp in all_bps:
+            key = (strategy.name, bp.name)
+            self._entries[key] = RegistryEntry(strategy=strategy, blueprint_name=bp.name)
+            created.append(BlueprintSelection(strategy_name=strategy.name, blueprint_name=bp.name))
+
+        return created
+
+    def add_or_replace(self, strategy: StrategyConfig) -> List[BlueprintSelection]:
+        """加入或取代策略"""
+        if strategy.name in self._strategies:
+            self.remove(strategy.name)
+        return self.add(strategy)
+
+    def get(self, strategy_name: str, blueprint_name: str) -> Optional[RegistryEntry]:
+        """取得特定 entry"""
+        return self._entries.get((strategy_name, blueprint_name))
+
+    def get_strategy(self, strategy_name: str) -> Optional[StrategyConfig]:
+        """取得原始 StrategyConfig（包含所有 blueprints）"""
+        return self._strategies.get(strategy_name)
+
+    def get_configs(self) -> List[StrategyConfig]:
+        """取得所有單一 blueprint configs（用於傳給 BatchTester）"""
+        return [entry.to_single_blueprint_config() for entry in self._entries.values()]
+
+    def remove(self, strategy_name: str) -> int:
+        """
+        移除策略的所有 entries
+
+        Returns:
+            移除的 entry 數量
+        """
+        keys = [k for k in self._entries if k[0] == strategy_name]
+        for k in keys:
+            del self._entries[k]
+        self._strategies.pop(strategy_name, None)
+        return len(keys)
+
+    def select(
+        self,
+        name: str,
+        selections: List[Tuple[str, str]],
+        capital: float = 0,
+        currency: str = "USD",
+        account_source: Optional[str] = None,
+        platform: Optional[str] = None,
+    ) -> "Portfolio":
+        """
+        建立 Portfolio
+
+        Args:
+            name: Portfolio 名稱
+            selections: 選取的 (strategy_name, blueprint_name) 列表
+            capital: 資金
+            currency: 貨幣
+            account_source: 帳戶來源
+            platform: 交易平台
+
+        Returns:
+            Portfolio 實例
+
+        Raises:
+            KeyError: 如果任何選取不存在
+        """
+        for sel in selections:
+            if sel not in self._entries:
+                raise KeyError(f"Selection not found: strategy='{sel[0]}', blueprint='{sel[1]}'")
+
+        from .portfolio import Portfolio
+
+        return Portfolio(
+            name=name,
+            selections=[
+                BlueprintSelection(strategy_name=s[0], blueprint_name=s[1]) for s in selections
+            ],
+            capital=capital,
+            currency=currency,
+            account_source=account_source,
+            platform=platform,
+        )
+
+    def keys(self) -> List[BlueprintSelection]:
+        """取得所有選取鍵"""
+        return [BlueprintSelection(strategy_name=k[0], blueprint_name=k[1]) for k in self._entries]
+
+    def strategy_names(self) -> List[str]:
+        """取得所有策略名稱"""
+        return list(self._strategies.keys())
+
+    def blueprint_names(self, strategy_name: str) -> List[str]:
+        """取得特定策略的所有 blueprint 名稱"""
+        return [k[1] for k in self._entries if k[0] == strategy_name]
+
+    def __len__(self) -> int:
+        """Entry 數量"""
+        return len(self._entries)
+
+    def __contains__(self, key: Tuple[str, str]) -> bool:
+        """檢查 entry 是否存在"""
+        return key in self._entries
+
+    def __getitem__(self, key: Tuple[str, str]) -> RegistryEntry:
+        """取得 entry: registry[('strategy', 'blueprint')]"""
+        if key not in self._entries:
+            raise KeyError(f"Entry not found: strategy='{key[0]}', blueprint='{key[1]}'")
+        return self._entries[key]
+
+    def __iter__(self) -> Iterator[RegistryEntry]:
+        """迭代所有 entries"""
+        return iter(self._entries.values())
+
+    def __repr__(self) -> str:
+        return f"StrategyRegistry(strategies={len(self._strategies)}, entries={len(self._entries)})"

tradepose_models/strategy/requests.py

@@ -0,0 +1,33 @@
+"""Strategy API request/response models."""
+
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class RegisterStrategyRequest(BaseModel):
+    """Request model for registering a strategy."""
+
+    strategy_code: str = Field(..., description="Strategy configuration Python code")
+    overwrite: bool = Field(default=False, description="Overwrite if strategy exists")
+
+
+class RegisterStrategyResponse(BaseModel):
+    """Response model for strategy registration."""
+
+    task_id: UUID
+    message: str
+
+
+class ListStrategiesRequest(BaseModel):
+    """Request model for listing strategies."""
+
+    full: bool = Field(default=False, description="Return full configs or summary")
+    instrument_id: str | None = Field(default=None, description="Filter by instrument ID")
+
+
+class ListStrategiesResponse(BaseModel):
+    """Response model for listing strategies."""
+
+    task_id: UUID
+    message: str

tradepose_models/strategy/trigger.py

@@ -0,0 +1,77 @@
+"""
+Trigger Model
+
+Provides the Trigger class for entry/exit triggers with conditions and price expressions.
+"""
+
+from typing import Any, List, Optional
+
+import polars as pl
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
+
+from ..enums import OrderStrategy
+from ..indicators import PolarsExprField
+
+
+class Trigger(BaseModel):
+    """進出場觸發器
+
+    使用方式：
+    - 讀取：trigger.conditions 直接得到 List[pl.Expr]
+    - 寫入：可直接賦值 pl.col("close") > 100
+    """
+
+    name: str = Field(..., description="觸發器名稱")
+    order_strategy: OrderStrategy = Field(..., description="訂單策略（OrderStrategy enum）")
+    priority: int = Field(..., description="優先級")
+    note: Optional[str] = Field(None, description="備註")
+
+    # 直接使用 pl.Expr 類型
+    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}'. Valid values: {', '.join(valid_values)}"
+                )
+        return v
+
+    @field_validator("conditions", mode="before")
+    @classmethod
+    def validate_conditions(cls, v: Any) -> List[pl.Expr]:
+        """自動轉換 conditions 為 List[pl.Expr]"""
+        if not v:
+            return []
+
+        result = []
+        for item in v:
+            result.append(PolarsExprField.deserialize(item))
+        return result
+
+    @field_validator("price_expr", mode="before")
+    @classmethod
+    def validate_price_expr(cls, v: Any) -> pl.Expr:
+        """自動轉換 price_expr 為 pl.Expr"""
+        return PolarsExprField.deserialize(v)
+
+    @field_serializer("conditions")
+    def serialize_conditions(self, conditions: List[pl.Expr]) -> List[dict]:
+        """序列化 conditions 為 dict 列表（與服務器格式一致）"""
+        return [PolarsExprField.serialize(expr) for expr in conditions]
+
+    @field_serializer("price_expr")
+    def serialize_price_expr(self, price_expr: pl.Expr) -> dict:
+        """序列化 price_expr 為 dict（與服務器格式一致）"""
+        return PolarsExprField.serialize(price_expr)
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True  # 允許 pl.Expr 這種自定義類型
+    )

tradepose_models/trading/__init__.py

@@ -0,0 +1,55 @@
+"""Trading-related models (orders, positions, executions, engagements)."""
+
+from tradepose_models.trading.engagement import Engagement
+from tradepose_models.trading.orderbook import OrderbookEntry
+from tradepose_models.trading.orders import (
+    ExecutionReport,
+    Order,
+    OrderSide,
+    OrderStatus,
+    OrderStrategy,
+    OrderSubmitRequest,
+    OrderType,
+    TimeInForce,
+)
+from tradepose_models.trading.positions import (
+    ClosedPosition,
+    Position,
+    PositionSide,
+)
+from tradepose_models.trading.trader_commands import (
+    BaseTraderCommand,
+    CancelOrderCommand,
+    ExecuteOrderCommand,
+    ModifyOrderCommand,
+    SyncBrokerStatusCommand,
+)
+from tradepose_models.trading.trades_execution import TradeExecution
+
+__all__ = [
+    # Orders
+    "Order",
+    "OrderSubmitRequest",
+    "ExecutionReport",
+    "OrderSide",
+    "OrderType",
+    "OrderStatus",
+    "TimeInForce",
+    "OrderStrategy",
+    # Positions
+    "Position",
+    "ClosedPosition",
+    "PositionSide",
+    # Trade Executions
+    "TradeExecution",
+    # Engagements
+    "Engagement",
+    # Orderbook
+    "OrderbookEntry",
+    # Trader Commands
+    "BaseTraderCommand",
+    "ExecuteOrderCommand",
+    "CancelOrderCommand",
+    "ModifyOrderCommand",
+    "SyncBrokerStatusCommand",
+]