tradai.common.entities¶

class ExchangeConfig(BaseModel):
    """Configuration for a CCXT exchange connection.

    Supports both CEX (API key/secret) and DEX (private key) authentication.
    Uses TradingMode enum for market type.
    Provides ccxt_types property for CCXT market filtering.

    Example:
        >>> # CEX (Binance)
        >>> config = ExchangeConfig(name="binance", trading_mode=TradingMode.FUTURES)
        >>> config.key
        'binance_futures'

        >>> # DEX (Hyperliquid)
        >>> config = ExchangeConfig(
        ...     name="hyperliquid",
        ...     auth_type=AuthType.PRIVATE_KEY,
        ...     private_key=SecretStr("0x..."),
        ... )

        >>> # From Secrets Manager
        >>> config = ExchangeConfig.from_secret("tradai/prod/exchange/binance")
    """

    model_config = {"frozen": True}

    name: str = Field(..., description="CCXT exchange name (e.g., 'binance', 'hyperliquid')")
    trading_mode: TradingMode = Field(default=TradingMode.FUTURES)
    auth_type: AuthType = Field(default=AuthType.API_KEY)

    # CEX fields (API key/secret pattern)
    api_key: SecretStr = Field(default=SecretStr(""), description="Exchange API key (CEX)")
    api_secret: SecretStr = Field(default=SecretStr(""), description="Exchange API secret (CEX)")
    passphrase: SecretStr = Field(
        default=SecretStr(""), description="Exchange passphrase (Coinbase, Kucoin)"
    )

    # DEX fields (private key pattern)
    private_key: SecretStr = Field(default=SecretStr(""), description="Private key (DEX)")
    wallet_address: str = Field(default="", description="Wallet address (DEX, optional)")

    @classmethod
    def from_secret(
        cls,
        secret_name: str,
        name: str | None = None,
        trading_mode: TradingMode = TradingMode.FUTURES,
        client: Any = None,
    ) -> ExchangeConfig:
        """Load credentials from AWS Secrets Manager.

        Expected secret format for CEX:
        ```json
        {
            "auth_type": "api_key",
            "api_key": "xxx",
            "api_secret": "yyy",
            "passphrase": "zzz"
        }
        ```

        Expected secret format for DEX:
        ```json
        {
            "auth_type": "private_key",
            "private_key": "0x...",
            "wallet_address": "0x..."
        }
        ```

        Args:
            secret_name: Name or ARN of the secret in Secrets Manager
            name: Exchange name (optional, can be in secret as "exchange_name")
            trading_mode: Trading mode (default: FUTURES)
            client: Optional Secrets Manager client for testing

        Returns:
            ExchangeConfig instance

        Raises:
            ExternalServiceError: If secret retrieval fails
            ValidationError: If secret format is invalid
        """
        from tradai.common.aws.secrets_manager import get_secret

        secret = get_secret(secret_name, client=client)
        auth_type = AuthType(secret.get("auth_type", AuthType.API_KEY.value))
        exchange_name = name or secret.get("exchange_name", "")

        if not exchange_name:
            raise ValueError("Exchange name must be provided or included in secret")

        if auth_type == AuthType.PRIVATE_KEY:
            return cls(
                name=exchange_name,
                trading_mode=trading_mode,
                auth_type=auth_type,
                private_key=SecretStr(secret["private_key"]),
                wallet_address=secret.get("wallet_address", ""),
            )

        return cls(
            name=exchange_name,
            trading_mode=trading_mode,
            auth_type=auth_type,
            api_key=SecretStr(secret["api_key"]),
            api_secret=SecretStr(secret["api_secret"]),
            passphrase=SecretStr(secret.get("passphrase", "")),
        )

    @property
    def key(self) -> str:
        """Return dict key for this exchange (e.g., 'binance_futures')."""
        return f"{self.name}_{self.trading_mode.value}"

    @property
    def ccxt_types(self) -> frozenset[str]:
        """Get CCXT market types for filtering."""
        return self.trading_mode.ccxt_types

    @property
    def is_authenticated(self) -> bool:
        """Check if credentials are present for authentication.

        Returns:
            True if required credentials are set.
        """
        if self.auth_type == AuthType.PRIVATE_KEY:
            return bool(self.private_key.get_secret_value())
        return bool(self.api_key.get_secret_value() and self.api_secret.get_secret_value())

    def to_ccxt_config(self) -> dict[str, str]:
        """Convert credentials to CCXT configuration format.

        Returns:
            Dictionary suitable for CCXT exchange initialization.

        Example:
            >>> config = ExchangeConfig(name="binance", api_key=SecretStr("key"), ...)
            >>> ccxt_config = config.to_ccxt_config()
            >>> exchange = ccxt.binance(ccxt_config)
        """
        result: dict[str, str] = {}

        if self.auth_type == AuthType.API_KEY:
            if self.api_key.get_secret_value():
                result["apiKey"] = self.api_key.get_secret_value()
            if self.api_secret.get_secret_value():
                result["secret"] = self.api_secret.get_secret_value()
            if self.passphrase.get_secret_value():
                result["password"] = self.passphrase.get_secret_value()
        elif self.auth_type == AuthType.PRIVATE_KEY:
            if self.private_key.get_secret_value():
                result["privateKey"] = self.private_key.get_secret_value()
            if self.wallet_address:
                result["walletAddress"] = self.wallet_address

        return result

    def validate_credentials(self, timeout: int = 10) -> None:
        """Validate exchange credentials by making an authenticated API call.

        Uses fetch_balance() as the validation method - it's lightweight and
        requires authentication on all exchanges.

        Args:
            timeout: Request timeout in seconds

        Raises:
            AuthenticationError: If credentials are invalid or missing
            ExternalServiceError: If exchange API call fails for other reasons

        Example:
            >>> config = ExchangeConfig.from_secret("tradai/prod/binance")
            >>> config.validate_credentials()  # Raises if invalid
        """
        if not self.is_authenticated:
            raise AuthenticationError(f"No credentials configured for {self.name}")

        exchange = None
        try:
            import ccxt

            # Create exchange client
            exchange_id = self.name.lower()
            if not hasattr(ccxt, exchange_id):
                raise ExternalServiceError(f"Unknown exchange: {exchange_id}")

            exchange_class = getattr(ccxt, exchange_id)
            # Build config with proper types (to_ccxt_config returns dict[str, str])
            ccxt_config: dict[str, Any] = {
                **self.to_ccxt_config(),
                "enableRateLimit": True,
                "timeout": timeout * 1000,  # ccxt uses milliseconds
            }

            exchange = exchange_class(ccxt_config)

            # Validate by calling an authenticated endpoint
            exchange.fetch_balance()

        except ccxt.AuthenticationError as e:
            raise AuthenticationError(f"Invalid credentials for {self.name}: {e}") from e
        except ccxt.ExchangeError as e:
            raise ExternalServiceError(
                f"Exchange error validating credentials for {self.name}: {e}"
            ) from e
        except ImportError as e:
            from tradai.common._optional import MissingDependencyError

            raise MissingDependencyError(
                "ccxt", "ccxt", "ExchangeConfig.validate_credentials"
            ) from e
        finally:
            # Clean up exchange client to prevent resource leak
            if exchange is not None and hasattr(exchange, "close"):
                try:
                    exchange.close()
                except Exception as e:
                    _logger.debug("Exchange cleanup failed: %s", e)

    @field_validator("name")
    @classmethod
    def validate_name(cls, v: str) -> str:
        """Normalize exchange name to lowercase."""
        if not v:
            raise ValueError("Exchange name cannot be empty")
        return v.lower()

    @field_validator("trading_mode", mode="before")
    @classmethod
    def parse_trading_mode(cls, v: str | TradingMode) -> TradingMode:
        """Parse trading mode from string or TradingMode enum."""
        if isinstance(v, TradingMode):
            return v
        if isinstance(v, str):
            return TradingMode.from_string(v)
        raise ValueError(f"trading_mode must be str or TradingMode, got {type(v)}")

