tradepose-models 1.1.0__py3-none-any.whl

tradepose_models/trading/engagement.py

@@ -0,0 +1,160 @@
+"""
+Engagement Model (Issue #305, #320)
+
+Provides the Engagement model for trade execution context.
+Tracks the lifecycle of a trade from signal to completion.
+
+8-Phase lifecycle:
+    PENDING(0) → ENTERING(1) → HOLDING(2) → EXITING(3) → CLOSED(4)
+                     │                           │
+                     ▼                           ▼
+                 FAILED(5)                 EXIT_FAILED(7)
+
+    CANCELLED(6) - Signal cancelled before execution
+"""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from ..enums import EngagementPhase, TradeDirection
+
+
+class Engagement(BaseModel):
+    """Trade execution context (Engagement).
+
+    Represents the binding between a trade signal and its execution.
+    One engagement can generate multiple orders (entry, SL, TP, exit).
+
+    Unique constraint: (user_id, account_id, binding_id, portfolio_id, blueprint_id, trade_id)
+    """
+
+    id: UUID = Field(..., description="Engagement UUID (primary key)")
+    user_id: UUID = Field(..., description="User UUID")
+    account_id: UUID = Field(..., description="Trading account UUID")
+    binding_id: UUID = Field(..., description="Account-Portfolio binding UUID")
+    portfolio_id: UUID = Field(..., description="Portfolio UUID")
+    blueprint_id: UUID = Field(..., description="Blueprint UUID")
+    trade_id: UUID = Field(..., description="Trade UUID (FK to trades)")
+
+    # FK fields for direct lookup
+    strategy_id: Optional[UUID] = Field(None, description="Strategy UUID")
+    portfolio_allocation_id: Optional[UUID] = Field(None, description="Portfolio allocation UUID")
+
+    # Phase system (8 states) - Issue #305
+    phase: EngagementPhase = Field(
+        default=EngagementPhase.PENDING,
+        description="Engagement phase (0-7): PENDING, ENTERING, HOLDING, EXITING, CLOSED, FAILED, CANCELLED, EXIT_FAILED",
+    )
+
+    # Latest tracking
+    is_latest: bool = Field(
+        default=True,
+        description="True if this is the most recent engagement for this trade context",
+    )
+
+    # Position sizing (MAE-based calculation)
+    target_quantity: Optional[Decimal] = Field(
+        None,
+        description="Calculated position size based on MAE formula",
+    )
+
+    # Trade direction and prices
+    direction: Optional[TradeDirection] = Field(
+        None,
+        description="Trade direction: Long or Short",
+    )
+    entry_price: Optional[Decimal] = Field(
+        None,
+        description="Target entry price from trade signal",
+    )
+    sl_price: Optional[Decimal] = Field(
+        None,
+        description="Stop loss price from trade signal",
+    )
+    tp_price: Optional[Decimal] = Field(
+        None,
+        description="Take profit price from trade signal",
+    )
+
+    # Fill tracking
+    filled_entry_qty: Decimal = Field(
+        default=Decimal("0"),
+        description="Quantity filled for entry order",
+    )
+    filled_exit_qty: Decimal = Field(
+        default=Decimal("0"),
+        description="Quantity filled for exit order",
+    )
+
+    # Trading instrument (may differ from signal instrument)
+    trading_instrument_id: Optional[int] = Field(
+        None,
+        description="Trading instrument ID (FK to data.instruments)",
+    )
+    symbol: Optional[str] = Field(
+        None,
+        description="Trading symbol for the mapped instrument",
+    )
+
+    # Timestamps
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+    # Phase helper properties
+    @property
+    def is_pending_phase(self) -> bool:
+        """Check if engagement is in PENDING phase."""
+        return self.phase == EngagementPhase.PENDING
+
+    @property
+    def is_entering_phase(self) -> bool:
+        """Check if engagement is in ENTERING phase."""
+        return self.phase == EngagementPhase.ENTERING
+
+    @property
+    def is_holding_phase(self) -> bool:
+        """Check if engagement is in HOLDING phase (position open)."""
+        return self.phase == EngagementPhase.HOLDING
+
+    @property
+    def is_exiting_phase(self) -> bool:
+        """Check if engagement is in EXITING phase."""
+        return self.phase == EngagementPhase.EXITING
+
+    @property
+    def is_closed_phase(self) -> bool:
+        """Check if engagement is in CLOSED phase."""
+        return self.phase == EngagementPhase.CLOSED
+
+    @property
+    def is_failed_phase(self) -> bool:
+        """Check if engagement is in FAILED phase."""
+        return self.phase == EngagementPhase.FAILED
+
+    @property
+    def is_cancelled_phase(self) -> bool:
+        """Check if engagement is in CANCELLED phase."""
+        return self.phase == EngagementPhase.CANCELLED
+
+    @property
+    def is_exit_failed_phase(self) -> bool:
+        """Check if engagement is in EXIT_FAILED phase."""
+        return self.phase == EngagementPhase.EXIT_FAILED
+
+    @property
+    def is_terminal(self) -> bool:
+        """Check if engagement is in a terminal state (no more transitions)."""
+        return self.phase in (
+            EngagementPhase.CLOSED,
+            EngagementPhase.FAILED,
+            EngagementPhase.CANCELLED,
+        )
+
+    @property
+    def needs_intervention(self) -> bool:
+        """Check if engagement needs manual intervention."""
+        return self.phase == EngagementPhase.EXIT_FAILED

