"""Project exception hierarchy.

All exceptions raised by AI MusiMuse inherit from ``AIMusiMuseError``.
Each exception class corresponds to a specific category of failure,
making it possible to catch errors at the appropriate granularity.
"""


class AIMusiMuseError(Exception):
    """Base exception for all AI MusiMuse errors.

    Every other project exception inherits from this class.  Catching
    ``AIMusiMuseError`` is sufficient to handle any error originating
    from the application.
    """


class ConfigurationError(AIMusiMuseError):
    """Raised when runtime configuration is invalid or incomplete."""


class DatabaseError(AIMusiMuseError):
    """Raised when a database operation fails."""


class AnalysisError(AIMusiMuseError):
    """Raised when an analysis pipeline operation fails."""


class PluginError(AIMusiMuseError):
    """Raised when a plugin fails to load, validate, or execute."""


class ValidationError(AIMusiMuseError):
    """Raised when input data fails validation."""


class DecodingError(AIMusiMuseError):
    """Raised when an audio file cannot be decoded."""