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.

    Attributes:
        partial_result (EvolutionResult | None): Partial result the engine
            attaches when it aborts a run after the baseline was scored,
            built with ``StopReason.ERROR`` from the iterations recorded so
            far. ``None`` when the error was raised before the baseline
            score existed or outside an engine run.

    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
        ```

    Notes:
        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).
    """

    partial_result: "EvolutionResult | None" = None

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
        ```

    Notes:
        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.

        """
        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.

        Notes:
            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",
        )
        ```

    Notes:
        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: Arbitrary key-value pairs stored as exception attributes
                for debugging context.
        """
        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.

        Notes:
            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 EmptyProposalError(EvolutionError):
    """Raised when reflection returns an empty proposal after one retry.

    The engine treats this error as a failed iteration rather than a fatal
    one: it records the iteration as skipped and continues the loop.

    Attributes:
        component (str): Name of the component the reflection was proposing
            text for.

    Examples:
        ```python
        raise EmptyProposalError("instruction")
        ```

    Notes:
        Raised by the mutation proposer after the reflection function has
        returned an empty or whitespace-only string twice in a row.
    """

    def __init__(self, component: str) -> None:
        """Initialize EmptyProposalError with the component name.

        Args:
            component: Name of the component whose reflection was empty.
        """
        super().__init__(
            f"Reflection agent returned empty string for component "
            f"{component!r} after one retry. Expected non-empty string "
            "with proposed component text."
        )
        self.component = component

class ReflectionTimeoutError(EvolutionError):
    """Raised when the reflection agent exceeds its timeout.

    The engine treats this error as a skipped iteration rather than a fatal
    one: it records the iteration with ``skip_reason="reflection_timeout"``,
    counts it toward patience and continues the loop. The proposer does not
    retry a timed-out reflection.

    Attributes:
        component (str): Name of the component the reflection was proposing
            text for.
        timeout_seconds (int | None): Timeout the reflection ran under, or
            ``None`` when the executor's own default applied.

    Examples:
        ```python
        raise ReflectionTimeoutError("instruction", timeout_seconds=120)
        ```

    Notes:
        Raised by the ADK reflection function when the executor returns
        ``ExecutionStatus.TIMEOUT``, as distinct from a failed run or an
        empty response.
    """

    def __init__(self, component: str, timeout_seconds: int | None = None) -> None:
        """Initialize ReflectionTimeoutError with the component and timeout.

        Args:
            component: Name of the component whose reflection timed out.
            timeout_seconds: Timeout the reflection ran under, or ``None``
                when the executor's own default applied.
        """
        limit = (
            f"after {timeout_seconds} seconds"
            if timeout_seconds is not None
            else "under the executor's default timeout"
        )
        super().__init__(
            f"Reflection agent timed out for component {component!r} {limit}."
        )
        self.component = component
        self.timeout_seconds = timeout_seconds

class IncompleteProposalError(EvolutionError):
    """Raised when the reflection output is incomplete.

    A proposal is incomplete when the last model response behind it reports
    a length stop (the output-token limit), or when its text opens a
    reasoning tag such as ``<think>`` that it never closes. The engine
    treats this error as a skipped iteration: it records the iteration with
    ``skip_reason="incomplete_proposal"``, keeps the raw text as the
    record's ``component_text``, counts it toward patience and continues
    the loop without evaluating. The proposer does not retry it.

    Attributes:
        component (str): Name of the component the reflection was proposing
            text for.
        finish_reason (str): Why the proposal is incomplete: the finish
            reason name (for example ``"MAX_TOKENS"``) or
            ``"unterminated_<tag>"`` for an unclosed reasoning tag.
        raw_text (str): The incomplete text the reflection produced.
        output_length (int): Length of ``raw_text`` in characters.

    Examples:
        ```python
        raise IncompleteProposalError(
            "instruction", finish_reason="MAX_TOKENS", raw_text="Be concise and"
        )
        ```

    Notes:
        Raised by the ADK reflection function after a successful execution,
        before the empty-response handling, so a length stop with no text
        is still reported as incomplete.
    """

    def __init__(self, component: str, *, finish_reason: str, raw_text: str) -> None:
        """Initialize IncompleteProposalError with the incomplete output.

        Args:
            component: Name of the component whose proposal is incomplete.
            finish_reason: Finish reason name or ``"unterminated_<tag>"``.
            raw_text: The incomplete text the reflection produced.
        """
        output_length = len(raw_text)
        super().__init__(
            f"Reflection output for component {component!r} is incomplete "
            f"(finish_reason={finish_reason}, {output_length} characters)."
        )
        self.component = component
        self.finish_reason = finish_reason
        self.raw_text = raw_text
        self.output_length = output_length

class ReflectionError(EvolutionError):
    """Raised when the reflection function raises an unexpected exception.

    The proposer wraps any non-``EvolutionError`` exception from the
    reflection function in this error and classifies it. A retryable error
    (quota, availability or connection failure) is retried once; when the
    retry fails too, the engine records the iteration with
    ``skip_reason="reflection_error"``, counts it toward patience and
    continues the loop. A non-retryable error aborts the run.

    Attributes:
        component (str): Name of the component the reflection was proposing
            text for.
        cause (BaseException): The exception the reflection function raised
            on the last attempt.
        retryable (bool): Whether the cause is a transient provider failure.
        attempts (int): Number of reflection calls made before giving up.

    Examples:
        ```python
        raise ReflectionError(
            "instruction",
            cause=RuntimeError("503 UNAVAILABLE"),
            retryable=True,
            attempts=2,
        )
        ```

    Notes:
        Raised by the mutation proposer. ``ReflectionTimeoutError`` and
        other ``EvolutionError`` subclasses from the reflection function
        pass through unwrapped.
    """

    def __init__(
        self,
        component: str,
        *,
        cause: BaseException,
        retryable: bool,
        attempts: int,
    ) -> None:
        """Initialize ReflectionError with the component and its cause.

        Args:
            component: Name of the component whose reflection failed.
            cause: The exception the reflection function raised.
            retryable: Whether the cause is a transient provider failure.
            attempts: Number of reflection calls made before giving up.
        """
        noun = "attempt" if attempts == 1 else "attempts"
        super().__init__(
            f"Reflection agent raised {type(cause).__name__}: {cause} for "
            f"component {component!r} after {attempts} {noun}."
        )
        self.component = component
        self.cause = cause
        self.retryable = retryable
        self.attempts = attempts

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
        ```

    Notes:
        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: Arbitrary key-value pairs stored as exception attributes
                for debugging context.

        Notes:
            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.

        Notes:
            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",
            )
        ```

    Notes:
        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,
            )
        ```

    Notes:
        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.

        """
        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.

        Notes:
            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}")
        ```

    Notes:
        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.

        """
        super().__init__(message)
        self.cause = cause

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

        Returns:
            Formatted message with cause information.

        Notes:
            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