tradepose-models 1.1.0__py3-none-any.whl

tradepose_models/indicators/momentum.py

@@ -0,0 +1,53 @@
+"""
+Momentum Indicator Models
+
+RSI, CCI, and Stochastic indicators aligned with Rust backend.
+"""
+
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class RSIIndicator(BaseModel):
+    """Relative Strength Index (RSI) 指标
+
+    对应 Rust: Indicator::RSI { period, column }
+
+    Returns:
+        单一数值字段（0-100 范围）
+    """
+
+    type: Literal["RSI"] = "RSI"
+    period: int = Field(default=14, gt=0, le=100)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+
+
+class CCIIndicator(BaseModel):
+    """Commodity Channel Index (CCI) 指标
+
+    对应 Rust: Indicator::CCI { period }
+
+    Returns:
+        单一数值字段
+    """
+
+    type: Literal["CCI"] = "CCI"
+    period: int = Field(default=20, gt=0, le=100)
+
+
+class StochasticIndicator(BaseModel):
+    """Stochastic Oscillator 指标
+
+    对应 Rust: Indicator::Stochastic { k_period, d_period, fields }
+
+    Returns:
+        Struct { k: f64, d: f64 }
+    """
+
+    type: Literal["Stochastic"] = "Stochastic"
+    k_period: int = Field(default=14, gt=0, le=100, description="%K period")
+    d_period: int = Field(default=3, gt=0, le=50, description="%D period (smoothing)")
+    fields: Optional[List[str]] = Field(
+        default=None, description="Select specific fields: ['k', 'd']"
+    )

tradepose_models/indicators/moving_average.py

