Exceptions

class EvolutionError(Exception):
    """Base exception for all gepa-adk errors.

    All custom exceptions in gepa-adk should inherit from this class
    to allow for unified exception handling.

    Examples:
        Catching evolution errors:

        ```python
        from gepa_adk.domain.exceptions import EvolutionError

        try:
            raise EvolutionError("Evolution failed unexpectedly")
        except EvolutionError as e:
            print(f"Caught: {e}")
        # Output: Caught: Evolution failed unexpectedly
        ```

    Note:
        Always use this base class or its subclasses for domain errors.
        Standard Python exceptions should still be raised for programming
        errors (e.g., TypeError, ValueError for developer mistakes).
    """

class ConfigurationError(EvolutionError):
    """Raised when configuration validation fails.

    This exception is raised during EvolutionConfig initialization
    when a parameter violates its validation constraints.

    Attributes:
        field (str | None): The name of the configuration field that failed
            validation.
        value (object): The invalid value that was provided.
        constraint (str | None): Description of the validation constraint that
            was violated.

    Examples:
        Creating a configuration error with context:

        ```python
        from gepa_adk.domain.exceptions import ConfigurationError

        error = ConfigurationError(
            "max_iterations must be non-negative",
            field="max_iterations",
            value=-5,
            constraint=">= 0",
        )
        print(error.field, error.value, error.constraint)
        # Output: max_iterations -5 >= 0
        ```

    Note:
        Arises from user-provided invalid settings, not programming errors.
        Should be caught and reported with clear guidance on valid values.
    """

    def __init__(
        self,
        message: str,
        *,
        field: str | None = None,
        value: object = None,
        constraint: str | None = None,
    ) -> None:
        """Initialize ConfigurationError with context.

        Args:
            message: Human-readable error description.
            field: Name of the invalid configuration field.
            value: The invalid value provided.
            constraint: Description of the validation constraint.

        Note:
            Context fields use keyword-only syntax to ensure explicit labeling
            and prevent positional argument mistakes.
        """
        super().__init__(message)
        self.field = field
        self.value = value
        self.constraint = constraint

    def __str__(self) -> str:
        """Return string representation with context.

        Returns:
            Formatted error message including field and value context.

        Note:
            Outputs formatted error message with field and value context
            when available, preserving base message structure.
        """
        base = super().__str__()
        context_parts = []
        if self.field is not None:
            context_parts.append(f"field={self.field!r}")
        if self.value is not None:
            context_parts.append(f"value={self.value!r}")
        if context_parts:
            return f"{base} [{', '.join(context_parts)}]"
        return base

class NoCandidateAvailableError(EvolutionError):
    """Raised when no candidates are available for selection.

    Attributes:
        cause (Exception | None): Original exception that caused this error.
        context (dict[str, object]): Extra context (candidate_idx, frontier_type).

    Examples:
        ```python
        raise NoCandidateAvailableError(
            "No candidates available",
            frontier_type="instance",
        )
        ```

    Note:
        Arises when candidate selector cannot find any valid candidates
        from the Pareto frontier, typically due to empty frontier or
        filtering constraints.
    """

    def __init__(
        self,
        message: str,
        *,
        cause: Exception | None = None,
        **context: object,
    ) -> None:
        """Initialize NoCandidateAvailableError with context.

        Args:
            message: Human-readable error description.
            cause: Original exception that caused this error.
            **context: Additional context such as candidate_idx or frontier_type.

        Note:
            Context fields use keyword-only syntax to ensure explicit labeling
            and prevent positional argument mistakes.
        """
        super().__init__(message)
        self.cause = cause
        self.context = context

    def __str__(self) -> str:
        """Return string with context and cause details.

        Returns:
            Formatted error message including context and cause information.

        Note:
            Outputs formatted error message with context dict and cause chain
            when available, preserving base message structure.
        """
        base = super().__str__()
        if self.context:
            ctx_str = ", ".join(f"{k}={v!r}" for k, v in self.context.items())
            base = f"{base} [{ctx_str}]"
        if self.cause:
            base = f"{base} (caused by: {self.cause})"
        return base

