tradepose-models 1.1.0__py3-none-any.whl

tradepose_models/schemas/trades.py

@@ -0,0 +1,64 @@
+"""
+Trades Schema
+
+Polars schema definition for trades data from backtest results or latest trades export.
+"""
+
+import polars as pl
+
+# Trades Schema (from backtest-results or latest-trades export)
+# Complete schema matching API response with MAE/MFE fields
+trades_schema = {
+    # Position identifiers
+    "final_position_id": pl.UInt32,
+    "position_id": pl.UInt32,
+    "direction": pl.Int32,  # -1 for Short, 1 for Long
+    "status": pl.Boolean,  # false = closed, true = open
+    # Entry details
+    "entry_idx": pl.UInt32,
+    "entry_time": pl.Datetime("ms"),
+    "entry_price": pl.Float64,
+    "entry_reason": pl.UInt32,
+    "favorable_entry_hypo_price": pl.Float64,
+    "adverse_entry_hypo_price": pl.Float64,
+    "favorable_entry_strategy": pl.UInt32,
+    "adverse_entry_strategy": pl.UInt32,
+    # Exit details
+    "exit_idx": pl.UInt32,
+    "exit_time": pl.Datetime("ms"),
+    "exit_price": pl.Float64,
+    "exit_reason": pl.UInt32,
+    "favorable_exit_hypo_price": pl.Float64,
+    "adverse_exit_hypo_price": pl.Float64,
+    "favorable_exit_strategy": pl.UInt32,
+    "adverse_exit_strategy": pl.UInt32,
+    # Holding period
+    "holding_seconds": pl.Int64,
+    "holding_bars": pl.UInt32,
+    # MAE/MFE metrics (Maximum Adverse/Favorable Excursion)
+    "g_mfe": pl.Float64,  # Global Maximum Favorable Excursion
+    "mae": pl.Float64,  # Maximum Adverse Excursion
+    "mfe": pl.Float64,  # Maximum Favorable Excursion
+    "mae_lv1": pl.Float64,  # MAE Level 1
+    "mhl": pl.Float64,  # Maximum High/Low
+    # MAE/MFE indices (bar index where each occurred)
+    "g_mfe_idx": pl.UInt32,
+    "mae_idx": pl.UInt32,
+    "mfe_idx": pl.UInt32,
+    "mae_lv1_idx": pl.UInt32,
+    "mhl_idx": pl.UInt32,
+    # Volatility at each key point (typically ATR)
+    "entry_volatility": pl.Float64,
+    "exit_volatility": pl.Float64,
+    "g_mfe_volatility": pl.Float64,
+    "mae_volatility": pl.Float64,
+    "mfe_volatility": pl.Float64,
+    "mae_lv1_volatility": pl.Float64,
+    "mhl_volatility": pl.Float64,
+    # P&L metrics
+    "pnl": pl.Float64,  # Absolute profit/loss
+    "pnl_pct": pl.Float64,  # Percentage profit/loss
+    # Metadata
+    "strategy_name": pl.Utf8,
+    "blueprint_name": pl.Utf8,
+}

tradepose_models/schemas.py

@@ -0,0 +1,34 @@
+"""Shared data schemas and DTOs (共用數據模式).
+
+This module contains Pydantic models for domain objects and data transfer
+objects (DTOs) that are shared across multiple packages.
+
+這個模組包含跨多個包共享的領域對象和數據傳輸對象（DTO）的 Pydantic 模型。
+
+Example usage:
+    from tradepose_models.schemas import PlanLimits, TaskResponse
+
+    # Use in gateway to enforce limits
+    limits = PlanLimits(
+        max_requests_per_minute=100,
+        max_concurrent_tasks=5
+    )
+
+    # Use in client to understand capabilities
+    plan = client.get_plan()
+    print(f"You can run {plan.limits.max_concurrent_tasks} tasks")
+"""
+
+
+# Placeholder for shared schemas
+# Models will be migrated here from gateway as needed
+# 共用模式將根據需要從 gateway 遷移到這裡
+
+# Example structure:
+# class PlanLimits(BaseModel):
+#     """Rate limits and quotas for subscription plans."""
+#     max_requests_per_minute: int
+#     max_concurrent_tasks: int
+#     max_strategies: int
+
+__all__ = []

tradepose_models/shared.py

@@ -0,0 +1,15 @@
+"""Shared models used across Gateway and Client.
+
+This module will be deprecated in favor of the more organized structure:
+- enums.py
+- schemas.py
+- validators.py
+- types.py
+
+Please import from those modules instead of this one.
+"""
+
+# This file is kept for backward compatibility
+# New models should be added to the appropriate specialized module
+
+__all__ = []

