ml/exceptions

lilith-ml-exceptions

ML-specific exception classes and HTTP status mappers for FastAPI applications.

Features

• Typed Exceptions: Specific exception classes for ML operations
• HTTP Mapping: Automatic HTTP status code mapping
• Serialization: Convert exceptions to API-friendly dictionaries
• FastAPI Integration: Exception handlers for FastAPI apps
• Zero Dependencies: Core package has no runtime dependencies

Installation

pip install lilith-ml-exceptions

With FastAPI integration:

pip install lilith-ml-exceptions[fastapi]

Quick Start

from lilith_ml_exceptions import (
    ModelLoadError,
    InferenceError,
    ValidationError,
    ResourceError,
    exception_to_http_status,
    create_exception_handler,
)

# Raise specific exceptions
raise ModelLoadError(
    "Failed to load model",
    model_name="gpt-4",
    model_path="/models/gpt-4.bin",
)

raise InferenceError(
    "Inference timeout",
    model_name="llama-3",
    timeout_seconds=30.0,
)

raise ValidationError(
    "Invalid input format",
    field="prompt",
    expected_type="string",
    received_value=123,
)

raise ResourceError(
    "Insufficient GPU memory",
    resource_type="VRAM",
    required_amount="16GB",
    available_amount="8GB",
)

Exception Classes

MLBaseError

Base class for all ML exceptions with common functionality.

class MLBaseError(Exception):
    error_code: str = "ML_ERROR"

    def __init__(
        self,
        message: str,
        *,
        details: dict[str, Any] | None = None,
        cause: Exception | None = None,
    ): ...

    def to_dict(self) -> dict[str, Any]: ...

ModelLoadError

Raised when a model cannot be loaded.

raise ModelLoadError(
    "Model file not found",
    model_name="mistral-7b",
    model_path="/models/mistral-7b.gguf",
    cause=FileNotFoundError("/models/mistral-7b.gguf"),
)

# error_code: "MODEL_LOAD_ERROR"

Common causes:

• Model file not found
• Corrupt model file
• Incompatible model format or version
• Insufficient memory to load model

InferenceError

Raised when model inference fails.

raise InferenceError(
    "Out of memory during inference",
    model_name="stable-diffusion-xl",
    input_shape=(1, 3, 1024, 1024),
    cause=RuntimeError("CUDA out of memory"),
)

# error_code: "INFERENCE_ERROR"

Common causes:

• Out of memory (OOM)
• Timeout during inference
• Invalid input data format
• Model computation error

ValidationError

Raised when input validation fails.

raise ValidationError(
    "Prompt exceeds maximum length",
    field="prompt",
    expected_type="string",
    received_value="...",
    constraints={"max_length": 4096, "actual_length": 5000},
)

# error_code: "VALIDATION_ERROR"

Common causes:

• Invalid input format
• Missing required fields
• Value out of acceptable range
• Type mismatch

ResourceError

Raised when required resources are unavailable.

raise ResourceError(
    "GPU not available",
    resource_type="GPU",
    required_amount="1 GPU",
    available_amount="0 GPUs",
)

# error_code: "RESOURCE_ERROR"

Common causes:

• GPU not available
• Insufficient VRAM
• Insufficient system memory
• Required service unavailable

HTTP Mapping

exception_to_http_status(exception)

Map exceptions to HTTP status codes.

from lilith_ml_exceptions import exception_to_http_status

status = exception_to_http_status(ModelLoadError("..."))  # 500
status = exception_to_http_status(ValidationError("..."))  # 400
status = exception_to_http_status(ResourceError("..."))  # 503

Exception	HTTP Status
ValidationError	400 Bad Request
ModelLoadError	500 Internal Server Error
InferenceError	500 Internal Server Error
ResourceError	503 Service Unavailable
MLBaseError	500 Internal Server Error

exception_to_response(exception)

Convert exception to API response dictionary.

from lilith_ml_exceptions import exception_to_response

response = exception_to_response(error)
# {
#     "error_code": "MODEL_LOAD_ERROR",
#     "message": "Failed to load model",
#     "details": {"model_name": "gpt-4"},
# }

FastAPI Integration

create_exception_handler()

Create a FastAPI exception handler for ML exceptions.

from fastapi import FastAPI
from lilith_ml_exceptions import create_exception_handler, MLBaseError

app = FastAPI()

# Register the exception handler
app.add_exception_handler(MLBaseError, create_exception_handler())

@app.post("/generate")
async def generate(prompt: str):
    # Exceptions are automatically converted to HTTP responses
    raise InferenceError("Model timeout", timeout_seconds=30)

Response:

{
  "error_code": "INFERENCE_ERROR",
  "message": "Model timeout",
  "details": {
    "timeout_seconds": 30
  }
}

Serialization

All exceptions support serialization via to_dict():

error = ModelLoadError(
    "Failed to load model",
    model_name="llama-3",
    model_path="/models/llama-3.gguf",
    cause=FileNotFoundError("File not found"),
)

error.to_dict()
# {
#     "error_code": "MODEL_LOAD_ERROR",
#     "message": "Failed to load model",
#     "details": {
#         "model_name": "llama-3",
#         "model_path": "/models/llama-3.gguf",
#     },
#     "cause": "File not found",
# }

License

MIT