Domain

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

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

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

        Notes:
            Outputs formatted error message with parse error and raw output
            preview (the first 100 chars followed by ``...`` when longer),
            preserving base message structure.
        """
        base = super().__str__()
        output_preview = (
            self.raw_output[:100] + "..."
            if len(self.raw_output) > 100  # noqa: PLR2004  # preview length local to this __str__
            else self.raw_output
        )
        return (
            f"{base} [parse_error={self.parse_error!r}, raw_output={output_preview!r}]"
        )

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 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 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 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 MissingScoreFieldError(ScoringError):
    """Raised when score field is missing or null in parsed output.

    This exception indicates that the output was successfully parsed
    and validated, but the required `score` field is missing or null.

    Attributes:
        parsed_output (dict[str, Any]): The parsed output without valid score.
        available_fields (list[str]): Fields that were present.

    Examples:
        Handling missing score field:

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

        try:
            score, metadata = await scorer.async_score(...)
        except MissingScoreFieldError as e:
            print(f"Missing score. Available fields: {e.available_fields}")
        ```

    Notes:
        Applies when parsed output lacks a valid score value.
        The parsed_output may contain other valid fields that will be
        preserved in metadata if score is found.
    """

    def __init__(
        self,
        message: str,
        *,
        parsed_output: dict[str, Any],
        cause: Exception | None = None,
    ) -> None:
        """Initialize MissingScoreFieldError with parsed output.

        Args:
            message: Human-readable error description.
            parsed_output: The parsed dict without valid score field.
            cause: Original exception that caused this error.

        """
        super().__init__(message, cause=cause)
        self.parsed_output = parsed_output
        self.available_fields = list(parsed_output.keys())

    def __str__(self) -> str:
        """Return string with available fields.

        Returns:
            Formatted message including list of available fields.

        Notes:
            Outputs formatted error message with list of available fields
            from parsed output, preserving base message structure.
        """
        base = super().__str__()
        return f"{base} [available_fields={self.available_fields}]"

class MultiAgentValidationError(EvolutionError):
    """Raised when multi-agent configuration validation fails.

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

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

    Examples:
        Creating a multi-agent validation error:

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

        error = MultiAgentValidationError(
            "agents list cannot be empty",
            field="agents",
            value=[],
            constraint="len >= 1",
        )
        print(error.field, error.value)  # agents []
        ```

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

    def __init__(
        self,
        message: str,
        *,
        field: str,
        value: object,
        constraint: str,
    ) -> None:
        """Initialize MultiAgentValidationError 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, value, and constraint
            context when available, preserving base message structure.
        """
        base = super().__str__()
        return (
            f"{base} [field={self.field!r}, value={self.value!r}, "
            f"constraint={self.constraint!r}]"
        )