tradepose_models/strategy/__init__.py

@@ -0,0 +1,52 @@
+"""Strategy Configuration Models.
+
+Provides models for strategy configuration including IndicatorSpec, Trigger,
+Blueprint, and StrategyConfig, plus API request/response models.
+"""
+
+from .base import StrategyBase
+from .blueprint import Blueprint
+from .config import StrategyConfig, parse_strategy
+from .entities import BlueprintEntity, StrategyEntity
+from .helpers import create_blueprint, create_indicator_spec, create_trigger
+from .indicator_spec import IndicatorConfig, IndicatorSpec
+from .performance import StrategyPerformance
+from .portfolio import Portfolio
+from .registry import BlueprintSelection, RegistryEntry, StrategyRegistry
+from .requests import (
+    ListStrategiesRequest,
+    ListStrategiesResponse,
+    RegisterStrategyRequest,
+    RegisterStrategyResponse,
+)
+from .trigger import Trigger
+
+__all__ = [
+    # Core models
+    "IndicatorSpec",
+    "IndicatorConfig",
+    "Trigger",
+    "Blueprint",
+    "StrategyConfig",
+    # Base and Entities
+    "StrategyBase",
+    "StrategyEntity",
+    "BlueprintEntity",
+    # Performance
+    "StrategyPerformance",
+    # Registry and Portfolio
+    "BlueprintSelection",
+    "RegistryEntry",
+    "StrategyRegistry",
+    "Portfolio",
+    # Helpers
+    "parse_strategy",
+    "create_indicator_spec",
+    "create_trigger",
+    "create_blueprint",
+    # API requests/responses
+    "RegisterStrategyRequest",
+    "RegisterStrategyResponse",
+    "ListStrategiesRequest",
+    "ListStrategiesResponse",
+]

tradepose_models/strategy/base.py

@@ -0,0 +1,56 @@
+"""
+Strategy Base Model
+
+Provides the StrategyBase class with shared strategy fields (without blueprints).
+Used as base class for StrategyConfig and StrategyEntity.
+"""
+
+from typing import Any, List, Optional
+
+import polars as pl
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
+
+from ..enums import Freq
+from ..indicators import PolarsExprField
+from .indicator_spec import IndicatorSpec
+
+
+class StrategyBase(BaseModel):
+    """Strategy base class with shared fields (without blueprints).
+
+    Contains the core strategy configuration that is shared between:
+    - StrategyConfig: Local/backtest model with embedded blueprints
+    - StrategyEntity: Database entity with UUID and timestamps
+    """
+
+    name: str = Field(..., description="Strategy name")
+    base_instrument: str = Field(..., description="Base trading instrument")
+    base_freq: Freq = Field(..., description="Base frequency")
+    note: str = Field(..., description="Strategy notes")
+
+    volatility_indicator: Optional[pl.Expr] = Field(
+        None,
+        description="Volatility field expression, e.g. pl.col('1D_ATR|14')",
+    )
+    indicators: List[IndicatorSpec] = Field(
+        default_factory=list, description="Indicator specifications"
+    )
+
+    @field_validator("volatility_indicator", mode="before")
+    @classmethod
+    def validate_volatility_indicator(cls, v: Any) -> Optional[pl.Expr]:
+        """Auto-convert volatility_indicator to pl.Expr"""
+        if v is None:
+            return None
+        return PolarsExprField.deserialize(v)
+
+    @field_serializer("volatility_indicator")
+    def serialize_volatility_indicator(self, expr: Optional[pl.Expr]) -> Optional[dict]:
+        """Serialize volatility_indicator to dict"""
+        if expr is None:
+            return None
+        return PolarsExprField.serialize(expr)
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True  # Allow pl.Expr custom type
+    )

tradepose_models/strategy/blueprint.py

@@ -0,0 +1,55 @@
+"""
+Blueprint Model
+
+Provides the Blueprint class for strategy blueprints with entry/exit triggers.
+"""
+
+from typing import Any, List, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator
+
+from ..enums import TradeDirection, TrendType
+from .trigger import Trigger
+
+
+class Blueprint(BaseModel):
+    """策略藍圖"""
+
+    id: Optional[UUID] = Field(None, description="藍圖 ID（由資料庫自動填充）")
+    name: str = Field(..., description="藍圖名稱")
+    direction: TradeDirection = Field(..., description="方向")
+    trend_type: TrendType = Field(..., description="趨勢類型")
+    entry_first: bool = Field(..., description="是否優先進場")
+    note: str = Field(default="", 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}'. 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}'. Valid values: {', '.join(valid_values)}"
+                )
+        return v

