"""Input validation utilities for SDK methods.

This module provides minimal validation helpers that catch obvious user errors
before making network requests. Validation is kept lightweight - the server
remains the authoritative validator for business logic constraints.

What to validate:
    - Required parameters are not None/empty
    - Basic type correctness (list vs string)
    - Obvious bounds that prevent network round-trips (e.g., top_n > 0)

What NOT to validate:
    - Model names, dimension ranges, format patterns (server decides)
    - Complex business logic constraints
    - Exhaustive input checking
"""

from __future__ import annotations

from typing import Any


def require_non_empty(name: str, value: str | list[Any] | None) -> None:
    """Raise ValueError if value is None, empty string, or empty list.

    Args:
        name: Parameter name for error message
        value: Value to check

    Raises:
        ValueError: If value is None, empty string, or empty list

    Example:
        >>> require_non_empty("model", "multilingual-e5-large")  # OK
        >>> require_non_empty("texts", ["Hello"])  # OK
        >>> require_non_empty("model", "")  # Raises ValueError
        >>> require_non_empty("texts", [])  # Raises ValueError
        >>> require_non_empty("query", None)  # Raises ValueError
    """
    if value is None:
        raise ValueError(f"{name} is required")

    if isinstance(value, str) and not value:
        raise ValueError(f"{name} must be a non-empty string")

    if isinstance(value, list) and not value:
        raise ValueError(f"{name} must be a non-empty list")


def require_in_range(name: str, value: int | None, min_val: int, max_val: int) -> None:
    """Raise ValueError if value is outside [min_val, max_val].

    None is always allowed (for optional parameters).

    Args:
        name: Parameter name for error message
        value: Value to check
        min_val: Minimum allowed value (inclusive)
        max_val: Maximum allowed value (inclusive)

    Raises:
        ValueError: If value is outside the specified range

    Example:
        >>> require_in_range("top_n", 5, 1, 10)  # OK
        >>> require_in_range("top_n", None, 1, 10)  # OK (None allowed)
        >>> require_in_range("top_n", 0, 1, 10)  # Raises ValueError
        >>> require_in_range("top_n", 11, 1, 10)  # Raises ValueError
    """
    if value is None:
        return

    if not (min_val <= value <= max_val):
        raise ValueError(f"{name} must be between {min_val} and {max_val}, got {value}")