class EvaluationError(EvolutionError):
    """Raised when batch evaluation fails.

    This exception indicates failures during agent evaluation,
    such as agent execution errors, timeout, or malformed output.

    Attributes:
        cause (Exception | None): Original exception that caused this error.
        context (dict): Additional context for debugging.

    Examples:
        Wrapping an ADK error:

        ```python
        from gepa_adk.domain.exceptions import EvaluationError

        try:
            result = await runner.run_async(...)
        except ADKError as e:
            raise EvaluationError(
                "Agent execution failed",
                cause=e,
                agent_name="my_agent",
            ) from e
        ```

    Note:
        Always preserves the original cause for debugging while providing
        a consistent interface for error handling.
    """

    def __init__(
        self,
        message: str,
        *,
        cause: Exception | None = None,
        **context: object,
    ) -> None:
        """Initialize EvaluationError with cause and context.

        Args:
            message: Human-readable error description.
            cause: Original exception that caused this error.
            **context: Additional context for debugging (agent_name, etc.).

        Note:
            Context is passed via keyword arguments. Positional arguments
            after message are not allowed.
        """
        super().__init__(message)
        self.cause = cause
        self.context = context

    def __str__(self) -> str:
        """Return string with cause chain if present.

        Returns:
            Formatted message with context and cause information.

        Note:
            Outputs formatted error message with context dict and cause chain
            when available, preserving base message structure.
        """
        base = super().__str__()
        if self.context:
            ctx_str = ", ".join(f"{k}={v!r}" for k, v in self.context.items())
            base = f"{base} [{ctx_str}]"
        if self.cause:
            base = f"{base} (caused by: {self.cause})"
        return base

class AdapterError(EvaluationError):
    """Raised when an adapter operation fails.

    This exception is used by adapter implementations (e.g., ADKAdapter)
    for adapter-specific failures such as session errors or configuration
    issues.

    Examples:
        Raising an adapter error:

        ```python
        from gepa_adk.domain.exceptions import AdapterError

        if not self._session_service:
            raise AdapterError(
                "Session service unavailable",
                adapter="ADKAdapter",
                operation="evaluate",
            )
        ```

    Note:
        AdapterError is a subclass of EvaluationError, so callers can
        catch either for different granularity of error handling.
    """

class RestoreError(AdapterError):
    """Raised when agent restoration fails after evaluation.

    This exception is raised when one or more agent components fail to
    restore to their original state after candidate evaluation. Uses
    best-effort restoration: all components are attempted even if some fail,
    then errors are aggregated into this exception.

    Attributes:
        errors (list[tuple[str, Exception]]): List of (qualified_name, exception)
            pairs for each failed restoration.

    Examples:
        Handling partial restore failures:

        ```python
        from gepa_adk.domain.exceptions import RestoreError

        try:
            adapter._restore_agents(originals)
        except RestoreError as e:
            for qualified_name, error in e.errors:
                print(f"Failed to restore {qualified_name}: {error}")
        ```

        Aggregating restoration failures:

        ```python
        errors = []
        for name, original in originals.items():
            try:
                handler.restore(agent, original)
            except Exception as exc:
                errors.append((name, exc))
        if errors:
            raise RestoreError(
                f"Failed to restore {len(errors)} components",
                errors=errors,
            )
        ```

    Note:
        As a subclass of AdapterError, this exception indicates that the
        agent state may be corrupted and manual intervention may be required
        to reset agents to a known state.
    """

    def __init__(
        self,
        message: str,
        *,
        errors: list[tuple[str, Exception]],
        cause: Exception | None = None,
    ) -> None:
        """Initialize RestoreError with aggregated failures.

        Args:
            message: Human-readable error summary.
            errors: List of (qualified_name, exception) pairs for each failed
                restoration. Must be non-empty when raising this exception.
            cause: Optional underlying cause exception.

        Note:
            Context fields use keyword-only syntax to ensure explicit labeling
            and prevent positional argument mistakes.
        """
        super().__init__(message, cause=cause)
        self.errors = errors

    def __str__(self) -> str:
        """Return string with failed component names.

        Returns:
            Formatted message including list of failed qualified names.

        Note:
            Outputs formatted error message with list of failed qualified
            names, preserving base message structure.
        """
        base = super().__str__()
        failed_names = [name for name, _ in self.errors]
        return f"{base} [failed_components={failed_names}]"

