tradepose-models 1.1.0__py3-none-any.whl

tradepose_models/enums/task_status.py

@@ -0,0 +1,23 @@
+"""
+Task status enumeration for export tasks
+"""
+
+from enum import Enum
+
+
+class TaskStatus(int, Enum):
+    """任務狀態枚舉（與 Worker TaskStatus enum 一致）
+
+    對應 Worker 的 TaskStatus enum，用於追蹤 export 任務的執行狀態
+
+    Rust 對應關係（#[repr(i16)]）:
+    - Rust: TaskStatus::Pending    = 0 → Python: TaskStatus.PENDING    = 0
+    - Rust: TaskStatus::Processing = 1 → Python: TaskStatus.PROCESSING = 1
+    - Rust: TaskStatus::Completed  = 2 → Python: TaskStatus.COMPLETED  = 2
+    - Rust: TaskStatus::Failed     = 3 → Python: TaskStatus.FAILED     = 3
+    """
+
+    PENDING = 0  # 待處理（Gateway 初始狀態）
+    PROCESSING = 1  # 處理中（Worker 開始執行）
+    COMPLETED = 2  # 已完成（Worker 成功完成）
+    FAILED = 3  # 失敗（Worker 執行失敗或超時）

tradepose_models/enums/trade_direction.py

@@ -0,0 +1,42 @@
+"""Trade direction enumeration."""
+
+from enum import Enum
+
+
+class TradeDirection(str, Enum):
+    """Trade direction enum.
+
+    Used to specify the trading direction in Blueprint.
+    String values match Rust's TradeDirection enum.
+
+    Values:
+        LONG: Long trades only (multiplier: 1)
+        SHORT: Short trades only (multiplier: -1)
+        BOTH: Both long and short trades (currently not fully supported)
+    """
+
+    LONG = "Long"
+    SHORT = "Short"
+    BOTH = "Both"
+
+    def to_int(self) -> int:
+        """Convert to integer multiplier (1=Long, -1=Short).
+
+        Matches Rust's direction_multiplier() function.
+        """
+        if self == TradeDirection.LONG:
+            return 1
+        elif self == TradeDirection.SHORT:
+            return -1
+        else:
+            raise ValueError(f"Cannot convert {self} to int multiplier")
+
+    @classmethod
+    def from_int(cls, value: int) -> "TradeDirection":
+        """Create from integer multiplier (1=Long, -1=Short)."""
+        if value == 1:
+            return cls.LONG
+        elif value == -1:
+            return cls.SHORT
+        else:
+            raise ValueError(f"Invalid direction int: {value}. Expected 1 or -1.")

tradepose_models/enums/trend_type.py

@@ -0,0 +1,22 @@
+"""
+Trend type enumeration
+"""
+
+from enum import Enum
+
+
+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_models/enums/weekday.py

@@ -0,0 +1,30 @@
+"""
+Weekday enumeration
+"""
+
+from enum import Enum
+
+
+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"

tradepose_models/enums.py

@@ -0,0 +1,32 @@
+"""Shared enumerations (共用枚舉).
+
+This module contains enum types that are used across multiple packages
+to ensure consistency and type safety.
+
+這個模組包含跨多個包使用的枚舉類型，以確保一致性和類型安全。
+
+Example usage:
+    from tradepose_models.enums import TaskStatus, PlanTier
+
+    # Use in gateway
+    task.status = TaskStatus.PROCESSING
+
+    # Use in client
+    if response.status == TaskStatus.COMPLETED:
+        print("Task finished!")
+"""
+
+
+# Placeholder for shared enums
+# Models will be migrated here from gateway as needed
+# 共用枚舉將根據需要從 gateway 遷移到這裡
+
+# Example structure:
+# class TaskStatus(str, Enum):
+#     """Task execution status."""
+#     PENDING = "pending"
+#     PROCESSING = "processing"
+#     COMPLETED = "completed"
+#     FAILED = "failed"
+
+__all__ = []

tradepose_models/events/__init__.py

@@ -0,0 +1,11 @@
+"""Event models for TradePose trading system.
+
+Contains order event models for the trading decision pipeline.
+"""
+
+from tradepose_models.events.order_events import EntryOrderEvent, ExitOrderEvent
+
+__all__ = [
+    "EntryOrderEvent",
+    "ExitOrderEvent",
+]

tradepose_models/events/order_events.py