@@ -0,0 +1,63 @@
+"""
+Moving Average Indicator Models
+
+SMA, EMA, SMMA, WMA indicators aligned with Rust backend.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class SMAIndicator(BaseModel):
+    """Simple Moving Average (SMA) 指标
+
+    对应 Rust: Indicator::SMA { period, column }
+
+    Args:
+        period: 计算周期（必须 > 0）
+        column: 计算列名（默认 "close"）
+
+    Example:
+        >>> sma = SMAIndicator(period=20)
+        >>> sma = SMAIndicator(period=50, column="high")
+    """
+
+    type: Literal["SMA"] = "SMA"
+    period: int = Field(gt=0, le=500, description="Period must be > 0 and <= 500")
+    column: str = Field(
+        default="close", pattern="^(open|high|low|close|volume)$", description="OHLCV column name"
+    )
+
+
+class EMAIndicator(BaseModel):
+    """Exponential Moving Average (EMA) 指标
+
+    对应 Rust: Indicator::EMA { period, column }
+    """
+
+    type: Literal["EMA"] = "EMA"
+    period: int = Field(gt=0, le=500)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+
+
+class SMMAIndicator(BaseModel):
+    """Smoothed Moving Average (SMMA) 指标
+
+    对应 Rust: Indicator::SMMA { period, column }
+    """
+
+    type: Literal["SMMA"] = "SMMA"
+    period: int = Field(gt=0, le=500)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+
+
+class WMAIndicator(BaseModel):
+    """Weighted Moving Average (WMA) 指标
+
+    对应 Rust: Indicator::WMA { period, column }
+    """
+
+    type: Literal["WMA"] = "WMA"
+    period: int = Field(gt=0, le=500)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")

tradepose_models/indicators/other.py

@@ -0,0 +1,40 @@
+"""
+Other Indicator Models
+
+Bollinger Bands and RawOhlcv indicators aligned with Rust backend.
+"""
+
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class BollingerBandsIndicator(BaseModel):
+    """Bollinger Bands 指标
+
+    对应 Rust: Indicator::BollingerBands { period, num_std, column, fields }
+
+    Returns:
+        Struct { upper: f64, middle: f64, lower: f64, bandwidth: f64 }
+    """
+
+    type: Literal["BollingerBands"] = "BollingerBands"
+    period: int = Field(default=20, gt=0, le=200)
+    num_std: float = Field(default=2.0, gt=0, le=5.0, description="Standard deviation multiplier")
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+    fields: Optional[List[str]] = Field(
+        default=None,
+        description="Select specific fields: ['upper', 'middle', 'lower', 'bandwidth']",
+    )
+
+
+class RawOhlcvIndicator(BaseModel):
+    """Raw OHLCV Column 指标
+
+    对应 Rust: Indicator::RawOhlcv { column }
+
+    直接引用 OHLCV 列，用于需要原始数据的场景。
+    """
+
+    type: Literal["RawOhlcv"] = "RawOhlcv"
+    column: str = Field(pattern="^(open|high|low|close|volume)$")

tradepose_models/indicators/trend.py

@@ -0,0 +1,80 @@
+"""
+Trend Indicator Models
+
+SuperTrend, MACD, and ADX indicators aligned with Rust backend.
+"""
+
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class SuperTrendIndicator(BaseModel):
+    """SuperTrend 指标
+
+    对应 Rust: Indicator::SuperTrend { multiplier, volatility_column, high, low, close }
+
+    Args:
+        multiplier: ATR 倍数（通常 2.0-3.0）
+        volatility_column: 引用的波动率列名（如 "ATR|14"，注意是列名不是 struct 字段）
+        high: 高价列名（默认 "high"）
+        low: 低价列名（默认 "low"）
+        close: 收盘价列名（默认 "close"）
+
+    Returns:
+        Struct { direction: i32, value: f64, trend: f64, ...}
+
+    Example:
+        >>> st = SuperTrendIndicator(
+        ...     multiplier=3.0,
+        ...     volatility_column="ATR|21"
+        ... )
+    """
+
+    type: Literal["SuperTrend"] = "SuperTrend"
+    multiplier: float = Field(gt=0, le=10, description="ATR multiplier (typically 2.0-3.0)")
+    volatility_column: str = Field(
+        min_length=1, description="Reference to volatility column (e.g., 'ATR|14')"
+    )
+    high: str = Field(default="high", pattern="^(high|open|low|close)$")
+    low: str = Field(default="low", pattern="^(high|open|low|close)$")
+    close: str = Field(default="close", pattern="^(high|open|low|close)$")
+    fields: Optional[List[str]] = Field(
+        default=None,
+        description="Select specific fields: ['direction', 'supertrend', 'long', 'short']",
+    )
+
+
+class MACDIndicator(BaseModel):
+    """Moving Average Convergence Divergence (MACD) 指标
+
+    对应 Rust: Indicator::MACD { fast_period, slow_period, signal_period, column, fields }
+
+    Returns:
+        Struct { macd: f64, signal: f64, histogram: f64 }
+    """
+
+    type: Literal["MACD"] = "MACD"
+    fast_period: int = Field(default=12, gt=0, le=100)
+    slow_period: int = Field(default=26, gt=0, le=200)
+    signal_period: int = Field(default=9, gt=0, le=50)
+    column: str = Field(default="close", pattern="^(open|high|low|close|volume)$")
+    fields: Optional[List[str]] = Field(
+        default=None, description="Select specific fields: ['macd', 'signal', 'histogram']"
+    )
+
+
+class ADXIndicator(BaseModel):
+    """Average Directional Index (ADX) 指标
+
+    对应 Rust: Indicator::ADX { period, fields }
+
+    Returns:
+        Struct { adx: f64, plus_di: f64, minus_di: f64 }
+    """
+
+    type: Literal["ADX"] = "ADX"
+    period: int = Field(default=14, gt=0, le=100)
+    fields: Optional[List[str]] = Field(
+        default=None, description="Select specific fields: ['adx', 'plus_di', 'minus_di']"
+    )

tradepose_models/indicators/volatility.py

@@ -0,0 +1,57 @@
+"""
+Volatility Indicator Models
+
+ATR and ATRQuantile indicators aligned with Rust backend.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ATRIndicator(BaseModel):
+    """Average True Range (ATR) 指标
+
+    对应 Rust: Indicator::ATR { period }
+
+    Returns:
+        单一数值字段（不是 struct）
+
+    Example:
+        >>> atr = ATRIndicator(period=14)
+        >>> atr = ATRIndicator(period=21)
+    """
+
+    type: Literal["ATR"] = "ATR"
+    period: int = Field(gt=0, le=200, description="Period must be > 0 and <= 200")
+
+
+class ATRQuantileIndicator(BaseModel):
+    """ATR Rolling Quantile 指标
+
+    对应 Rust: Indicator::AtrQuantile { atr_column, window, quantile }
+
+    计算 ATR 的滚动分位数，用于动态止损等场景。
+
+    注意：这是依赖指标，必须先定义 ATR 指标。
+
+    Args:
+        atr_column: 引用的 ATR 列名（如 "ATR|14"）
+        window: 滚动窗口大小
+        quantile: 分位数值 (0, 1)，0.5 表示中位数
+
+    Returns:
+        单一数值字段（不是 struct）
+
+    Example:
+        >>> atr_q = ATRQuantileIndicator(
+        ...     atr_column="ATR|21",
+        ...     window=40,
+        ...     quantile=0.75  # 75th percentile
+        ... )
+    """
+
+    type: Literal["AtrQuantile"] = "AtrQuantile"
+    atr_column: str = Field(min_length=1, description="Reference to existing ATR column")
+    window: int = Field(gt=0, le=500, description="Rolling window size")
+    quantile: float = Field(gt=0, lt=1, description="Quantile value in (0, 1)")

