tradepose-models 1.1.0__py3-none-any.whl

tradepose_models/__init__.py

@@ -0,0 +1,44 @@
+"""TradePose shared models package.
+
+This package contains Pydantic models, enums, schemas, and types shared
+across the TradePose platform, including gateway, client SDK, and other
+components.
+
+Organization:
+    - base: Base Pydantic model with standardized configuration
+    - enums: Shared enumerations
+    - events: Order and trading event models
+    - schemas: Shared data schemas (Polars)
+    - auth: Authentication and API key models
+    - billing: Billing, subscription, and usage models
+    - broker: Broker account and binding models
+    - export: Export task and result models
+    - gateway: Gateway API response models
+    - indicators: Indicator specifications
+    - strategy: Strategy configuration models
+    - trading: Trading-related models (orders, positions, engagements)
+    - utils: Utility modules (rate conversion, etc.)
+    - validators: Shared validation utilities
+    - types: Common type definitions
+
+Example usage:
+    from tradepose_models.base import BaseModel
+    from tradepose_models.enums import TaskStatus, ExportType
+    from tradepose_models.auth import APIKeyCreate
+    from tradepose_models.billing import PlanResponse
+    from tradepose_models.export import ExportTaskResponse
+    from tradepose_models.utils import RateConverter, get_default_converter
+"""
+
+from .base import BaseModel
+from .utils import DEFAULT_RATES, RateConverter, get_default_converter
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "BaseModel",
+    "DEFAULT_RATES",
+    "RateConverter",
+    "get_default_converter",
+]

tradepose_models/auth/__init__.py

@@ -0,0 +1,13 @@
+"""Authentication and API key models."""
+
+from .api_keys import APIKeyCreate, APIKeyCreateResponse, APIKeyListResponse, APIKeyResponse
+from .auth import AuthContext, AuthUser
+
+__all__ = [
+    "APIKeyCreate",
+    "APIKeyResponse",
+    "APIKeyCreateResponse",
+    "APIKeyListResponse",
+    "AuthUser",
+    "AuthContext",
+]

tradepose_models/auth/api_keys.py