@@ -0,0 +1,79 @@
+"""Order Event Models for Trading System.
+
+Provides EntryOrderEvent and ExitOrderEvent for the trading decision pipeline.
+These events are published to Redis Stream for consumption by Trader Service.
+"""
+
+from decimal import Decimal
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from tradepose_models.trading.orders import OrderSide, OrderType
+
+
+class EntryOrderEvent(BaseModel):
+    """Entry order event (進場委託事件).
+
+    Published by TradingDecisionJob when a trade entry signal is detected.
+    Contains all information needed for Trader Service to execute entry order.
+
+    Redis Stream: order:events:{user_id}:{account_id}
+    """
+
+    engagement_id: UUID = Field(..., description="Engagement UUID (FK)")
+    account_id: UUID = Field(..., description="Account UUID for execution")
+    symbol: str = Field(..., description="Trading symbol (mapped via instrument_mapping)")
+    side: OrderSide = Field(..., description="Order side (BUY/SELL)")
+    quantity: Decimal = Field(..., description="Order quantity (lots)")
+    order_type: OrderType = Field(..., description="Order type (MARKET/LIMIT)")
+    entry_price: Decimal = Field(..., description="Entry price (required)")
+    sl_price: Optional[Decimal] = Field(None, description="Stop Loss price (optional)")
+    tp_price: Optional[Decimal] = Field(None, description="Take Profit price (optional)")
+
+    def to_redis_dict(self) -> dict:
+        """Convert to Redis-compatible dict for Stream publishing."""
+        return {
+            "event_type": "entry",
+            "engagement_id": str(self.engagement_id),
+            "account_id": str(self.account_id),
+            "symbol": self.symbol,
+            "side": self.side.value,
+            "quantity": str(self.quantity),
+            "order_type": self.order_type.value,
+            "entry_price": str(self.entry_price),
+            "sl_price": str(self.sl_price) if self.sl_price else "",
+            "tp_price": str(self.tp_price) if self.tp_price else "",
+        }
+
+
+class ExitOrderEvent(BaseModel):
+    """Exit order event (出場委託事件).
+
+    Published by TradingDecisionJob when a trade exit signal is detected.
+    Contains information needed for Trader Service to execute exit order.
+
+    Redis Stream: order:events:{user_id}:{account_id}
+    """
+
+    engagement_id: UUID = Field(..., description="Engagement UUID (FK)")
+    account_id: UUID = Field(..., description="Account UUID for execution")
+    symbol: str = Field(..., description="Trading symbol")
+    side: OrderSide = Field(..., description="Order side (opposite of entry)")
+    quantity: Decimal = Field(..., description="Order quantity (lots)")
+    order_type: OrderType = Field(
+        default=OrderType.MARKET, description="Order type (typically MARKET for exits)"
+    )
+
+    def to_redis_dict(self) -> dict:
+        """Convert to Redis-compatible dict for Stream publishing."""
+        return {
+            "event_type": "exit",
+            "engagement_id": str(self.engagement_id),
+            "account_id": str(self.account_id),
+            "symbol": self.symbol,
+            "side": self.side.value,
+            "quantity": str(self.quantity),
+            "order_type": self.order_type.value,
+        }

tradepose_models/export/__init__.py

@@ -0,0 +1,19 @@
+"""Export API Models.
+
+Provides models for export task management, on-demand OHLCV requests,
+and export API requests/responses.
+"""
+
+from .request import OnDemandOhlcvRequest
+from .requests import ExportRequest, ExportResponse
+from .task_metadata import TaskMetadata, TaskMetadataResponse
+
+__all__ = [
+    # Task models
+    "TaskMetadata",  # Internal: Complete task metadata (Gateway/Worker/Redis)
+    "TaskMetadataResponse",  # Public: API response (excludes internal fields)
+    # Request models
+    "OnDemandOhlcvRequest",
+    "ExportRequest",
+    "ExportResponse",
+]

tradepose_models/export/request.py

