sort_function.py

"""
PackageSorter - Core Sorting Function

This module implements the core sorting logic for Thoughtful's robotic automation factory.
The function dispatches packages to the correct stack based on their volume and mass.

Technical Specification:
- STANDARD: Packages that are neither bulky nor heavy (handled automatically)
- SPECIAL: Packages that are either bulky OR heavy (require manual handling)
- REJECTED: Packages that are both bulky AND heavy (cannot be processed)

Classification Rules:
- Bulky: volume >= 1,000,000 cm³ OR any dimension >= 150 cm
- Heavy: mass >= 20 kg
"""


def sort(width: float, height: float, length: float, mass: float) -> str:
    """
    Sort packages based on dimensions and mass for robotic dispatch.

    This function determines which stack a package should be dispatched to
    based on its physical properties.

    Args:
        width: Package width in centimeters (cm)
        height: Package height in centimeters (cm)
        length: Package length in centimeters (cm)
        mass: Package mass in kilograms (kg)

    Returns:
        str: Stack name - "STANDARD", "SPECIAL", or "REJECTED"

    Raises:
        ValueError: If any dimension or mass is negative or zero
        TypeError: If arguments are not numeric

    Examples:
        >>> sort(10, 10, 10, 5)
        'STANDARD'

        >>> sort(50, 50, 50, 25)
        'SPECIAL'

        >>> sort(200, 100, 100, 30)
        'REJECTED'
    """
    # Input validation
    if not all(isinstance(arg, (int, float)) for arg in [width, height, length, mass]):
        raise TypeError("All arguments must be numeric (int or float)")

    if width <= 0 or height <= 0 or length <= 0 or mass <= 0:
        raise ValueError("All dimensions and mass must be positive values")

    # Calculate volume
    volume = width * height * length

    # Determine if package is bulky using ternary operator
    is_bulky = (
        True if (volume >= 1_000_000 or
                width >= 150 or
                height >= 150 or
                length >= 150)
        else False
    )

    # Determine if package is heavy using ternary operator
    is_heavy = True if mass >= 20 else False

    # Classify package using ternary operator
    category = (
        "REJECTED" if (is_bulky and is_heavy) else
        "SPECIAL" if (is_bulky or is_heavy) else
        "STANDARD"
    )

    return category


# Additional helper function for detailed classification info
def sort_detailed(width: float, height: float, length: float, mass: float) -> dict:
    """
    Sort packages with detailed classification information.

    Returns a dictionary with the classification result and additional details
    about why the package was classified in that category.

    Args:
        width: Package width in centimeters
        height: Package height in centimeters
        length: Package length in centimeters
        mass: Package mass in kilograms

    Returns:
        dict: Classification details including category, volume, flags, and reasons

    Example:
        >>> result = sort_detailed(160, 50, 50, 15)
        >>> result['category']
        'SPECIAL'
        >>> result['is_bulky']
        True
        >>> result['reasons']
        ['Height >= 150 cm']
    """
    # Input validation
    if not all(isinstance(arg, (int, float)) for arg in [width, height, length, mass]):
        raise TypeError("All arguments must be numeric (int or float)")

    if width <= 0 or height <= 0 or length <= 0 or mass <= 0:
        raise ValueError("All dimensions and mass must be positive values")

    # Calculate properties
    volume = width * height * length
    is_bulky = volume >= 1_000_000 or width >= 150 or height >= 150 or length >= 150
    is_heavy = mass >= 20

    # Determine classification
    category = sort(width, height, length, mass)

    # Build reasons list
    reasons = []
    if volume >= 1_000_000:
        reasons.append(f"Volume {volume:,.0f} cm³ >= 1,000,000 cm³")
    if width >= 150:
        reasons.append(f"Width {width} cm >= 150 cm")
    if height >= 150:
        reasons.append(f"Height {height} cm >= 150 cm")
    if length >= 150:
        reasons.append(f"Length {length} cm >= 150 cm")
    if mass >= 20:
        reasons.append(f"Mass {mass} kg >= 20 kg")

    if not reasons:
        reasons.append("Package meets standard criteria")

    return {
        "category": category,
        "volume": volume,
        "is_bulky": is_bulky,
        "is_heavy": is_heavy,
        "dimensions": {
            "width": width,
            "height": height,
            "length": length
        },
        "mass": mass,
        "reasons": reasons
    }


if __name__ == "__main__":
    # Demo examples
    print("PackageSorter - Core Function Demonstration\n")
    print("=" * 60)

    test_cases = [
        ("Small Box", 10, 10, 10, 5),
        ("Heavy Box", 50, 50, 50, 25),
        ("Bulky Box (dimension)", 160, 50, 50, 15),
        ("Bulky Box (volume)", 120, 110, 90, 18),
        ("Rejected Package", 200, 100, 100, 30),
        ("Edge Case (exactly 150cm)", 150, 50, 50, 15),
        ("Edge Case (exactly 20kg)", 50, 50, 50, 20),
    ]

    for name, w, h, l, m in test_cases:
        result = sort(w, h, l, m)
        volume = w * h * l
        print(f"\n{name}:")
        print(f"  Dimensions: {w}×{h}×{l} cm (volume: {volume:,} cm³)")
        print(f"  Mass: {m} kg")
        print(f"  → Result: {result}")

    print("\n" + "=" * 60)
    print("\nDetailed classification example:")
    print("=" * 60)
    detailed = sort_detailed(160, 50, 50, 15)
    print(f"\nCategory: {detailed['category']}")
    print(f"Volume: {detailed['volume']:,} cm³")
    print(f"Bulky: {detailed['is_bulky']}")
    print(f"Heavy: {detailed['is_heavy']}")
    print(f"Reasons: {', '.join(detailed['reasons'])}")