@@ -0,0 +1,52 @@
+"""API key management models."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class APIKeyCreate(BaseModel):
+    """Request model for creating a new API key."""
+
+    name: str = Field(
+        ...,
+        min_length=1,
+        max_length=100,
+        description="Human-readable name for the API key",
+    )
+
+
+class APIKeyResponse(BaseModel):
+    """Response model for API key (without plaintext key)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    user_id: str  # Clerk ID
+    name: str
+    revoked: bool
+    last_used: datetime | None
+    created_at: datetime
+
+
+class APIKeyCreateResponse(BaseModel):
+    """Response model when creating a new API key (includes plaintext key ONCE)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    user_id: str  # Clerk ID
+    name: str
+    api_key: str = Field(
+        ...,
+        description="Plaintext API key - save this securely, it won't be shown again!",
+    )
+    created_at: datetime
+
+
+class APIKeyListResponse(BaseModel):
+    """Response model for listing API keys."""
+
+    keys: list[APIKeyResponse]
+    total: int

tradepose_models/auth/auth.py

@@ -0,0 +1,20 @@
+"""Authentication context models."""
+
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class AuthUser(BaseModel):
+    """Authenticated user information."""
+
+    user_id: str  # Clerk ID (primary key)
+    auth_method: str = Field(..., description="Authentication method used: 'jwt' or 'api_key'")
+    api_key_id: UUID | None = None  # Present if authenticated via API key
+
+
+class AuthContext(BaseModel):
+    """Full authentication context for a request."""
+
+    user: AuthUser
+    is_authenticated: bool = True

tradepose_models/base.py

@@ -0,0 +1,57 @@
+"""
+Base Pydantic models with standardized configuration.
+
+This module provides a base model that all TradePose models should inherit from.
+It includes standardized serialization rules, particularly for enum handling.
+"""
+
+from pydantic import BaseModel as PydanticBaseModel
+from pydantic import ConfigDict
+
+
+class BaseModel(PydanticBaseModel):
+    """
+    Base model with standardized configuration for all TradePose models.
+
+    Configuration:
+    - use_enum_values=False: Enums serialize to their NAME (uppercase string) instead of value
+      Example: TaskStatus.PENDING → "PENDING" (not 0)
+    - validate_assignment=True: Validate field assignments after model creation
+    - arbitrary_types_allowed=True: Allow custom types (e.g., Redis connections)
+
+    Internal Storage vs API Response:
+    - PostgreSQL: Stores enums as SMALLINT (0, 1, 2, 3)
+    - Python Code: Uses int Enum (TaskStatus.PENDING = 0)
+    - Redis: Stores as integer in JSON ({"status": 0})
+    - API JSON Output: Serializes as uppercase string ({"status": "PENDING"})
+
+    This ensures:
+    1. Efficient storage (integers in database)
+    2. Type safety in code (enum objects)
+    3. Readable API responses (uppercase strings)
+    4. Backward compatibility (string format maintained)
+
+    Example:
+        ```python
+        from tradepose_models.base import BaseModel
+        from tradepose_models.enums import TaskStatus
+
+        class MyModel(BaseModel):
+            status: TaskStatus
+
+        model = MyModel(status=TaskStatus.PENDING)
+        print(model.model_dump())  # {'status': TaskStatus.PENDING}
+        print(model.model_dump_json())  # '{"status":"PENDING"}'
+        ```
+    """
+
+    model_config = ConfigDict(
+        # Serialize enums to name (uppercase string) for API responses
+        use_enum_values=False,
+        # Validate assignments after model creation
+        validate_assignment=True,
+        # Allow arbitrary types (e.g., Redis connections, asyncpg pools)
+        arbitrary_types_allowed=True,
+        # Use attribute docstrings for schema descriptions
+        use_attribute_docstrings=True,
+    )

tradepose_models/billing/__init__.py

@@ -0,0 +1,33 @@
+"""Billing and subscription models."""
+
+from .checkout import CheckoutRequest, CheckoutResponse
+from .plans import PlanLimitsResponse, PlanResponse, PlansListResponse
+from .subscriptions import SubscriptionDetailResponse, SubscriptionResponse
+from .usage import (
+    CurrentUsageResponse,
+    DetailedUsageResponse,
+    UsageDayResponse,
+    UsageHistoryResponse,
+    UsageStatsResponse,
+    UsageWindowResponse,
+)
+
+__all__ = [
+    # Checkout
+    "CheckoutRequest",
+    "CheckoutResponse",
+    # Plans
+    "PlanLimitsResponse",
+    "PlanResponse",
+    "PlansListResponse",
+    # Subscriptions
+    "SubscriptionResponse",
+    "SubscriptionDetailResponse",
+    # Usage
+    "UsageDayResponse",
+    "CurrentUsageResponse",
+    "UsageHistoryResponse",
+    "UsageStatsResponse",
+    "UsageWindowResponse",
+    "DetailedUsageResponse",
+]

tradepose_models/billing/checkout.py

@@ -0,0 +1,17 @@
+"""Checkout session models."""
+
+from pydantic import BaseModel, Field
+
+
+class CheckoutRequest(BaseModel):
+    """Request model for creating a checkout session."""
+
+    plan_tier: str = Field(..., description="Plan tier: free, pro, enterprise")
+    billing_cycle: str = Field(..., description="Billing cycle: monthly, yearly")
+
+
+class CheckoutResponse(BaseModel):
+    """Response model for checkout session."""
+
+    checkout_url: str = Field(..., description="Lemon Squeezy checkout URL")
+    variant_id: str = Field(..., description="Lemon Squeezy variant ID")

tradepose_models/billing/plans.py

@@ -0,0 +1,32 @@
+"""Subscription plan models."""
+
+from pydantic import BaseModel
+
+
+class PlanLimitsResponse(BaseModel):
+    """Plan limits response model."""
+
+    requests_per_minute: int
+    monthly_quota: int
+    max_concurrent_tasks: int
+    max_strategies: int
+    priority_queue: bool
+    support_level: str
+
+
+class PlanResponse(BaseModel):
+    """Subscription plan response model."""
+
+    tier: str
+    name: str
+    description: str
+    price_monthly: float
+    price_yearly: float
+    limits: PlanLimitsResponse
+    features: list[str]
+
+
+class PlansListResponse(BaseModel):
+    """Response model for listing all plans."""
+
+    plans: list[PlanResponse]

tradepose_models/billing/subscriptions.py

@@ -0,0 +1,34 @@
+"""Subscription models."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+from .plans import PlanResponse
+
+
+class SubscriptionResponse(BaseModel):
+    """Response model for subscription (without sensitive data)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    user_id: UUID  # User ID (UUID)
+    lemonsqueezy_subscription_id: str | None = None
+    lemonsqueezy_customer_id: str | None = None
+    plan: str
+    status: str
+    current_period_start: datetime | None = None
+    current_period_end: datetime | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class SubscriptionDetailResponse(BaseModel):
+    """Detailed subscription response with plan info."""
+
+    subscription: SubscriptionResponse | None
+    current_plan: PlanResponse
+    usage_current_month: int = 0
+    usage_limit: int = 0

tradepose_models/billing/usage.py

@@ -0,0 +1,71 @@
+"""Usage tracking models."""
+
+from datetime import date, datetime
+
+from pydantic import BaseModel, Field
+
+
+class UsageDayResponse(BaseModel):
+    """Daily usage record response."""
+
+    usage_date: date = Field(..., description="Date of usage")
+    requests: int = Field(..., description="Number of requests on this date")
+
+
+class CurrentUsageResponse(BaseModel):
+    """Current month usage response."""
+
+    user_id: str  # Clerk ID
+    current_month: str = Field(..., description="Current month (YYYY-MM)")
+    usage: int = Field(..., description="Total requests this month")
+    limit: int = Field(..., description="Monthly quota limit")
+    remaining: int = Field(..., description="Remaining requests")
+    percentage_used: float = Field(..., description="Percentage of quota used (0-100)")
+
+
+class UsageHistoryResponse(BaseModel):
+    """Historical usage response."""
+
+    user_id: str  # Clerk ID
+    start_date: date
+    end_date: date
+    total_requests: int = Field(..., description="Total requests in date range")
+    daily_usage: list[UsageDayResponse] = Field(default_factory=list, description="Daily breakdown")
+
+
+class UsageStatsResponse(BaseModel):
+    """Usage statistics response."""
+
+    current_month: CurrentUsageResponse
+    plan_name: str
+    plan_tier: str
+    rate_limit_per_minute: int
+    monthly_quota: int
+
+
+class UsageWindowResponse(BaseModel):
+    """Usage window response for a specific time period."""
+
+    total_requests: int = Field(..., description="Total number of requests")
+    completed_tasks: int = Field(..., description="Number of completed tasks")
+    failed_tasks: int = Field(..., description="Number of failed tasks")
+
+
+class DetailedUsageResponse(BaseModel):
+    """Detailed usage statistics response from Redis cache."""
+
+    period_start: datetime = Field(..., description="Start of the current billing period")
+    last_minute: UsageWindowResponse = Field(..., description="Usage in the last minute")
+    last_hour: UsageWindowResponse = Field(..., description="Usage in the last hour")
+    last_day: UsageWindowResponse = Field(..., description="Usage in the last day")
+    current_period: UsageWindowResponse = Field(
+        ..., description="Usage in the current billing period"
+    )
+    plan: str = Field(..., description="Current plan tier (free/pro/enterprise)")
+    monthly_quota: int = Field(..., description="Monthly quota limit for the plan")
+    requests_per_minute: int = Field(..., description="Rate limit per minute")
+    remaining_quota: int = Field(..., description="Remaining quota for the current period")
+    quota_percentage_used: float = Field(
+        ..., description="Percentage of monthly quota used (0-100)"
+    )
+    last_updated: datetime = Field(..., description="When this data was last calculated")

tradepose_models/broker/__init__.py

@@ -0,0 +1,34 @@
+"""Broker-related models and configuration."""
+
+from tradepose_models.broker.account_config import (
+    AccountStatus,
+    BrokerAccount,
+    BrokerCredentials,
+    MarketType,
+)
+from tradepose_models.broker.account_models import (
+    AccountBalance,
+    AccountInfo,
+    MarginInfo,
+)
+from tradepose_models.broker.binding import AccountPortfolioBinding
+from tradepose_models.broker.connection_status import ConnectionStatus
+from tradepose_models.enums import BrokerType
+
+__all__ = [
+    # Enums
+    "BrokerType",
+    "MarketType",
+    "AccountStatus",
+    "ConnectionStatus",
+    # Credentials
+    "BrokerCredentials",
+    # Account
+    "BrokerAccount",
+    # Account Info
+    "AccountBalance",
+    "AccountInfo",
+    "MarginInfo",
+    # Binding
+    "AccountPortfolioBinding",
+]

tradepose_models/broker/account_config.py

@@ -0,0 +1,93 @@
+"""Broker account configuration models."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field, SecretStr
+
+from tradepose_models.enums import AccountSource, BrokerType
+
+
+class MarketType(str, Enum):
+    """Market types."""
+
+    SPOT = "spot"  # Spot market
+    FUTURES = "futures"  # Futures
+    MARGIN = "margin"  # Margin trading
+    OPTIONS = "options"  # Options
+    SWAP = "swap"  # Perpetual swap
+
+
+class AccountStatus(str, Enum):
+    """Account status."""
+
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    SUSPENDED = "suspended"
+    EXPIRED = "expired"
+
+
+class BrokerCredentials(BaseModel):
+    """
+    Broker credentials (encrypted storage).
+
+    Credentials are provided by users and passed to adapters.
+    Storage encryption is handled by consuming applications.
+    """
+
+    api_key: SecretStr = Field(..., description="API Key")
+    api_secret: SecretStr = Field(..., description="API Secret")
+
+    # Optional fields (broker-specific)
+    passphrase: Optional[SecretStr] = Field(None, description="API Passphrase (OKX)")
+    account_id: Optional[str] = Field(None, description="Account ID")
+    password: Optional[SecretStr] = Field(None, description="Login password (MT5)")
+    person_id: Optional[str] = Field(None, description="Person ID (Taiwan brokers)")
+
+    # Additional config
+    extra_config: dict[str, Any] = Field(default_factory=dict)
+
+
+class BrokerAccount(BaseModel):
+    """
+    Broker account configuration.
+
+    This model is passed to BrokerAdapter on initialization.
+    It contains all information needed to connect to a broker.
+    """
+
+    # Basic info
+    id: UUID = Field(..., description="Account UUID")
+    user_id: UUID = Field(..., description="User UUID who owns this account")
+    name: str = Field(..., description="Account name")
+
+    # Broker info (immutable after creation)
+    broker_type: BrokerType = Field(..., description="Broker type")
+    credentials: BrokerCredentials = Field(..., description="Encrypted credentials")
+
+    # Market configuration
+    available_markets: list[MarketType] = Field(
+        ..., description="Supported market types for this account"
+    )
+    default_market: Optional[MarketType] = Field(None, description="Default market type")
+
+    # Environment configuration
+    environment: str = Field(
+        default="production", description="Environment (production/testnet/sandbox)"
+    )
+    base_url: Optional[str] = Field(None, description="API Base URL")
+    ws_url: Optional[str] = Field(None, description="WebSocket URL")
+
+    # Status
+    status: AccountStatus = Field(default=AccountStatus.INACTIVE)
+
+    # Account source (for timezone handling)
+    account_source: Optional[AccountSource] = Field(
+        None, description="Account source (FTMO, IB, etc.) for timezone determination"
+    )
+
+    # Metadata
+    created_at: datetime
+    updated_at: datetime

