"""API utility helpers."""
from __future__ import annotations

from typing import NoReturn

from fastapi import HTTPException

from crystallise.llm.errors import RETRYABLE_CATEGORIES, classify_openai_error


def classify_and_raise(exc: Exception) -> NoReturn:
    """Classify an LLM/OpenAI error and raise an appropriate HTTPException.

    Maps error categories to HTTP status codes:
        rate_limit → 429, auth → 401, validation → 400, others → 500
    """
    category = classify_openai_error(exc)
    status_map = {"rate_limit": 429, "auth": 401, "validation": 400}
    status_code = status_map.get(category.value, 500)
    raise HTTPException(
        status_code=status_code,
        detail={
            "message": str(exc),
            "error_code": category.value,
            "retryable": category in RETRYABLE_CATEGORIES,
        },
    )