tradepose_models/strategy/config.py

@@ -0,0 +1,142 @@
+"""
+Strategy Configuration Model
+
+Provides the StrategyConfig class for complete strategy configuration.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+from uuid import UUID
+
+import polars as pl
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
+
+from ..enums import Freq
+from ..indicators import PolarsExprField
+from .blueprint import Blueprint
+from .indicator_spec import IndicatorSpec
+
+
+class StrategyConfig(BaseModel):
+    """完整策略配置"""
+
+    id: Optional[UUID] = Field(None, description="策略 ID（由資料庫自動填充）")
+    name: str = Field(..., description="策略名稱")
+    base_instrument: str = Field(..., description="基礎交易標的")
+    base_instrument_id: Optional[int] = Field(
+        None, description="基礎交易標的 ID（由 Gateway 自動填充）"
+    )
+    base_freq: Freq = Field(..., description="基礎頻率")
+    note: str = Field(default="", description="備註")
+
+    volatility_indicator: Optional[pl.Expr] = Field(
+        None,
+        description="波動率欄位表達式，如 pl.col('1D_ATR|14') 或 pl.col('profile').struct.field('shape')",
+    )
+    indicators: List[IndicatorSpec] = Field(default_factory=list, description="指標列表")
+
+    base_blueprint: Blueprint = Field(..., description="基礎藍圖")
+    advanced_blueprints: List[Blueprint] = Field(default_factory=list, description="進階藍圖列表")
+
+    @field_validator("volatility_indicator", mode="before")
+    @classmethod
+    def validate_volatility_indicator(cls, v: Any) -> Optional[pl.Expr]:
+        """自動轉換 volatility_indicator 為 pl.Expr
+
+        支援：
+        - None / null
+        - 字串（如 "1D_ATR|14"）→ 自動轉為 pl.col("1D_ATR|14")
+        - 完整 Expr JSON（如 {"Column": "..."}）
+        """
+        if v is None:
+            return None
+        return PolarsExprField.deserialize(v)
+
+    @field_serializer("volatility_indicator")
+    def serialize_volatility_indicator(self, expr: Optional[pl.Expr]) -> Optional[dict]:
+        """序列化 volatility_indicator 為 dict（與服務器格式一致）"""
+        if expr is None:
+            return None
+        return PolarsExprField.serialize(expr)
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True  # 允許 pl.Expr 這種自定義類型
+    )
+
+    @classmethod
+    def from_api(cls, api_response: Union[Dict[str, Any], str]) -> "StrategyConfig":
+        """從 API 響應創建策略配置
+
+        Args:
+            api_response: API 返回的 JSON 數據（dict 或 JSON 字符串）
+
+        Returns:
+            StrategyConfig 實例，conditions 和 price_expr 自動轉為 pl.Expr
+
+        Example:
+            >>> # 從 JSON 字符串
+            >>> strategy = StrategyConfig.from_api(json_str)
+            >>> # 從 dict
+            >>> strategy = StrategyConfig.from_api(response.json())
+            >>> # 直接使用
+            >>> expr = strategy.base_blueprint.entry_triggers[0].conditions[0]
+            >>> print(type(expr))  # <class 'polars.expr.expr.Expr'>
+        """
+        if isinstance(api_response, str):
+            return cls.model_validate_json(api_response)
+        else:
+            return cls.model_validate(api_response)
+
+    def to_json(self, indent: int = 2) -> str:
+        """序列化為 JSON 字符串
+
+        自動將 pl.Expr 轉為 JSON 字符串格式
+
+        Returns:
+            JSON 字符串，conditions 和 price_expr 已序列化
+        """
+        return self.model_dump_json(indent=indent, exclude_none=True).replace("\n", "")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """轉換為字典（用於發送到 API）
+
+        Returns:
+            字典，pl.Expr 已序列化為 JSON 字符串
+        """
+        return self.model_dump(exclude_none=True)
+
+    def save(self, filepath: str) -> None:
+        """保存到 JSON 文件"""
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(self.to_json())
+        print(f"✅ 策略已保存到: {filepath}")
+
+    @classmethod
+    def load(cls, filepath: str) -> "StrategyConfig":
+        """從 JSON 文件加載"""
+        with open(filepath, "r", encoding="utf-8") as f:
+            return cls.from_api(f.read())
+
+
+def parse_strategy(data: Union[Dict[str, Any], str]) -> StrategyConfig:
+    """解析策略配置（最簡單的方式）
+
+    Args:
+        data: API JSON 數據（dict 或 JSON 字符串）
+
+    Returns:
+        StrategyConfig 實例，可直接訪問 pl.Expr
+
+    Example:
+        >>> import requests
+        >>> # 從 API
+        >>> response = requests.get("http://localhost:8080/api/v1/strategies/txf_1d_sma20_30")
+        >>> strategy = parse_strategy(response.json())
+        >>>
+        >>> # 直接訪問 Polars Expr
+        >>> conditions = strategy.base_blueprint.entry_triggers[0].conditions
+        >>> print(type(conditions[0]))  # <class 'polars.expr.expr.Expr'>
+        >>>
+        >>> # 從 JSON 字符串
+        >>> strategy = parse_strategy(json_str)
+    """
+    return StrategyConfig.from_api(data)

tradepose_models/strategy/entities.py

@@ -0,0 +1,104 @@
+"""
+Strategy Database Entities
+
+Provides StrategyEntity and BlueprintEntity for database operations.
+These models include UUID IDs and timestamp fields for persistence.
+"""
+
+from datetime import datetime
+from typing import Any, List, Optional
+from uuid import UUID
+
+import polars as pl
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
+
+from ..enums import Freq, TradeDirection, TrendType
+from ..indicators import PolarsExprField
+from .indicator_spec import IndicatorSpec
+from .trigger import Trigger
+
+
+class StrategyEntity(BaseModel):
+    """Strategy database entity.
+
+    Represents a strategy stored in the database with UUID ID and metadata.
+    Does not include blueprints (they are stored separately and linked via FK).
+    """
+
+    id: UUID = Field(..., description="Strategy UUID (primary key)")
+    user_id: UUID = Field(..., description="User UUID (owner)")
+    name: str = Field(..., description="Strategy name")
+    base_instrument: str = Field(..., description="Base trading instrument")
+    base_freq: Freq = Field(..., description="Base frequency")
+    note: str = Field(default="", description="Strategy notes")
+
+    volatility_indicator: Optional[pl.Expr] = Field(
+        None,
+        description="Volatility field expression",
+    )
+    indicators: List[IndicatorSpec] = Field(
+        default_factory=list, description="Indicator specifications (list)"
+    )
+
+    is_archived: bool = Field(default=False, description="Whether strategy is archived")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+    @field_validator("volatility_indicator", mode="before")
+    @classmethod
+    def validate_volatility_indicator(cls, v: Any) -> Optional[pl.Expr]:
+        """Auto-convert volatility_indicator to pl.Expr"""
+        if v is None:
+            return None
+        return PolarsExprField.deserialize(v)
+
+    @field_serializer("volatility_indicator")
+    def serialize_volatility_indicator(self, expr: Optional[pl.Expr]) -> Optional[dict]:
+        """Serialize volatility_indicator to dict"""
+        if expr is None:
+            return None
+        return PolarsExprField.serialize(expr)
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True  # Allow pl.Expr custom type
+    )
+
+
+class BlueprintEntity(BaseModel):
+    """Blueprint database entity.
+
+    Represents a blueprint stored in the database with UUID ID and metadata.
+    Linked to a strategy via strategy_id FK.
+    """
+
+    id: UUID = Field(..., description="Blueprint UUID (primary key)")
+    strategy_id: UUID = Field(..., description="Parent strategy UUID (FK)")
+    name: str = Field(..., description="Blueprint name")
+    direction: TradeDirection = Field(..., description="Trade direction")
+    trend_type: TrendType = Field(..., description="Trend type")
+    entry_first: bool = Field(..., description="Whether to prioritize entry")
+    note: str = Field(default="", description="Blueprint notes")
+
+    entry_triggers: List[Trigger] = Field(default_factory=list, description="Entry trigger list")
+    exit_triggers: List[Trigger] = Field(default_factory=list, description="Exit trigger list")
+
+    is_base: bool = Field(default=False, description="Whether this is the base blueprint")
+    is_archived: bool = Field(default=False, description="Whether blueprint is archived")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+    @field_validator("direction", mode="before")
+    @classmethod
+    def convert_direction(cls, v: Any) -> TradeDirection:
+        """Auto-convert string to TradeDirection enum"""
+        if isinstance(v, str):
+            return TradeDirection(v)
+        return v
+
+    @field_validator("trend_type", mode="before")
+    @classmethod
+    def convert_trend_type(cls, v: Any) -> TrendType:
+        """Auto-convert string to TrendType enum"""
+        if isinstance(v, str):
+            return TrendType(v)
+        return v