tradepose_models/broker/account_models.py

@@ -0,0 +1,61 @@
+"""Account balance and information models."""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class AccountBalance(BaseModel):
+    """Account balance for a specific asset."""
+
+    asset: str = Field(..., description="Asset symbol (USD, USDT, BTC, etc.)")
+    total: Decimal = Field(..., description="Total balance")
+    free: Decimal = Field(..., description="Available balance")
+    locked: Decimal = Field(default=Decimal("0"), description="Locked balance in orders/margin")
+
+
+class AccountInfo(BaseModel):
+    """Account information."""
+
+    # Basic identification
+    account_id: UUID = Field(..., description="Unique account identifier")
+    broker: str = Field(..., description="Broker name (mt5, binance, okx)")
+    account_type: str = Field(..., description="CASH, MARGIN, FUTURES, SPOT, demo, real")
+
+    # Status (provide defaults for backward compatibility)
+    status: str = Field(default="ACTIVE", description="ACTIVE, SUSPENDED, CLOSED")
+    trading_enabled: bool = Field(default=True)
+
+    # Financial information
+    total_equity: Decimal = Field(..., description="Total account equity")
+    available_balance: Decimal = Field(..., description="Available balance for trading")
+    used_margin: Decimal = Field(default=Decimal("0"), description="Margin currently in use")
+
+    # Account attributes
+    leverage: int = Field(default=1, description="Account leverage")
+    currency: str = Field(default="USD", description="Account base currency")
+    position_count: int = Field(default=0, description="Number of open positions")
+
+    # Timestamps
+    created_at: Optional[datetime] = None
+
+    # Extended fields for broker-specific info
+    broker: Optional[str] = Field(None, description="Broker name")
+    total_equity: Optional[Decimal] = Field(None, description="Total equity")
+    available_balance: Optional[Decimal] = Field(None, description="Available balance")
+    used_margin: Optional[Decimal] = Field(None, description="Used margin")
+    position_count: Optional[int] = Field(None, description="Number of open positions")
+    leverage: Optional[int] = Field(None, description="Account leverage")
+    currency: Optional[str] = Field(None, description="Account currency")
+
+
+class MarginInfo(BaseModel):
+    """Margin information."""
+
+    initial_margin: Decimal = Field(..., description="Initial margin requirement")
+    maintenance_margin: Decimal = Field(..., description="Maintenance margin requirement")
+    margin_level: Decimal = Field(..., description="Margin level (%)")
+    liquidation_price: Optional[Decimal] = Field(None, description="Liquidation price")