class ScoringError(EvolutionError):
    """Base exception for all scoring-related errors.

    All scoring exceptions inherit from this class to allow for unified
    exception handling in scoring operations.

    Attributes:
        cause (Exception | None): Original exception that caused this error.

    Examples:
        Catching scoring errors:

        ```python
        from gepa_adk.domain.exceptions import ScoringError

        try:
            score, metadata = await scorer.async_score(...)
        except ScoringError as e:
            print(f"Scoring failed: {e}")
        ```

    Note:
        All scoring exceptions inherit from this base class.
        ScoringError extends EvolutionError, following ADR-009 exception
        hierarchy guidelines.
    """

    def __init__(
        self,
        message: str,
        *,
        cause: Exception | None = None,
    ) -> None:
        """Initialize ScoringError with message and optional cause.

        Args:
            message: Human-readable error description.
            cause: Original exception that caused this error.

        Note:
            Context fields use keyword-only syntax to ensure explicit labeling
            and prevent positional argument mistakes.
        """
        super().__init__(message)
        self.cause = cause

    def __str__(self) -> str:
        """Return string with cause chain if present.

        Returns:
            Formatted message with cause information.

        Note:
            Outputs formatted error message with cause chain when available,
            preserving base message structure.
        """
        base = super().__str__()
        if self.cause:
            base = f"{base} (caused by: {self.cause})"
        return base

class CriticOutputParseError(ScoringError):
    """Raised when critic agent output cannot be parsed as valid JSON.

    This exception indicates that the critic agent returned output that
    could not be parsed as JSON or did not conform to the expected schema.

    Attributes:
        raw_output (str): The unparseable output from critic.
        parse_error (str): Description of parsing failure.

    Examples:
        Handling parse errors:

        ```python
        from gepa_adk.domain.exceptions import CriticOutputParseError

        try:
            score, metadata = await scorer.async_score(...)
        except CriticOutputParseError as e:
            print(f"Invalid JSON: {e.raw_output}")
            print(f"Error: {e.parse_error}")
        ```

    Note:
        Arises when critic agent output cannot be parsed as valid JSON.
        Typically occurs when LLM output doesn't follow structured format
        despite output_schema being set.
    """

    def __init__(
        self,
        message: str,
        *,
        raw_output: str,
        parse_error: str,
        cause: Exception | None = None,
    ) -> None:
        """Initialize CriticOutputParseError with context.

        Args:
            message: Human-readable error description.
            raw_output: The unparseable output string from critic.
            parse_error: Description of the parsing failure.
            cause: Original exception that caused this error.

        Note:
            Context fields use keyword-only syntax to ensure explicit labeling
            and prevent positional argument mistakes.
        """
        super().__init__(message, cause=cause)
        self.raw_output = raw_output
        self.parse_error = parse_error

    def __str__(self) -> str:
        """Return string with parse error details.

        Returns:
            Formatted message including parse error and raw output preview.

        Note:
            Outputs formatted error message with parse error and raw output
            preview (truncated to 100 chars), preserving base message structure.
        """
        base = super().__str__()
        output_preview = (
            self.raw_output[:100] + "..."
            if len(self.raw_output) > 100
            else self.raw_output
        )
        return (
            f"{base} [parse_error={self.parse_error!r}, raw_output={output_preview!r}]"
        )

class OutputParseError(ScoringError):
    """Raised when agent output cannot be parsed as valid JSON.

    This exception indicates that the agent returned output that
    could not be parsed as JSON.

    Attributes:
        raw_output (str): The unparseable output from agent.
        parse_error (str): Description of parsing failure.

    Examples:
        Handling parse errors:

        ```python
        from gepa_adk.domain.exceptions import OutputParseError

        try:
            score, metadata = scorer.score(input_text, output)
        except OutputParseError as e:
            print(f"Invalid JSON: {e.raw_output[:50]}")
            print(f"Error: {e.parse_error}")
        ```

    Note:
        Arises when agent output cannot be parsed as valid JSON.
        Typically occurs when LLM output doesn't follow structured format.
    """

    def __init__(
        self,
        message: str,
        *,
        raw_output: str,
        parse_error: str,
        cause: Exception | None = None,
    ) -> None:
        """Initialize OutputParseError with context.

        Args:
            message: Human-readable error description.
            raw_output: The unparseable output string from agent.
            parse_error: Description of the parsing failure.
            cause: Original exception that caused this error.

        Note:
            Context fields use keyword-only syntax to ensure explicit labeling
            and prevent positional argument mistakes.
        """
        super().__init__(message, cause=cause)
        self.raw_output = raw_output
        self.parse_error = parse_error

    def __str__(self) -> str:
        """Return string with parse error details.

        Returns:
            Formatted message including parse error and raw output preview.

        Note:
            Outputs formatted error message with parse error and raw output
            preview (truncated to 100 chars), preserving base message structure.
        """
        base = super().__str__()
        output_preview = (
            self.raw_output[:100] + "..."
            if len(self.raw_output) > 100
            else self.raw_output
        )
        return (
            f"{base} [parse_error={self.parse_error!r}, raw_output={output_preview!r}]"
        )