class BacktestConfig(BaseModel):
    """Backtest configuration with validation.

    Defines all parameters needed to run a backtest.
    Validates symbols use proper trading pair format and date range is valid.

    Attributes:
        strategy: Strategy name to backtest
        timeframe: Trading timeframe (e.g., "1h", "4h", "1d")
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
        symbols: List of trading pairs
        stoploss: Optional stoploss percentage (-1.0 to 0.0)
        stake_amount: Position size in stake currency
        exchange: Exchange key (e.g., "binance_futures")
        strategy_version: MLflow version specifier ("latest", stage name, or number)
        config_version_id: Optional ConfigVersion ID for reproducibility

    Example:
        >>> config = BacktestConfig(
        ...     strategy="PascalStrategy",
        ...     timeframe="1h",
        ...     start_date="2024-01-01",
        ...     end_date="2024-06-30",
        ...     symbols=["BTC/USDT:USDT", "ETH/USDT:USDT"],
        ...     exchange="binance_futures",
        ...     strategy_version="Production",
        ... )
    """

    strategy: str = Field(..., min_length=1)
    timeframe: str = Field(..., pattern=r"^\d+[mhd]$")  # e.g., "1h", "4h", "1d"
    start_date: str = Field(..., pattern=r"^\d{4}-\d{2}-\d{2}$")
    end_date: str = Field(..., pattern=r"^\d{4}-\d{2}-\d{2}$")
    symbols: list[str] = Field(..., min_length=1)
    stoploss: float | None = Field(default=None, ge=-1.0, le=0.0)
    stake_amount: float = Field(default=1000.0, gt=0)

    # Exchange configuration (default matches existing hardcoded value)
    exchange: str = Field(
        default="binance_futures",
        # Pattern derived from TradingMode enum values (see _EXCHANGE_PATTERN above)
        pattern=_EXCHANGE_PATTERN,
        description="Exchange key: '{name}_{trading_mode}' (e.g., 'binance_futures')",
    )

    # Strategy version for MLflow resolution (default matches existing hardcoded value)
    strategy_version: str = Field(
        default="latest",
        description="'latest', 'Production', 'Staging', or specific version number",
    )

    # Config version reference for reproducibility (opt-in)
    config_version_id: str | None = Field(
        default=None,
        description="ConfigVersion ID for reproducibility tracking",
    )

    # ECS task definition override (bypass unified convention)
    task_definition: str | None = Field(
        default=None,
        min_length=1,
        description=(
            "ECS task definition family name override. If None, computed from "
            "strategy name + environment via get_strategy_task_definition(). "
            "WARNING: Setting this bypasses the unified naming convention. "
            "Use only for emergency overrides or migration."
        ),
    )

    model_config = {"frozen": True}

    @field_validator("start_date", "end_date")
    @classmethod
    def validate_date_is_real(cls, v: str) -> str:
        """Validate date string represents an actual calendar date (C6).

        The pattern regex only checks format (YYYY-MM-DD), not validity.
        This validator catches impossible dates like 2024-02-30 or 2024-13-01.
        """
        try:
            datetime.strptime(v, "%Y-%m-%d")
        except ValueError as e:
            raise ValueError(f"Invalid date '{v}': {e}") from e
        return v

    @field_validator("strategy_version")
    @classmethod
    def validate_strategy_version(cls, v: str) -> str:
        """Validate strategy_version format.

        Valid formats:
        - "latest" - resolve to highest version number
        - "Production", "Staging", "Archived", "None" - resolve by MLflow stage
        - Numeric string like "1", "2", "3" - specific version number
        """
        valid_specifiers = {"latest", "production", "staging", "archived", "none"}
        if v.lower() in valid_specifiers or v.isdigit():
            return v
        raise ValueError(
            f"Invalid strategy_version '{v}'. Use 'latest', stage name, or version number"
        )

    @field_validator("symbols")
    @classmethod
    def validate_symbols_format(cls, v: list[str]) -> list[str]:
        """Validate all symbols use proper trading pair format.

        Uses validate_trading_pair to ensure format like BTC/USDT or BTC/USDT:USDT.
        Prevents command injection and normalizes to uppercase.
        """
        return [validate_trading_pair(s) for s in v]

    @model_validator(mode="after")
    def validate_date_range(self) -> BacktestConfig:
        """Ensure end_date is not before start_date."""
        start = datetime.strptime(self.start_date, "%Y-%m-%d")
        end = datetime.strptime(self.end_date, "%Y-%m-%d")
        if end < start:
            raise ValueError(
                f"end_date ({self.end_date}) must be >= start_date ({self.start_date})"
            )
        return self

