Common Entities¶

class Strategy(BaseModel):
    """Trading strategy entity.

    Represents a registered trading strategy with its metadata.

    Attributes:
        name: Strategy name (alphanumeric, underscores, hyphens)
        version: Semantic version (e.g., "1.0.0" or "v1.0.0")
        ecr_url: ECR image URL for deployment
        created_at: Creation timestamp
        tags: Optional metadata tags

    Example:
        >>> strategy = Strategy(
        ...     name="PascalStrategy",
        ...     version="2.0.0",
        ...     ecr_url="123456789.dkr.ecr.eu-central-1.amazonaws.com/tradai-strategies:pascal-2.0.0"
        ... )
    """

    name: str = Field(..., min_length=1, max_length=100, pattern=r"^[a-zA-Z0-9_-]+$")
    version: str = Field(..., pattern=r"^v?\d+\.\d+\.\d+$")
    ecr_url: str = Field(..., description="ECR image URL")
    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
    tags: dict[str, str] = Field(default_factory=dict)

    model_config = {"frozen": True}  # Immutable

    @field_validator("ecr_url")
    @classmethod
    def validate_ecr_url(cls, v: str) -> str:
        """Validate ECR URL format."""
        if ".dkr.ecr." not in v or ".amazonaws.com/" not in v:
            raise ValueError("ecr_url must be a valid ECR URL")
        return 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)
    stake_currency: str = Field(
        default="USDT",
        min_length=1,
        description="Stake currency (e.g., 'USDT', 'BTC')",
    )

    # 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",
    )

    # FreqAI model override (required for FreqAI strategies)
    freqai_model: str | None = Field(
        default=None,
        description="FreqAI model class name (e.g., 'LightGBMRegressor'). Required for FreqAI strategies.",
    )

    # 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("task_definition")
    @classmethod
    def validate_task_definition(cls, v: str | None) -> str | None:
        """Restrict task_definition to the tradai-strategy naming convention.

        Accepts family name (with optional `:revision`) and full ARN form.
        Prevents arbitrary task definition injection via untrusted config sources.
        """
        if v is None:
            return v
        # Slug from strategy_name_to_slug may contain underscores (e.g., "my_strategy_v2");
        # ECS task definition family allows [a-zA-Z0-9_-]. Require lowercase here to match slug output.
        pattern = (
            r"^(arn:aws:ecs:[a-z0-9-]+:\d+:task-definition/)?"
            r"tradai-strategy-[a-z0-9][a-z0-9_-]*"
            r"(:\d+)?$"
        )
        if not re.match(pattern, v):
            raise ValueError(
                f"Invalid task_definition {v!r}: must match "
                "'tradai-strategy-<slug>[-<env>][:<revision>]' "
                "or full ECS task-definition ARN"
            )
        return v

    @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,
        description="Maximum drawdown as positive percentage (e.g., 15.0 means 15%).",
    )
    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("max_drawdown_pct", mode="before")
    @classmethod
    def normalize_drawdown_sign(cls, v: float | None) -> float | None:
        """Normalize max_drawdown_pct to positive percentage."""
        if v is not None:
            return abs(v)
        return v

    @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=extract_drawdown_pct(metrics),
            mlflow_run_id=mlflow_run_id,
            config_artifact_uri=config_artifact_uri,
        )