tradepose_models/trading/orderbook.py

@@ -0,0 +1,73 @@
+"""
+Orderbook Model
+
+Provides the OrderbookEntry model for event sourcing of order lifecycle.
+Each event in the order lifecycle is recorded as a separate entry.
+"""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from ..enums import OrderbookEventType
+from .orders import OrderSide, OrderStatus, OrderType
+
+
+class OrderbookEntry(BaseModel):
+    """Orderbook event entry (Event Sourcing).
+
+    Records each event in the order lifecycle for audit and tracking.
+    Each order state change creates a new entry (immutable log).
+
+    Event Types:
+    - ORDER_CREATED (0): Order submitted to broker
+    - ORDER_MODIFIED (1): Order modified (price, quantity)
+    - ORDER_CANCELLED (2): Order cancelled
+    - PARTIAL_FILL (3): Order partially filled
+    - FULLY_FILLED (4): Order fully filled
+    - REJECTED (5): Order rejected by broker
+    """
+
+    id: UUID = Field(..., description="Entry UUID (primary key)")
+    user_id: UUID = Field(..., description="User UUID")
+    engagement_id: UUID = Field(..., description="Engagement UUID (FK)")
+
+    event_type: OrderbookEventType = Field(..., description="Event type (SMALLINT: 0-5)")
+    raw_data: dict = Field(default_factory=dict, description="Broker raw response (JSONB)")
+
+    # Order details
+    symbol: str = Field(..., description="Trading symbol")
+    side: OrderSide = Field(..., description="Order side (BUY/SELL)")
+    order_type: OrderType = Field(..., description="Order type")
+    quantity: Decimal = Field(..., description="Order quantity")
+    filled_quantity: Decimal = Field(
+        default=Decimal("0"), description="Filled quantity (for partial fills)"
+    )
+    price: Optional[Decimal] = Field(None, description="Order price (for limit orders)")
+    filled_price: Optional[Decimal] = Field(None, description="Average filled price")
+
+    # Broker tracking
+    broker_order_id: str = Field(..., description="Broker's order ID")
+    status: OrderStatus = Field(..., description="Order status")
+
+    # Timestamps
+    created_at: datetime = Field(..., description="Event timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+    @property
+    def is_filled(self) -> bool:
+        """Check if order is fully filled."""
+        return self.event_type == OrderbookEventType.FULLY_FILLED
+
+    @property
+    def is_partial(self) -> bool:
+        """Check if order is partially filled."""
+        return self.event_type == OrderbookEventType.PARTIAL_FILL
+
+    @property
+    def remaining_quantity(self) -> Decimal:
+        """Calculate remaining quantity."""
+        return self.quantity - self.filled_quantity

tradepose_models/trading/orders.py

@@ -0,0 +1,137 @@
+"""Order models for unified trading interface."""
+
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+# Import OrderStrategy from existing enums module
+from tradepose_models.enums.order_strategy import OrderStrategy
+
+
+class OrderSide(str, Enum):
+    """Order side."""
+
+    BUY = "buy"
+    SELL = "sell"
+
+
+class OrderType(str, Enum):
+    """Order types."""
+
+    MARKET = "market"
+    LIMIT = "limit"
+    STOP_MARKET = "stop_market"
+    STOP_LIMIT = "stop_limit"
+    TAKE_PROFIT_MARKET = "take_profit_market"
+    TAKE_PROFIT_LIMIT = "take_profit_limit"
+
+
+class OrderStatus(str, Enum):
+    """Order status."""
+
+    PENDING_NEW = "pending_new"
+    NEW = "new"
+    PARTIALLY_FILLED = "partially_filled"
+    FILLED = "filled"
+    CANCELLED = "cancelled"
+    REJECTED = "rejected"
+    EXPIRED = "expired"
+
+
+class TimeInForce(str, Enum):
+    """Time in force."""
+
+    GTC = "gtc"  # Good Till Cancel
+    IOC = "ioc"  # Immediate or Cancel
+    FOK = "fok"  # Fill or Kill
+
+
+class OrderSubmitRequest(BaseModel):
+    """Unified order submission request."""
+
+    user_id: UUID
+    account_id: UUID
+    symbol: str = Field(..., description="Unified symbol (e.g., BTC-USDT)")
+    side: OrderSide
+    order_type: OrderType
+    quantity: Decimal
+    price: Optional[Decimal] = None
+    stop_price: Optional[Decimal] = None
+    time_in_force: TimeInForce = TimeInForce.GTC
+    client_order_id: Optional[str] = None
+    reduce_only: bool = False
+
+    # Trade/Portfolio context
+    snapshot_price: Optional[Decimal] = Field(None, description="Market price at submission")
+    trade_id: Optional[str] = Field(None, description="Backtest trade ID")
+    portfolio_id: Optional[str] = Field(None, description="Portfolio ID")
+    order_strategy: Optional[OrderStrategy] = Field(None, description="Execution strategy")
+
+    extra_params: dict = Field(default_factory=dict)
+
+
+class Order(BaseModel):
+    """Unified order model."""
+
+    order_id: str
+    client_order_id: Optional[str]
+    user_id: UUID
+    account_id: UUID
+    broker: str
+    symbol: str = Field(..., description="Unified symbol")
+    broker_symbol: str = Field(..., description="Broker-specific symbol")
+    side: OrderSide
+    order_type: OrderType
+    quantity: Decimal
+    price: Optional[Decimal]
+    stop_price: Optional[Decimal]
+    filled_quantity: Decimal
+    remaining_quantity: Decimal
+    average_fill_price: Optional[Decimal]
+    status: OrderStatus
+    time_in_force: TimeInForce
+    created_at: datetime
+    updated_at: datetime
+    commission: Optional[Decimal] = None
+    commission_asset: Optional[str] = None
+
+    # Trade/Portfolio tracking
+    trade_id: Optional[str] = None
+    portfolio_id: Optional[str] = None
+    order_strategy: Optional[OrderStrategy] = None
+
+    raw_data: Optional[dict] = None  # Broker's raw response
+
+
+class ExecutionReport(BaseModel):
+    """Unified execution report (fill notification)."""
+
+    execution_id: str
+    order_id: str
+    client_order_id: Optional[str]
+    user_id: UUID
+    account_id: UUID
+    broker: str
+    symbol: str
+    broker_symbol: str
+    side: OrderSide
+    last_filled_quantity: Decimal
+    last_filled_price: Optional[Decimal]
+    cumulative_filled_quantity: Decimal
+    remaining_quantity: Decimal
+    order_status: OrderStatus
+    commission: Decimal
+    commission_asset: str
+    transact_time: datetime
+    received_at: datetime
+
+    # Trade/Portfolio tracking
+    trade_id: Optional[str] = None
+    portfolio_id: Optional[str] = None
+    order_strategy: Optional[OrderStrategy] = None
+
+    raw_data: Optional[dict] = None

tradepose_models/trading/positions.py

@@ -0,0 +1,78 @@
+"""Position models."""
+
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class PositionSide(str, Enum):
+    """Position side."""
+
+    LONG = "long"
+    SHORT = "short"
+
+
+class Position(BaseModel):
+    """Unified position model."""
+
+    # Core fields (required)
+    symbol: str  # Unified symbol
+    broker_symbol: str  # Broker-specific symbol
+    side: PositionSide
+    quantity: Decimal
+    entry_price: Decimal  # Average cost
+    current_price: Decimal
+    unrealized_pnl: Decimal
+
+    # With defaults (was required, now has sensible defaults)
+    realized_pnl: Decimal = Decimal(0)
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+    # Existing optional fields
+    margin_used: Optional[Decimal] = None
+    leverage: Optional[Decimal] = None
+    raw_data: Optional[dict] = None
+
+    # Broker-specific identifiers (optional)
+    position_id: Optional[str] = None
+    user_id: Optional[UUID] = None
+    account_id: Optional[UUID] = None
+    broker: Optional[str] = None
+    opened_at: Optional[datetime] = None
+
+    # Risk management (optional)
+    stop_loss: Optional[Decimal] = None
+    take_profit: Optional[Decimal] = None
+
+    # MT5-specific (optional)
+    swap: Optional[Decimal] = None
+    magic: Optional[int] = None
+    comment: Optional[str] = None
+
+
+class ClosedPosition(BaseModel):
+    """Closed position (historical)."""
+
+    # Required fields
+    symbol: str
+    side: PositionSide
+    quantity: Decimal
+    entry_price: Decimal
+    exit_price: Decimal
+    realized_pnl: Decimal
+    commission: Decimal
+    opened_at: datetime
+    closed_at: datetime
+
+    # Broker-specific (optional)
+    position_id: Optional[str] = None
+    user_id: Optional[UUID] = None
+    account_id: Optional[UUID] = None
+    broker: Optional[str] = None
+    broker_symbol: Optional[str] = None
+    swap: Optional[Decimal] = None

tradepose_models/trading/trader_commands.py

@@ -0,0 +1,138 @@
+"""Trader command models for Redis Stream communication (Issue #307, #320).
+
+Pydantic models for trader commands published to Redis Streams:
+- ExecuteOrderCommand: Open a new position
+- CancelOrderCommand: Cancel an existing order
+- ModifyOrderCommand: Modify SL/TP on existing order
+- SyncBrokerStatusCommand: Request broker status sync
+
+Stream pattern: trader:commands:{user_id}:{node_seq}:{slot_idx}
+"""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Literal, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from tradepose_models.enums import TradeDirection
+
+
+class BaseTraderCommand(BaseModel):
+    """Base class for all trader commands."""
+
+    timestamp: datetime = Field(
+        ...,
+        description="Command creation timestamp (UTC)",
+    )
+
+
+class ExecuteOrderCommand(BaseTraderCommand):
+    """Command to execute a new order.
+
+    Published when an engagement is created and ready for execution.
+    Contains all information needed to place entry order with SL/TP.
+    """
+
+    command_type: Literal["execute_order"] = Field(
+        default="execute_order",
+        description="Command type identifier",
+    )
+    engagement_id: UUID = Field(
+        ...,
+        description="Engagement UUID for tracking",
+    )
+    account_id: UUID = Field(
+        ...,
+        description="Trading account UUID",
+    )
+    symbol: str = Field(
+        ...,
+        description="Trading symbol (e.g., XAUUSD, MNQ)",
+    )
+    direction: TradeDirection = Field(
+        ...,
+        description="Trade direction: Long or Short",
+    )
+    quantity: Decimal = Field(
+        ...,
+        gt=0,
+        description="Order quantity (lots)",
+    )
+    entry_price: Decimal = Field(
+        ...,
+        gt=0,
+        description="Target entry price",
+    )
+    sl_price: Optional[Decimal] = Field(
+        None,
+        description="Stop loss price (optional)",
+    )
+    tp_price: Optional[Decimal] = Field(
+        None,
+        description="Take profit price (optional)",
+    )
+
+
+class CancelOrderCommand(BaseTraderCommand):
+    """Command to cancel an existing order."""
+
+    command_type: Literal["cancel_order"] = Field(
+        default="cancel_order",
+        description="Command type identifier",
+    )
+    engagement_id: UUID = Field(
+        ...,
+        description="Engagement UUID for tracking",
+    )
+    account_id: UUID = Field(
+        ...,
+        description="Trading account UUID",
+    )
+    broker_order_id: Optional[str] = Field(
+        None,
+        description="Broker's order ID to cancel (if known)",
+    )
+
+
+class ModifyOrderCommand(BaseTraderCommand):
+    """Command to modify an existing order's SL/TP."""
+
+    command_type: Literal["modify_order"] = Field(
+        default="modify_order",
+        description="Command type identifier",
+    )
+    engagement_id: UUID = Field(
+        ...,
+        description="Engagement UUID for tracking",
+    )
+    account_id: UUID = Field(
+        ...,
+        description="Trading account UUID",
+    )
+    broker_order_id: str = Field(
+        ...,
+        description="Broker's order ID to modify",
+    )
+    new_sl_price: Optional[Decimal] = Field(
+        None,
+        description="New stop loss price",
+    )
+    new_tp_price: Optional[Decimal] = Field(
+        None,
+        description="New take profit price",
+    )
+
+
+class SyncBrokerStatusCommand(BaseTraderCommand):
+    """Command to request broker status synchronization."""
+
+    command_type: Literal["sync_broker_status"] = Field(
+        default="sync_broker_status",
+        description="Command type identifier",
+    )
+    account_id: UUID = Field(
+        ...,
+        description="Trading account UUID to sync",
+    )

tradepose_models/trading/trades_execution.py

@@ -0,0 +1,27 @@
+"""Trade execution record models."""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+from tradepose_models.trading.orders import OrderSide
+
+
+class TradeExecution(BaseModel):
+    """Trade execution record (actual fill)."""
+
+    trade_id: str
+    order_id: str
+    client_order_id: Optional[str]
+    symbol: str
+    broker_symbol: str
+    side: OrderSide
+    price: Decimal
+    quantity: Decimal
+    commission: Decimal
+    commission_asset: str
+    commission_type: Literal["maker", "taker", "fixed"]
+    timestamp: datetime
+    raw_data: Optional[dict] = None

tradepose_models/types.py

@@ -0,0 +1,35 @@
+"""Common type definitions (通用類型定義).
+
+This module contains type aliases and custom types used across the platform
+to improve code clarity and type safety.
+
+這個模組包含平台上使用的類型別名和自定義類型，以提高代碼清晰度和類型安全性。
+
+Example usage:
+    from tradepose_models.types import UserId, APIKeyHash, Timestamp
+
+    def get_user(user_id: UserId) -> dict:
+        # Type hints make the code more readable
+        return {"id": user_id}
+
+    def verify_key(key_hash: APIKeyHash) -> bool:
+        # Custom types document intent
+        return check_hash(key_hash)
+"""
+
+
+# Placeholder for shared type definitions
+# Types will be added here as needed
+# 共用類型定義將根據需要添加到這裡
+
+# Example structure:
+# UserId = NewType('UserId', str)
+# """User identifier type (用戶標識符類型)."""
+#
+# APIKeyHash = NewType('APIKeyHash', str)
+# """Hashed API key type (API 密鑰哈希類型)."""
+#
+# Timestamp = NewType('Timestamp', datetime)
+# """Timestamp type for consistency (時間戳類型以保持一致性)."""
+
+__all__ = []

tradepose_models/utils/__init__.py

@@ -0,0 +1,13 @@
+"""Utility modules for TradePose models."""
+
+from .rate_converter import (
+    DEFAULT_RATES,
+    RateConverter,
+    get_default_converter,
+)
+
+__all__ = [
+    "DEFAULT_RATES",
+    "RateConverter",
+    "get_default_converter",
+]