tradepose_models/broker/binding.py

@@ -0,0 +1,54 @@
+"""
+Account-Portfolio Binding Model
+
+Provides the AccountPortfolioBinding model for linking trading accounts to portfolios.
+"""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from ..enums import ExecutionMode
+
+
+class AccountPortfolioBinding(BaseModel):
+    """Account-Portfolio binding configuration.
+
+    Links a trading account to a portfolio for automated trading.
+    Controls execution behavior and capital allocation.
+
+    Unique constraint: (account_id, portfolio_id)
+    """
+
+    id: UUID = Field(..., description="Binding UUID (primary key)")
+    user_id: UUID = Field(..., description="User UUID for multi-tenancy")
+    account_id: UUID = Field(..., description="Trading account UUID (FK)")
+    portfolio_id: UUID = Field(..., description="Portfolio UUID (FK)")
+    is_active: bool = Field(default=True, description="Whether binding is active")
+
+    capital_override: Optional[Decimal] = Field(
+        None, description="Override portfolio capital for this binding"
+    )
+    execution_mode: ExecutionMode = Field(
+        default=ExecutionMode.PRICE_PRIORITY,
+        description="Execution mode (price_priority or signal_priority)",
+    )
+    order_split_config: Optional[dict] = Field(
+        None, description="Order split configuration (reserved for future use)"
+    )
+
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+    @property
+    def is_price_priority(self) -> bool:
+        """Check if execution mode is price priority."""
+        return self.execution_mode == ExecutionMode.PRICE_PRIORITY
+
+    @property
+    def is_signal_priority(self) -> bool:
+        """Check if execution mode is signal priority."""
+        return self.execution_mode == ExecutionMode.SIGNAL_PRIORITY

tradepose_models/broker/connection_status.py

@@ -0,0 +1,14 @@
+"""Connection status enum for broker adapters."""
+
+from enum import Enum
+
+
+class ConnectionStatus(str, Enum):
+    """Broker connection status states."""
+
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+    FAILED = "failed"
+    SCHEDULED_DOWNTIME = "scheduled_downtime"

tradepose_models/commands/__init__.py

@@ -0,0 +1,8 @@
+"""Trader command models (Issue #307).
+
+Models for commands sent to Trader via Redis Streams.
+"""
+
+from .trader_command import CommandType, TraderCommand
+
+__all__ = ["CommandType", "TraderCommand"]