class ConfigVersion(DynamoDBSerializableMixin):
    """Immutable config version entity with DynamoDB serialization.

    Content-addressable versioning using SHA256 hash for deduplication.
    Follows existing patterns:
    - frozen=True for immutability (like BacktestJobStatus)
    - with_status() for state transitions
    - DynamoDBSerializableMixin provides to_dynamodb_item()/from_dynamodb_item()
    - ClassVar for constants (not dict)

    DynamoDB Schema:
        PK: strategy_name
        SK: config_id
        GSIs:
            - status-index (PK: strategy_name, SK: status) for get_active
            - config_hash-index (PK: config_hash) for deduplication

    Example:
        >>> version = ConfigVersion(
        ...     strategy_name="PascalStrategy",
        ...     config_id="v1-abc12345",
        ...     config_hash="a" * 64,
        ...     config_data={"timeframe": "1h"},
        ...     version_number=1,
        ... )
        >>> activated = version.with_status(ConfigVersionStatus.ACTIVE)
        >>> activated.deployed_at  # Set automatically
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    # Keys
    strategy_name: str = Field(..., description="Partition key")
    config_id: str = Field(..., description="Sort key: v{version}-{hash[:8]}")

    # Content-addressable
    config_hash: str = Field(..., description="SHA256 of normalized config content")
    config_data: dict[str, Any] = Field(default_factory=dict, description="Frozen config content")

    # Lifecycle
    status: ConfigVersionStatus = Field(default=ConfigVersionStatus.DRAFT)
    version_number: int = Field(ge=1, description="Sequential version per strategy")

    # Metadata
    description: str = Field(default="", description="Version description")
    created_by: str = Field(default="system", description="User/system that created version")
    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
    deployed_at: datetime | None = Field(default=None, description="When activated")
    deprecated_at: datetime | None = Field(default=None, description="When deprecated")
    superseded_by: str | None = Field(default=None, description="config_id of newer version")
    ttl: int | None = Field(default=None, description="Unix epoch for DynamoDB auto-cleanup")

    # Constants (ClassVar, not PrivateAttr)
    _TTL_DAYS: ClassVar[int] = 90

    @field_validator("config_hash")
    @classmethod
    def validate_hash(cls, v: str) -> str:
        """Validate SHA256 format and normalize to lowercase.

        Args:
            v: Hash string to validate

        Returns:
            Lowercase normalized hash

        Raises:
            ValueError: If hash is not valid SHA256 (64 hex chars)
        """
        if len(v) != 64:
            raise ValueError(f"Invalid SHA256 hash: length {len(v)}, expected 64")
        if not all(c in "0123456789abcdefABCDEF" for c in v):
            raise ValueError(f"Invalid SHA256 hash: non-hex characters in {v}")
        return v.lower()

    def with_status(self, status: ConfigVersionStatus) -> ConfigVersion:
        """Return new instance with updated status (immutable update pattern).

        Automatically sets:
        - deployed_at when transitioning to ACTIVE
        - deprecated_at and ttl when transitioning to DEPRECATED

        Args:
            status: New status

        Returns:
            New ConfigVersion with updated status
        """
        updates: dict[str, Any] = {"status": status}

        if status == ConfigVersionStatus.ACTIVE:
            updates["deployed_at"] = datetime.now(UTC)
        elif status == ConfigVersionStatus.DEPRECATED:
            updates["deprecated_at"] = datetime.now(UTC)
            # Set TTL for auto-cleanup
            updates["ttl"] = int(datetime.now(UTC).timestamp() + (self._TTL_DAYS * 86400))

        return ConfigVersion(**{**self.model_dump(), **updates})

class ConfigVersionStatus(str, Enum):
    """Config version lifecycle status.

    Lifecycle: DRAFT → ACTIVE → DEPRECATED

    - DRAFT: Not yet validated/deployed
    - ACTIVE: Currently deployed (only one per strategy)
    - DEPRECATED: Superseded by newer version (auto-cleanup via TTL)
    """

    DRAFT = "draft"
    ACTIVE = "active"
    DEPRECATED = "deprecated"

    @property
    def is_terminal(self) -> bool:
        """DEPRECATED is terminal (no further transitions)."""
        return self == ConfigVersionStatus.DEPRECATED

    @property
    def is_active(self) -> bool:
        """Only ACTIVE versions are deployable."""
        return self == ConfigVersionStatus.ACTIVE

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")

        try:
            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", "")),
            )
        except KeyError as e:
            raise ValidationError(f"Missing required secret field: {e.args[0]}") from e

    @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)}")