altametris.sara.core.exceptions
===============================

.. py:module:: altametris.sara.core.exceptions

.. autoapi-nested-parse::

   Custom exceptions for Altametris libraries.

   Provides a hierarchy of exceptions for different error scenarios:
   - AltametrisException: Base exception
   - ModelError: Model-related errors (loading, architecture, weights)
   - TrainingError: Training-related errors (dataset, convergence, OOM)
   - InferenceError: Inference-related errors (input format, device)
   - ExportError: Export-related errors (format, validation)
   - ConfigurationError: Configuration-related errors (invalid parameters)



Exceptions
----------

.. autoapisummary::

   altametris.sara.core.exceptions.AltametrisException
   altametris.sara.core.exceptions.ModelError
   altametris.sara.core.exceptions.TrainingError
   altametris.sara.core.exceptions.InferenceError
   altametris.sara.core.exceptions.ExportError
   altametris.sara.core.exceptions.ConfigurationError


Functions
---------

.. autoapisummary::

   altametris.sara.core.exceptions.validate_param


Module Contents
---------------

.. py:exception:: AltametrisException(message: str, details: Optional[dict[str, Any]] = None)

   Bases: :py:obj:`Exception`


   Base exception for all Altametris libraries.

   All custom exceptions inherit from this base class to allow
   catching all Altametris-specific errors with a single except clause.

   :param message: Error message describing what went wrong
   :param details: Optional dictionary with additional error context

   .. rubric:: Example

   >>> try:
   ...     raise AltametrisException("Something went wrong", {"code": 500})
   ... except AltametrisException as e:
   ...     print(e)
   ...     print(e.details)


   .. py:attribute:: message


   .. py:attribute:: details


   .. py:method:: __str__() -> str

      Return string representation of exception.



   .. py:method:: __repr__() -> str

      Return repr representation of exception.



.. py:exception:: ModelError(message: str, details: Optional[dict[str, Any]] = None)

   Bases: :py:obj:`AltametrisException`


   Exception raised for model-related errors.

   Scenarios:
   - Failed to load model weights
   - Invalid model architecture
   - Corrupted checkpoint file
   - Incompatible model version
   - Missing required model files

   .. rubric:: Example

   >>> raise ModelError(
   ...     "Failed to load weights",
   ...     {"path": "model.pt", "reason": "File not found"}
   ... )


.. py:exception:: TrainingError(message: str, details: Optional[dict[str, Any]] = None)

   Bases: :py:obj:`AltametrisException`


   Exception raised for training-related errors.

   Scenarios:
   - Dataset not found or invalid format
   - Training divergence (NaN loss)
   - Out of memory during training
   - Invalid hyperparameters
   - Checkpoint save failure

   .. rubric:: Example

   >>> raise TrainingError(
   ...     "Training diverged",
   ...     {"epoch": 10, "loss": float('nan'), "lr": 0.001}
   ... )


.. py:exception:: InferenceError(message: str, details: Optional[dict[str, Any]] = None)

   Bases: :py:obj:`AltametrisException`


   Exception raised for inference-related errors.

   Scenarios:
   - Invalid input format (wrong shape, type)
   - Device mismatch (model on CUDA, input on CPU)
   - Prediction failure
   - Post-processing error
   - Batch size too large for memory

   .. rubric:: Example

   >>> raise InferenceError(
   ...     "Invalid input shape",
   ...     {"expected": (3, 640, 640), "got": (640, 640)}
   ... )


.. py:exception:: ExportError(message: str, details: Optional[dict[str, Any]] = None)

   Bases: :py:obj:`AltametrisException`


   Exception raised for export-related errors.

   Scenarios:
   - Unsupported export format
   - Export validation failed
   - Missing export dependencies (onnx, tensorrt)
   - Dynamic shapes not supported
   - Export optimization failed

   .. rubric:: Example

   >>> raise ExportError(
   ...     "ONNX export failed",
   ...     {"format": "onnx", "reason": "Dynamic axes not supported"}
   ... )


.. py:exception:: ConfigurationError(message: str, details: Optional[dict[str, Any]] = None)

   Bases: :py:obj:`AltametrisException`


   Exception raised for configuration-related errors.

   Scenarios:
   - Invalid configuration parameter
   - Missing required configuration key
   - Configuration validation failed
   - Incompatible configuration values
   - Invalid YAML/JSON format

   .. rubric:: Example

   >>> raise ConfigurationError(
   ...     "Invalid batch_size",
   ...     {"parameter": "batch_size", "value": -1, "expected": "> 0"}
   ... )


.. py:function:: validate_param(condition: bool, param_name: str, value: Any, expected: str) -> None

   Validate a parameter and raise ConfigurationError if invalid.

   :param condition: Condition that must be True (if False, raises exception)
   :param param_name: Name of the parameter being validated
   :param value: Current value of the parameter
   :param expected: Description of expected value

   :raises ConfigurationError: If condition is False

   .. rubric:: Example

   >>> validate_param(batch_size > 0, "batch_size", batch_size, "> 0")
   >>> validate_param(device in ["cpu", "cuda"], "device", device, "cpu or cuda")