class BacktestResult(BaseModel):
    """Backtest execution result.

    Contains complete metrics and trades from a Freqtrade backtest.
    Includes all key ratios: Sharpe, Sortino, Calmar, SQN, etc.
    Additional metrics stored in the metrics dict for MLflow logging.

    Attributes:
        total_trades: Total number of trades executed
        winning_trades: Number of profitable trades
        losing_trades: Number of losing trades
        draw_trades: Number of break-even trades
        total_profit: Total profit in stake currency
        total_profit_pct: Total profit as percentage
        profit_factor: Ratio of gross profit to gross loss
        sharpe_ratio: Risk-adjusted return metric
        sortino_ratio: Downside risk-adjusted return
        calmar_ratio: Return over max drawdown
        sqn: System Quality Number
        cagr: Compound Annual Growth Rate
        max_drawdown: Maximum drawdown in stake currency
        max_drawdown_pct: Maximum drawdown as percentage
        win_rate: Percentage of winning trades
        metrics: Additional custom metrics
        trades: Raw trade data (limited)
        raw_stats: Full raw stats from Freqtrade
        mlflow_run_id: MLflow run ID for traceability
        config_artifact_uri: URI of config artifact in MLflow
        results_artifact_uri: S3 URI of results file
        job_id: DynamoDB job ID for reverse lookup
        git_commit: Git commit SHA for reproducibility
        resolved_strategy_version: Resolved MLflow version number
        config_version_id: ConfigVersion ID used for this backtest
    """

    # Trade summary
    total_trades: int = Field(ge=0)
    winning_trades: int = Field(ge=0)
    losing_trades: int = Field(default=0, ge=0)
    draw_trades: int = Field(default=0, ge=0)

    # Profit metrics
    total_profit: float = Field(default=0.0)
    total_profit_pct: float = Field(default=0.0)
    profit_factor: float | None = Field(default=None, ge=0)
    expectancy: float | None = Field(default=None)
    expectancy_ratio: float | None = Field(default=None)

    # Risk ratios (Freqtrade 2023.1+)
    sharpe_ratio: float | None = Field(default=None)
    sortino_ratio: float | None = Field(default=None)
    calmar_ratio: float | None = Field(default=None)
    sqn: float | None = Field(default=None)  # System Quality Number
    cagr: float | None = Field(default=None)  # Compound Annual Growth Rate

    # Drawdown metrics
    max_drawdown: float | None = Field(default=None)
    max_drawdown_pct: float | None = Field(default=None)
    drawdown_start: str | None = Field(default=None)
    drawdown_end: str | None = Field(default=None)

    # Trade durations
    avg_trade_duration: str | None = Field(default=None)
    winning_avg_duration: str | None = Field(default=None)
    losing_avg_duration: str | None = Field(default=None)

    # Win rate
    win_rate: float | None = Field(default=None, ge=0.0, le=1.0)

    # Best/worst performance
    best_pair: str | None = Field(default=None)
    worst_pair: str | None = Field(default=None)
    best_trade_profit: float | None = Field(default=None)
    worst_trade_profit: float | None = Field(default=None)

    # Additional metrics dict (for MLflow logging)
    metrics: dict[str, float] = Field(default_factory=dict)

    # Raw trades (limited to prevent memory issues)
    # Expected keys: pair, profit_ratio, profit_abs, open_date, close_date,
    # trade_duration, is_open, is_short, open_rate, close_rate, leverage
    trades: list[dict[str, Any]] = Field(default_factory=list)

    # Full raw stats from Freqtrade (for complete logging)
    raw_stats: dict[str, Any] = Field(default_factory=dict)

    # MLflow traceability fields (SS010/BE010)
    mlflow_run_id: str | None = Field(default=None, description="MLflow run ID for traceability")
    config_artifact_uri: str | None = Field(
        default=None, description="URI of uploaded config artifact in MLflow"
    )
    results_artifact_uri: str | None = Field(default=None, description="S3 URI of results file")

    # E2E traceability fields (P1.2/P1.3)
    job_id: str | None = Field(default=None, description="DynamoDB job ID for reverse lookup")
    git_commit: str | None = Field(default=None, description="Git commit SHA for reproducibility")

    # Internal run correlation (S3 paths and MLflow tags)
    tradai_run_id: str | None = Field(
        default=None, description="Internal run ID used for S3 paths and MLflow tags"
    )

    # Strategy versioning traceability (V-003)
    resolved_strategy_version: str | None = Field(
        default=None, description="Resolved MLflow version number (e.g., '3')"
    )
    config_version_id: str | None = Field(
        default=None, description="ConfigVersion ID used for this backtest"
    )

    # Exchange traceability
    exchange: str | None = Field(default=None, description="Exchange key (e.g., 'binance_futures')")

    model_config = {"frozen": True}

    @field_validator("winning_trades")
    @classmethod
    def validate_winning_trades(cls, v: int, info: Any) -> int:
        """Ensure winning trades <= total trades."""
        if "total_trades" in info.data and v > info.data["total_trades"]:
            raise ValueError("winning_trades cannot exceed total_trades")
        return v

    @field_validator("git_commit")
    @classmethod
    def validate_git_commit(cls, v: str | None) -> str | None:
        """Validate git commit SHA format (P1.3).

        Accepts:
        - None (no git info available)
        - "unknown" (not in a git repository)
        - 7-char short SHA (e.g., "abc1234")
        - 40-char full SHA (e.g., "abc1234567890...")
        """
        if v is None or v == "unknown":
            return v
        if len(v) not in (7, 40):
            raise ValueError(f"Invalid git commit SHA length: {len(v)} (expected 7 or 40)")
        if not all(c in "0123456789abcdef" for c in v.lower()):
            raise ValueError(f"Invalid git commit SHA (not hex): {v}")
        return v

    @classmethod
    def from_mlflow_metrics(
        cls,
        metrics: dict[str, float],
        mlflow_run_id: str,
        config_artifact_uri: str | None = None,
    ) -> BacktestResult:
        """Create BacktestResult from MLflow run metrics dict.

        Extracts standard metric keys from MLflow's flat metrics dictionary.

        Args:
            metrics: MLflow run metrics (e.g., run.data.metrics)
            mlflow_run_id: MLflow run ID for traceability
            config_artifact_uri: Optional URI of config artifact

        Returns:
            BacktestResult with metrics populated from the dict

        Example:
            >>> run = mlflow_client.get_run(run_id)
            >>> result = BacktestResult.from_mlflow_metrics(
            ...     run.data.metrics, run_id
            ... )
        """
        return cls(
            total_trades=int(metrics.get("total_trades", 0)),
            winning_trades=int(metrics.get("winning_trades", 0)),
            losing_trades=int(metrics.get("losing_trades", 0)),
            total_profit=metrics.get("total_profit", 0.0),
            total_profit_pct=metrics.get("total_profit_pct", 0.0),
            sharpe_ratio=metrics.get("sharpe_ratio"),
            profit_factor=metrics.get("profit_factor"),
            win_rate=metrics.get("win_rate"),
            max_drawdown_pct=metrics.get("max_drawdown"),
            mlflow_run_id=mlflow_run_id,
            config_artifact_uri=config_artifact_uri,
        )