@@ -0,0 +1,52 @@
+"""
+Export Request Models
+
+Provides models for on-demand OHLCV export requests.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class OnDemandOhlcvRequest(BaseModel):
+    """On-Demand OHLCV 導出請求（與 Rust OnDemandOhlcvRequest struct 一致）
+
+    特點：
+    - 無需預先註冊策略
+    - 直接指定指標規格即可導出
+    - 適用於快速探索指標、外部數據分析
+
+    Example:
+        >>> from tradepose_models import create_indicator_spec, Indicator, Freq
+        >>>
+        >>> # 定義指標
+        >>> sma_spec = create_indicator_spec(Freq.HOUR_1, Indicator.sma(20), shift=1)
+        >>> atr_spec = create_indicator_spec(Freq.HOUR_1, Indicator.atr(14), shift=1)
+        >>>
+        >>> # 創建請求
+        >>> request = OnDemandOhlcvRequest(
+        ...     base_instrument="TXFR1",
+        ...     base_freq="1min",
+        ...     indicator_specs=[
+        ...         sma_spec.model_dump(exclude_none=True),
+        ...         atr_spec.model_dump(exclude_none=True)
+        ...     ],
+        ...     start_date="2025-01-01T00:00:00",
+        ...     end_date="2025-01-02T23:59:59"
+        ... )
+    """
+
+    base_instrument: str = Field(
+        ..., description="基礎商品 ID (例如 'TXFR1', 'TXF_M1_SHIOAJI_FUTURE')"
+    )
+    base_freq: str = Field(
+        ..., description="基礎頻率 ('1min', '5min', '15min', '1h', '4h', '1D' 等)"
+    )
+    indicator_specs: List[Dict[str, Any]] = Field(
+        ..., description="指標規格列表 (IndicatorSpec JSON 數組)", min_length=1
+    )
+    start_date: Optional[str] = Field(
+        None, description="開始時間 (ISO 8601 格式，例如 '2025-01-01T00:00:00')"
+    )
+    end_date: Optional[str] = Field(None, description="結束時間 (ISO 8601 格式，預設為當前時間)")

tradepose_models/export/requests.py

@@ -0,0 +1,75 @@
+"""Export API request/response models."""
+
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from tradepose_models.enums.export_type import ExportType
+from tradepose_models.enums.persist_mode import PersistMode
+
+
+class ExportRequest(BaseModel):
+    """Worker-compatible export request model.
+
+    This model matches the Gateway's requirements and generates events
+    compatible with Worker's BacktestTaskEvent format.
+
+    Required:
+    - strategy_configs: Complete StrategyConfig objects (self-contained)
+    - export_type: ExportType enum
+
+    Optional (nested in backtest_request):
+    - start_date, end_date, strategy_ids
+    - strategy_name, blueprint_name (for enhanced-ohlcv)
+    - base_instrument, base_freq, indicator_specs (for on-demand-ohlcv)
+    - persist_mode: Where to store results (REDIS or PSQL)
+    """
+
+    # Required: Complete StrategyConfig objects (user must provide)
+    strategy_configs: list[dict] = Field(
+        ..., description="List of complete StrategyConfig objects (JSON)"
+    )
+
+    # Export type (using enum)
+    export_type: ExportType = Field(
+        ...,
+        description="Export type: BACKTEST_RESULTS, LATEST_TRADES, ENHANCED_OHLCV, ON_DEMAND_OHLCV",
+    )
+
+    # Persistence mode (default: REDIS only)
+    persist_mode: PersistMode = Field(
+        default=PersistMode.REDIS,
+        description="Where to persist results: REDIS (default) or PSQL (dual-write to PostgreSQL)",
+    )
+
+    # BacktestRequest fields (nested in worker event)
+    start_date: str | None = Field(default=None, description="Start date ISO 8601 format")
+    end_date: str | None = Field(default=None, description="End date ISO 8601 format")
+    strategy_ids: list[str] | None = Field(
+        default=None, description="Strategy IDs to execute (None = all)"
+    )
+
+    # For EnhancedOhlcv
+    strategy_name: str | None = Field(
+        default=None, description="Strategy name (for enhanced-ohlcv)"
+    )
+    blueprint_name: str | None = Field(
+        default=None, description="Blueprint name (for enhanced-ohlcv)"
+    )
+
+    # For OnDemandOhlcv
+    base_instrument: str | None = Field(
+        default=None, description="Instrument ID for on-demand OHLCV"
+    )
+    base_freq: str | None = Field(default=None, description="Base frequency for on-demand OHLCV")
+    indicator_specs: list[dict] | None = Field(
+        default=None, description="Indicator specifications for on-demand OHLCV"
+    )
+
+
+class ExportResponse(BaseModel):
+    """Response model for export task creation."""
+
+    task_id: UUID
+    message: str
+    operation_type: str

tradepose_models/export/task_metadata.py

@@ -0,0 +1,97 @@
+"""
+Task Metadata Models
+
+Provides two models for task metadata:
+- TaskMetadata: Internal complete model (Gateway/Worker/Redis)
+- TaskStatusResponse: Public API response (excludes internal fields)
+"""
+
+from datetime import datetime
+from typing import List, Optional
+from uuid import UUID
+
+from pydantic import Field
+
+from ..base import BaseModel
+from ..enums import ExportType, TaskStatus
+
+
+class TaskMetadata(BaseModel):
+    """
+    Internal task metadata model (complete with all fields).
+
+    This model is used for:
+    1. Gateway creation - Initial task metadata
+    2. Redis storage - Stored as JSON STRING
+    3. Worker updates - Worker modifies status, timing, results
+    4. Internal communication - Full context for backend
+
+    For API responses, use TaskStatusResponse instead.
+    """
+
+    # Core identification
+    task_id: UUID = Field(..., description="Task UUID")
+    user_id: UUID = Field(description="User UUID (internal only, not included in API responses)")
+
+    # Task status
+    status: TaskStatus = Field(
+        default=TaskStatus.PENDING,
+        description="Current task status (0=pending, 1=processing, 2=completed, 3=failed)",
+    )
+
+    # Operation info
+    export_type: ExportType = Field(
+        description="Export type (0=BACKTEST_RESULTS, 1=LATEST_TRADES, 2=ENHANCED_OHLCV, 3=ON_DEMAND_OHLCV)"
+    )
+
+    # Timing (TIMESTAMPTZ in PostgreSQL, datetime in Python, ISO 8601 in JSON)
+    created_at: datetime = Field(..., description="Task creation timestamp")
+    started_at: Optional[datetime] = Field(None, description="Processing start timestamp")
+    completed_at: Optional[datetime] = Field(None, description="Processing completion timestamp")
+
+    # Worker info
+    worker_id: Optional[str] = Field(None, description="Worker ID that processed this task")
+
+    # Strategy execution info
+    executed_strategies: List[str] = Field(
+        default_factory=list, description="List of strategy names that were executed"
+    )
+    strategy_counts: int = Field(
+        default=0, description="Number of strategies (Gateway sets, Worker may update)"
+    )
+    blueprint_counts: int = Field(default=0, description="Number of blueprints processed")
+    indicator_counts: int = Field(default=0, description="Number of indicators used")
+    trigger_counts: int = Field(default=0, description="Number of triggers used")
+    input_rows: int = Field(default=0, description="Number of input rows processed")
+
+    # Error handling
+    error_message: Optional[str] = Field(None, description="Error message if task failed")
+
+
+class TaskMetadataResponse(TaskMetadata):
+    """
+    Public API response model for task metadata.
+
+    Inherits from TaskMetadata but excludes internal-only fields.
+    This model is returned by GET /api/v1/tasks/{task_id} endpoint.
+
+    Excluded fields:
+    - executed_strategies: Internal execution details
+    - error_message: Internal error tracking
+    """
+
+    def model_dump(self, **kwargs):
+        """Override to exclude internal-only fields from serialization."""
+        data = super().model_dump(**kwargs)
+        data.pop("executed_strategies", None)
+        # data.pop("error_message", None)
+        return data
+
+    def model_dump_json(self, **kwargs):
+        """Override JSON serialization to exclude internal-only fields."""
+        exclude = kwargs.get("exclude", set())
+        if isinstance(exclude, set):
+            exclude.add("executed_strategies")
+            # exclude.add("error_message")
+        kwargs["exclude"] = exclude
+        return super().model_dump_json(**kwargs)

tradepose_models/gateway/__init__.py

@@ -0,0 +1,19 @@
+"""Gateway API Response Models.
+
+This module contains common response models used by gateway endpoints
+for operations that return simple success/status messages.
+"""
+
+from .responses import (
+    CancelSubscriptionResponse,
+    OperationResponse,
+    StrategyOperationResponse,
+    WebhookResponse,
+)
+
+__all__ = [
+    "OperationResponse",
+    "StrategyOperationResponse",
+    "CancelSubscriptionResponse",
+    "WebhookResponse",
+]

tradepose_models/gateway/responses.py

@@ -0,0 +1,37 @@
+"""Gateway API Response Models."""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class OperationResponse(BaseModel):
+    """Generic operation response with task ID."""
+
+    task_id: str = Field(..., description="Task ID for polling status")
+    message: str = Field(..., description="Human-readable message")
+
+
+class StrategyOperationResponse(BaseModel):
+    """Response for strategy operations (delete, get detail)."""
+
+    task_id: str = Field(..., description="Task ID for polling status")
+    message: str = Field(..., description="Operation status message")
+
+
+class CancelSubscriptionResponse(BaseModel):
+    """Response for subscription cancellation."""
+
+    message: str = Field(..., description="Cancellation status message")
+    status: str = Field(..., description="Updated subscription status")
+    current_period_end: Optional[datetime] = Field(
+        None, description="End of current billing period"
+    )
+
+
+class WebhookResponse(BaseModel):
+    """Response for webhook processing."""
+
+    status: str = Field(..., description="Processing status (success/error)")
+    event: str = Field(..., description="Event type that was processed")

tradepose_models/indicators/__init__.py

@@ -0,0 +1,56 @@
+"""
+Indicator Pydantic Models for Strong Typing
+
+Provides strongly-typed indicator models aligned with Rust backend.
+"""
+
+from .base import PolarsExprField
+from .factory import Indicator
+from .market_profile import (
+    AtrQuantileConfig,
+    MarketProfileIndicator,
+    ProfileShape,
+    ProfileShapeConfig,
+    create_daily_anchor,
+    create_profile_shape_config,
+    create_weekly_anchor,
+)
+from .momentum import CCIIndicator, RSIIndicator, StochasticIndicator
+from .moving_average import EMAIndicator, SMAIndicator, SMMAIndicator, WMAIndicator
+from .other import BollingerBandsIndicator, RawOhlcvIndicator
+from .trend import ADXIndicator, MACDIndicator, SuperTrendIndicator
+from .volatility import ATRIndicator, ATRQuantileIndicator
+
+__all__ = [
+    # Base
+    "PolarsExprField",
+    # Moving Average
+    "SMAIndicator",
+    "EMAIndicator",
+    "SMMAIndicator",
+    "WMAIndicator",
+    # Volatility
+    "ATRIndicator",
+    "ATRQuantileIndicator",
+    # Trend
+    "SuperTrendIndicator",
+    "MACDIndicator",
+    "ADXIndicator",
+    # Momentum
+    "RSIIndicator",
+    "CCIIndicator",
+    "StochasticIndicator",
+    # Other
+    "BollingerBandsIndicator",
+    "RawOhlcvIndicator",
+    # Market Profile
+    "MarketProfileIndicator",
+    "AtrQuantileConfig",
+    "ProfileShape",
+    "ProfileShapeConfig",
+    "create_daily_anchor",
+    "create_weekly_anchor",
+    "create_profile_shape_config",
+    # Factory
+    "Indicator",
+]

tradepose_models/indicators/base.py

@@ -0,0 +1,42 @@
+"""
+Base utilities for indicator models
+
+Provides Polars Expr field handling for strategy models.
+"""
+
+import json
+from io import StringIO
+from typing import Union
+
+import polars as pl
+
+
+class PolarsExprField:
+    """自定義 Polars Expr 字段處理"""
+
+    @staticmethod
+    def serialize(expr: pl.Expr) -> dict:
+        """序列化 Polars Expr 為 dict（與服務器格式一致）
+
+        Python Polars 1.33+ 的 expr.meta.serialize() 已輸出與 Rust Polars 0.51 兼容的格式：
+        - Window variant (not Over)
+        - options: {"Over": "GroupsToRows"} (correct WindowType format)
+        """
+        json_str = expr.meta.serialize(format="json")
+        return json.loads(json_str)
+
+    @staticmethod
+    def deserialize(data: Union[str, dict, pl.Expr]) -> pl.Expr:
+        """反序列化為 Polars Expr"""
+        if isinstance(data, pl.Expr):
+            # 已經是 Expr 對象
+            return data
+        elif isinstance(data, dict):
+            # API 返回的 dict（優先處理）
+            json_str = json.dumps(data)
+            return pl.Expr.deserialize(StringIO(json_str), format="json")
+        elif isinstance(data, str):
+            # JSON 字符串（向後兼容）
+            return pl.Expr.deserialize(StringIO(data), format="json")
+        else:
+            raise ValueError(f"無法反序列化類型: {type(data)}")