tradepose_models/instruments/__init__.py

@@ -0,0 +1,13 @@
+"""Instrument models."""
+
+from tradepose_models.instruments.instrument import (
+    Instrument,
+    InstrumentStatus,
+    get_instrument_key,
+)
+
+__all__ = [
+    "Instrument",
+    "InstrumentStatus",
+    "get_instrument_key",
+]

tradepose_models/instruments/instrument.py

@@ -0,0 +1,87 @@
+"""Instrument (trading instrument) models."""
+
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from tradepose_models.broker.account_config import BrokerType, MarketType
+from tradepose_models.enums import AccountSource
+
+
+class InstrumentStatus(str, Enum):
+    """Instrument trading status."""
+
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    TRADING_HALT = "trading_halt"
+
+
+class Instrument(BaseModel):
+    """
+    金融商品核心模型
+
+    Unique Key: (symbol, source, market_type)
+    """
+
+    # === 資料庫 ID (從 DB 查詢時填入) ===
+    id: int | None = Field(default=None, description="資料庫自動生成的 ID")
+
+    # === 識別欄位 (Composite Key) ===
+    symbol: str = Field(..., description="券商原生符號: BTCUSDT, EURUSD")
+    source: AccountSource = Field(..., description="帳戶來源: BINANCE, FTMO, SHIOAJI")
+    broker_type: BrokerType = Field(..., description="券商類型: binance, mt5, sinopac")
+    market_type: MarketType = Field(..., description="市場類型: SPOT, FUTURES, SWAP")
+
+    # === 貨幣定義 ===
+    base_currency: str = Field(..., description="基礎資產: BTC, EUR")
+    quote_currency: str = Field(..., description="計價貨幣: USDT, USD")
+
+    # === 交易規格 (必要) ===
+    tick_size: Decimal = Field(..., description="最小跳動點")
+    lot_size: Decimal = Field(..., description="最小下單量")
+    price_precision: int = Field(..., description="價格精度 (小數位數)")
+    quantity_precision: int = Field(..., description="數量精度 (小數位數)")
+
+    # === 交易規格 (可選) ===
+    contract_size: Decimal = Field(default=Decimal("1"), description="合約大小 (衍生品)")
+    contract_expiry: datetime | None = Field(default=None, description="到期日 (季度期貨)")
+    min_notional: Decimal | None = Field(default=None, description="最小名義價值")
+
+    # === 狀態 ===
+    status: InstrumentStatus = Field(default=InstrumentStatus.ACTIVE)
+
+    # === 擴展 ===
+    metadata: dict = Field(default_factory=dict)
+
+
+def get_instrument_key(instrument: Instrument) -> str:
+    """
+    獲取 Instrument 的唯一鍵值
+
+    用於 OHLCV 資料庫主鍵或唯一索引。
+
+    Args:
+        instrument: Instrument 實例
+
+    Returns:
+        唯一的 key 字符串
+
+    Examples:
+        >>> inst = Instrument(
+        ...     symbol="BTCUSDT",
+        ...     source=AccountSource.BINANCE,
+        ...     broker_type=BrokerType.BINANCE,
+        ...     market_type=MarketType.SPOT,
+        ...     base_currency="BTC",
+        ...     quote_currency="USDT",
+        ...     tick_size=Decimal("0.01"),
+        ...     lot_size=Decimal("0.001"),
+        ...     price_precision=2,
+        ...     quantity_precision=3,
+        ... )
+        >>> get_instrument_key(inst)
+        'BINANCE:spot:BTCUSDT'
+    """
+    return f"{instrument.source.value}:{instrument.market_type.value}:{instrument.symbol}"

tradepose_models/scheduler/__init__.py

@@ -0,0 +1,9 @@
+"""Scheduler models and responses."""
+
+from .results import OperationStatus, TradesUpdateJobResult, UpdateTradesResult
+
+__all__ = [
+    "OperationStatus",
+    "TradesUpdateJobResult",
+    "UpdateTradesResult",
+]

tradepose_models/scheduler/results.py

