# SPDX-License-Identifier: AGPL-3.0-or-later | Commercial license available
# Â© Concepts 1996â€“2026 Miroslav Ĺ otek. All rights reserved.
# Â© Code 2020â€“2026 Miroslav Ĺ otek. All rights reserved.
# ORCID: 0009-0009-3560-0851
# Contact: www.anulum.li | protoscience@anulum.li
# Director-Class AI â€” Exception Hierarchy

"""Structured exception hierarchy for Director-Class AI.

All library-specific exceptions descend from ``DirectorAIError`` so
callers can catch the entire family with a single except clause.
"""


class DirectorAIError(Exception):
    """Base exception for all Director-Class AI errors."""


class CoherenceError(DirectorAIError):
    """Raised when the coherence pipeline encounters a fatal scoring error."""


class KernelHaltError(DirectorAIError):
    """Raised when the safety kernel triggers an emergency halt."""


class GeneratorError(DirectorAIError):
    """Raised when candidate generation fails unrecoverably."""


class ValidationError(DirectorAIError, ValueError):
    """Raised for invalid inputs (prompts, parameters, configs)."""


class DependencyError(DirectorAIError):
    """Raised when an optional dependency is missing or broken."""


class PhysicsError(DirectorAIError):
    """Raised when the research physics modules encounter a fatal error."""


class NumericalError(PhysicsError):
    """Raised when a numerical computation produces NaN/Inf."""


class HallucinationError(DirectorAIError):
    """Raised when a guarded LLM response fails coherence scoring."""

    def __init__(self, query: str, response: str, score):
        self.query = query
        self.response = response
        self.score = score
        super().__init__(
            f"Hallucination detected (coherence={score.score:.3f}): {response[:100]}",
        )
