"""
Math utilities module.

Provides basic arithmetic operations with type hints and documentation.
"""

from typing import NamedTuple, Union

Number = Union[int, float]


class AddResult(NamedTuple):
    """Result of adding multiple numbers.
    
    Attributes:
        value: The sum of all operands
        operands: The original numbers that were added
    """
    value: Number
    operands: list[Number]


def add(a: Number, b: Number) -> Number:
    """Add two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        The sum of a and b
        
    Example:
        >>> add(1, 2)
        3
        >>> add(1.5, 2.5)
        4.0
    """
    return a + b


def add_many(*numbers: Number) -> AddResult:
    """Add multiple numbers together.
    
    Args:
        *numbers: Variable number of numbers to add
        
    Returns:
        An AddResult namedtuple containing the sum and the operands
        
    Raises:
        ValueError: If no numbers are provided
        
    Example:
        >>> result = add_many(1, 2, 3, 4, 5)
        >>> result.value
        15
        >>> result.operands
        [1, 2, 3, 4, 5]
    """
    if not numbers:
        raise ValueError("At least one number is required")
    
    total = sum(numbers)
    return AddResult(value=total, operands=list(numbers))