@@ -0,0 +1,49 @@
+"""Result models for scheduler operations."""
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class OperationStatus(str, Enum):
+    """Status of an operation."""
+
+    COMPLETED = "completed"
+    COMPLETED_WITH_ERRORS = "completed_with_errors"
+    FAILED = "failed"
+
+
+class UpdateTradesResult(BaseModel):
+    """Result of updating trades for a user.
+
+    Returned by TradesUpdaterService.update_trades_for_user()
+    """
+
+    status: OperationStatus = Field(..., description="Operation status")
+    user_id: str = Field(..., description="User UUID")
+    sb_combinations: int = Field(..., description="Number of strategy+blueprint combinations found")
+    batches_published: int = Field(..., description="Number of batches successfully published")
+    tasks_published: list[str] = Field(
+        default_factory=list, description="List of task IDs published"
+    )
+    errors: list[str] | None = Field(None, description="List of errors encountered (if any)")
+    error: str | None = Field(None, description="Fatal error message (if failed)")
+
+    model_config = ConfigDict(use_enum_values=True)
+
+
+class TradesUpdateJobResult(BaseModel):
+    """Result of TradesUpdateJob execution.
+
+    Returned by TradesUpdateJob.run()
+    """
+
+    status: OperationStatus = Field(..., description="Job execution status")
+    users_processed: int = Field(..., description="Number of users processed")
+    total_batches: int = Field(..., description="Total batches published across all users")
+    lookback_days: int = Field(..., description="Lookback period used")
+    errors: list[str] | None = Field(None, description="List of errors encountered (if any)")
+    error: str | None = Field(None, description="Fatal error message (if failed)")
+    message: str | None = Field(None, description="Additional message (if applicable)")
+
+    model_config = ConfigDict(use_enum_values=True)

tradepose_models/schemas/__init__.py

@@ -0,0 +1,15 @@
+"""
+Polars Schema Definitions
+
+Provides schema definitions for Enhanced OHLCV, Trades, and Performance data.
+"""
+
+from .enhanced_ohlcv import enhanced_ohlcv_schema
+from .performance import performance_schema
+from .trades import trades_schema
+
+__all__ = [
+    "enhanced_ohlcv_schema",
+    "trades_schema",
+    "performance_schema",
+]

tradepose_models/schemas/enhanced_ohlcv.py

@@ -0,0 +1,111 @@
+"""
+Enhanced OHLCV Schema
+
+Polars schema definition for enhanced OHLCV data with signals and trading context.
+"""
+
+import polars as pl
+
+# Enhanced OHLCV Schema
+enhanced_ohlcv_schema = {
+    "idx": pl.Int64,
+    "ts": pl.Datetime("ms"),
+    "open": pl.Float64,
+    "high": pl.Float64,
+    "low": pl.Float64,
+    "close": pl.Float64,
+    "volume": pl.Float64,
+    "gap_type": pl.Int64,
+    "gap_points": pl.Float64,
+    "gap_range_min": pl.Float64,
+    "gap_range_max": pl.Float64,
+    "entry_signal": pl.Boolean,
+    "exit_signal": pl.Boolean,
+    "cleaned_entry_signal": pl.Boolean,
+    "cleaned_exit_signal": pl.Boolean,
+    "base_entry_price": pl.Float64,
+    "base_entry_strategy": pl.Int64,
+    "base_exit_price": pl.Float64,
+    "base_exit_strategy": pl.Int64,
+    "base_position_id": pl.Int64,
+    # 巢狀結構統一使用 Struct
+    "base_trading_context": pl.Struct(
+        [
+            pl.Field("bars_in_position", pl.Int64),
+            pl.Field("highest_since_entry", pl.Float64),
+            pl.Field("lowest_since_entry", pl.Float64),
+            pl.Field("position_entry_price", pl.Float64),
+        ]
+    ),
+    # 來自 trigger 自動產生
+    # "base_entry": pl.Struct(
+    #     [
+    #         pl.Field("cond", pl.Boolean),
+    #         pl.Field("price", pl.Float64),
+    #         pl.Field("strategy", pl.Int64),
+    #         pl.Field("priority", pl.Int64),
+    #     ]
+    # ),
+    "advanced_favorable_entry_hypo_price": pl.Float64,
+    "advanced_adverse_entry_hypo_price": pl.Float64,
+    "advanced_neutral_entry_hypo_price": pl.Float64,
+    "advanced_favorable_entry_strategy": pl.Int64,
+    "advanced_adverse_entry_strategy": pl.Int64,
+    "advanced_neutral_entry_strategy": pl.Int64,
+    "advanced_entry_price": pl.Float64,
+    "advanced_entry_strategy": pl.Int64,
+    "is_entry_gap_filled": pl.Boolean,
+    "advanced_cleaned_entry_signal": pl.Boolean,
+    "advanced_entry_position_id": pl.Int64,
+    "advanced_entry_trading_context": pl.Struct(
+        [
+            pl.Field("bars_since_advanced_entry", pl.Int64),
+            pl.Field("highest_since_advanced_entry", pl.Float64),
+            pl.Field("lowest_since_advanced_entry", pl.Float64),
+            pl.Field("position_entry_price", pl.Float64),
+        ]
+    ),
+    # 來自 trigger 自動產生
+    # "base_exit": pl.Struct(
+    #     [
+    #         pl.Field("cond", pl.Boolean),
+    #         pl.Field("price", pl.Float64),
+    #         pl.Field("strategy", pl.Int64),
+    #         pl.Field("priority", pl.Int64),
+    #     ]
+    # ),
+    "advanced_favorable_exit_hypo_price": pl.Float64,
+    "advanced_adverse_exit_hypo_price": pl.Float64,
+    "advanced_neutral_exit_hypo_price": pl.Float64,
+    "advanced_favorable_exit_strategy": pl.Int64,
+    "advanced_adverse_exit_strategy": pl.Int64,
+    "advanced_neutral_exit_strategy": pl.Int64,
+    "advanced_exit_price": pl.Float64,
+    "advanced_exit_strategy": pl.Int64,
+    "is_exit_gap_filled": pl.Boolean,
+    "advanced_cleaned_exit_signal": pl.Boolean,
+    "advanced_exit_position_id": pl.Int64,
+    "advanced_exit_trading_context": pl.Struct(
+        [
+            pl.Field("bars_since_advanced_entry", pl.Int64),
+            pl.Field("highest_since_advanced_entry", pl.Float64),
+            pl.Field("lowest_since_advanced_entry", pl.Float64),
+            pl.Field("position_entry_price", pl.Float64),
+        ]
+    ),
+    "is_entry_valid": pl.Boolean,
+    "entry_rejection_reason": pl.Utf8,
+    "validated_entry_signal": pl.Boolean,
+    "validated_exit_signal": pl.Boolean,
+    "final_position_id": pl.Int64,
+    "final_trading_context": pl.Struct(
+        [
+            pl.Field("bars_in_position", pl.Int64),
+            pl.Field("highest_since_entry", pl.Float64),
+            pl.Field("lowest_since_entry", pl.Float64),
+            pl.Field("position_entry_price", pl.Float64),
+        ]
+    ),
+    "strategy_name": pl.Utf8,
+    "blueprint_name": pl.Utf8,
+}

tradepose_models/schemas/performance.py

@@ -0,0 +1,40 @@
+"""
+Performance Schema
+
+Polars schema definition for performance metrics from backtest results.
+"""
+
+import polars as pl
+
+# Performance Schema (from backtest-results export)
+# Updated to match actual API response
+performance_schema = {
+    # Identifiers
+    "strategy_name": pl.Utf8,
+    "blueprint_name": pl.Utf8,
+    "metric_type": pl.Utf8,  # "pnl_pct" or "pnl"
+    # Basic trade statistics
+    "trades": pl.UInt32,  # Total number of trades (renamed from total_trades)
+    "win_ratio": pl.Float64,  # Win rate (renamed from win_rate)
+    # Time information
+    "first_entry_time": pl.Datetime("ms"),
+    "last_entry_time": pl.Datetime("ms"),
+    "last_exit_time": pl.Datetime("ms"),
+    # Performance metrics
+    "total": pl.Float64,  # Total PnL (renamed from total_pnl)
+    "expect_payoff": pl.Float64,  # Expected payoff per trade
+    "pnl_std": pl.Float64,  # Standard deviation of PnL
+    # Risk metrics
+    "profit_factor": pl.Float64,
+    "sharpe_ratio": pl.Float64,
+    "sortino_ratio": pl.Float64,
+    "recovery_factor": pl.Float64,
+    # MAE/MFE risk analysis
+    "risk_mae_pct_p75": pl.Float64,  # 75th percentile MAE (risk management)
+    "risk_mae_pct_conservative": pl.Float64,  # Conservative MAE estimate
+    "risk_mae_pct_p95": pl.Float64,  # 95th percentile MAE (worst case)
+    "g_mfe_after_mae_pct": pl.Float64,  # Global MFE after MAE
+    # Advanced metrics
+    "kelly": pl.Float64,  # Kelly criterion
+    "sqn": pl.Float64,  # System Quality Number
+}