Ports

@dataclass(frozen=True, slots=True)
class ProposalResult:
    """Result of a successful proposal operation.

    Attributes:
        candidate (Candidate): The proposed candidate with components.
        parent_indices (list[int]): Indices of parent candidate(s) in ParetoState.
        tag (str): Type of proposal ("mutation" or "merge").
        metadata (dict[str, Any]): Additional proposal-specific metadata.

    Examples:
        Creating a mutation proposal result:

        ```python
        from gepa_adk.domain.types import ProposalResult
        from gepa_adk.domain.models import Candidate

        result = ProposalResult(
            candidate=Candidate(components={"instruction": "Be helpful"}),
            parent_indices=[5],
            tag="mutation",
        )
        ```

        Creating a merge proposal result:

        ```python
        result = ProposalResult(
            candidate=Candidate(components={"instruction": "..."}),
            parent_indices=[5, 8],
            tag="merge",
            metadata={"ancestor_idx": 2},
        )
        ```

    Note:
        A frozen dataclass ensures immutability of proposal results.
        Parent indices must be valid indices into the ParetoState.candidates list.
    """

    candidate: "Candidate"  # Forward reference to avoid circular import
    parent_indices: list[int]
    tag: str
    metadata: dict[str, Any] = field(default_factory=dict)

@runtime_checkable
class AsyncGEPAAdapter(Protocol[DataInst, Trajectory, RolloutOutput]):
    """Protocol for async GEPA adapters used by the evolution engine.

    Implementations provide evaluation, reflection dataset generation, and
    proposal updates for candidate component texts.

    Examples:
        Implement a minimal adapter:

        ```python
        class MyAdapter:
            async def evaluate(self, batch, candidate, capture_traces=False):
                return EvaluationBatch(outputs=[], scores=[])

            async def make_reflective_dataset(
                self, candidate, eval_batch, components_to_update
            ):
                return {component: [] for component in components_to_update}

            async def propose_new_texts(
                self, candidate, reflective_dataset, components_to_update
            ):
                return {
                    component: candidate[component]
                    for component in components_to_update
                }
        ```

    Note:
        Adapters must implement all three async methods to satisfy
        the protocol. Use runtime_checkable for isinstance() checks.
    """

    async def evaluate(
        self,
        batch: list[DataInst],
        candidate: dict[str, str],
        capture_traces: bool = False,
    ) -> EvaluationBatch[Trajectory, RolloutOutput]:
        """Evaluate a candidate over a batch of inputs.

        Args:
            batch: Input data instances to evaluate.
            candidate: Component name to text mapping.
            capture_traces: Whether to capture execution traces.

        Returns:
            Evaluation results with outputs, scores, and optional traces.

        Examples:
            Basic evaluation:

            ```python
            result = await adapter.evaluate(batch, candidate)
            assert len(result.scores) == len(batch)
            ```

        Note:
            Output and score lists must have the same length as the
            input batch. Set capture_traces=True to enable reflection.
        """

    async def make_reflective_dataset(
        self,
        candidate: dict[str, str],
        eval_batch: EvaluationBatch[Trajectory, RolloutOutput],
        components_to_update: list[str],
    ) -> Mapping[str, Sequence[Mapping[str, Any]]]:
        """Build reflective datasets from evaluation traces.

        Args:
            candidate: Current candidate components.
            eval_batch: Evaluation results with traces.
            components_to_update: Components to generate datasets for.

        Returns:
            Mapping of component name to reflective examples.

        Examples:
            Build datasets for specific components:

            ```python
            dataset = await adapter.make_reflective_dataset(
                candidate,
                eval_batch,
                ["instruction"],
            )
            ```

        Note:
            Only call this method when eval_batch contains trajectories.
            Each component receives its own list of reflective examples.
        """

    async def propose_new_texts(
        self,
        candidate: dict[str, str],
        reflective_dataset: Mapping[str, Sequence[Mapping[str, Any]]],
        components_to_update: list[str],
    ) -> dict[str, str]:
        """Propose updated component texts from reflective datasets.

        Args:
            candidate: Current candidate components.
            reflective_dataset: Reflective examples per component.
            components_to_update: Components to propose updates for.

        Returns:
            Mapping of component name to new proposed text.

        Examples:
            Generate new component texts:

            ```python
            proposals = await adapter.propose_new_texts(
                candidate,
                reflective_dataset,
                ["instruction"],
            )
            ```

        Note:
            Outputs should contain improved text for each requested
            component. The evolution engine uses these as mutation candidates.
        """

@dataclass(frozen=True, slots=True)
class EvaluationBatch(Generic[Trajectory, RolloutOutput]):
    """Container for evaluation outputs and scores.

    Attributes:
        outputs (list[RolloutOutput]): Per-example outputs produced during evaluation.
        scores (list[Score]): Per-example normalized scores (higher is better).
        trajectories (list[Trajectory] | None): Optional per-example execution traces.
        objective_scores (list[dict[ComponentName, Score]] | None): Optional
            multi-objective scores per example.
        metadata (list[dict[str, Any]] | None): Optional per-example scorer metadata.
            When provided, metadata[i] corresponds to outputs[i] and scores[i]
            (index-aligned). Metadata dicts may contain scorer-specific fields like
            'feedback', 'actionable_guidance', or 'dimension_scores' from
            CriticScorer implementations.
        inputs (list[str] | None): Optional per-example input text that was used
            to generate each output. Used by make_reflective_dataset to provide
            context for reflection. When provided, inputs[i] corresponds to the
            input that produced outputs[i].

    Examples:
        Create a batch with optional traces:

        ```python
        batch = EvaluationBatch(
            outputs=["ok", "ok"],
            scores=[0.9, 0.8],
            trajectories=[{"trace": 1}, {"trace": 2}],
        )
        ```

        Create a batch with inputs for reflection:

        ```python
        batch = EvaluationBatch(
            outputs=["Hello!", "Good morrow!"],
            scores=[0.3, 0.9],
            inputs=["I am the King", "I am your friend"],
        )
        ```

    Note:
        All fields are immutable once created due to frozen=True.
        Use this as the standard return type from adapter evaluations.
        When metadata is not None, len(metadata) must equal len(outputs) and len(scores).
    """

    outputs: list[RolloutOutput]
    scores: list[Score]
    trajectories: list[Trajectory] | None = None
    objective_scores: list[dict[ComponentName, Score]] | None = None
    metadata: list[dict[str, Any]] | None = None
    inputs: list[str] | None = None

@runtime_checkable
class AgentExecutorProtocol(Protocol):
    """Protocol for unified agent execution.

    Defines the interface for executing any ADK agent type (LlmAgent,
    workflow agents) with consistent behavior, session management, and
    result handling.

    This protocol enables:
    - Feature parity across generator, critic, and reflection agents
    - Dependency injection for testing
    - Single point of change for new ADK features

    Examples:
        Using an executor:

        ```python
        executor: AgentExecutorProtocol = AgentExecutor()

        result = await executor.execute_agent(
            agent=my_agent,
            input_text="Hello",
            timeout_seconds=60,
        )

        if result.status == ExecutionStatus.SUCCESS:
            print(result.extracted_value)
        ```

        With instruction override (for evolution):

        ```python
        result = await executor.execute_agent(
            agent=my_agent,
            input_text="Hello",
            instruction_override="You are a helpful assistant.",
        )
        ```

    See Also:
        - [`ExecutionResult`][gepa_adk.ports.agent_executor.ExecutionResult]:
            Return type for execute_agent.
        - [`ExecutionStatus`][gepa_adk.ports.agent_executor.ExecutionStatus]:
            Status enum for execution outcomes.

    Note:
        All implementations should validate that the agent parameter is a
        valid ADK LlmAgent. The Any type is used here to avoid coupling
        the ports layer to ADK types.
    """

    async def execute_agent(
        self,
        agent: Any,
        input_text: str,
        *,
        input_content: Any | None = None,
        instruction_override: str | None = None,
        output_schema_override: Any | None = None,
        session_state: dict[str, Any] | None = None,
        existing_session_id: str | None = None,
        timeout_seconds: int = 300,
    ) -> ExecutionResult:
        """Execute an agent and return structured result.

        Runs the specified agent with the given input, optionally applying
        instruction or schema overrides for evolution scenarios. Manages
        session lifecycle and captures execution events.

        Args:
            agent: ADK LlmAgent to execute. The agent's tools, output_key,
                and other ADK features are preserved during execution.
            input_text: User message to send to the agent. Used as fallback
                if input_content is not provided.
            input_content: Optional ADK Content object for multimodal input
                (e.g., video parts). If provided, takes precedence over input_text.
            instruction_override: If provided, replaces the agent's instruction
                for this execution only. Original agent is not modified.
            output_schema_override: If provided, replaces the agent's output
                schema for this execution only (type[BaseModel]). Used for schema evolution.
            session_state: Initial state to inject into the session. Used for
                template variable substitution (e.g., {component_text}).
            existing_session_id: If provided, reuses an existing session instead
                of creating a new one. Useful for critic accessing generator state.
            timeout_seconds: Maximum execution time in seconds. Defaults to 300.
                Execution terminates with TIMEOUT status if exceeded.

        Returns:
            ExecutionResult with status, output, and debugging information.

        Raises:
            SessionNotFoundError: If existing_session_id is provided but session
                does not exist.

        Examples:
            Basic execution:

            ```python
            result = await executor.execute_agent(
                agent=greeter,
                input_text="Hello!",
            )
            print(result.extracted_value)  # "Hello! How can I help?"
            ```

            With session state for reflection:

            ```python
            result = await executor.execute_agent(
                agent=reflector,
                input_text="Improve the instruction",
                session_state={
                    "component_text": "Be helpful.",
                    "trials": '[{"score": 0.5}]',
                },
            )
            ```

            Session sharing between agents:

            ```python
            # Generator creates session
            gen_result = await executor.execute_agent(
                agent=generator,
                input_text="Write a story.",
            )

            # Critic reuses generator's session
            critic_result = await executor.execute_agent(
                agent=critic,
                input_text=f"Evaluate: {gen_result.extracted_value}",
                existing_session_id=gen_result.session_id,
            )
            ```

        Note:
            The agent parameter is typed as Any to avoid coupling to ADK types
            in the ports layer. Implementations should validate that the agent
            is a valid LlmAgent.
        """
        ...

@dataclass
class ExecutionResult:
    """Result of an agent execution.

    Provides consistent return type across all agent types (generator, critic,
    reflection) with status, output, timing, and debugging information.

    Attributes:
        status (ExecutionStatus): Outcome status of the execution.
        session_id (str): ADK session identifier used for this execution.
        extracted_value (str | None): Output text extracted from agent response. None if
            agent produced no output or execution failed.
        error_message (str | None): Error details if status is FAILED or TIMEOUT. None
            for successful executions.
        execution_time_seconds (float): Duration of execution in seconds.
        captured_events (list[Any] | None): ADK events captured during execution for debugging
            and trajectory analysis. None if event capture disabled.

    Examples:
        Successful execution:

        ```python
        result = ExecutionResult(
            status=ExecutionStatus.SUCCESS,
            session_id="sess_123",
            extracted_value="Hello, world!",
            execution_time_seconds=1.5,
        )
        ```

        Failed execution:

        ```python
        result = ExecutionResult(
            status=ExecutionStatus.FAILED,
            session_id="sess_456",
            error_message="Model rate limit exceeded",
            execution_time_seconds=0.2,
        )
        ```

    Note:
        All captured_events contain raw ADK Event objects for debugging
        and trajectory recording. Events are captured even on timeout
        or failure.
    """

    status: ExecutionStatus
    session_id: str
    extracted_value: str | None = None
    error_message: str | None = None
    execution_time_seconds: float = 0.0
    captured_events: list[Any] | None = field(default=None)

class ExecutionStatus(str, Enum):
    """Status of agent execution.

    This enum represents the outcome status of an agent execution,
    used by ExecutionResult to indicate how the execution completed.

    Attributes:
        SUCCESS: Agent completed execution normally with valid output.
        FAILED: Agent encountered an error during execution.
        TIMEOUT: Agent execution exceeded configured timeout.

    Examples:
        Checking execution status:

        ```python
        from gepa_adk.ports.agent_executor import ExecutionStatus

        if result.status == ExecutionStatus.SUCCESS:
            print(f"Output: {result.extracted_value}")
        elif result.status == ExecutionStatus.TIMEOUT:
            print(f"Timed out after {result.execution_time_seconds}s")
        elif result.status == ExecutionStatus.FAILED:
            print(f"Error: {result.error_message}")
        ```

    Note:
        All status values reflect execution outcome, not output quality.
        A successful execution may still produce low-quality output
        that fails scoring.
    """

    SUCCESS = "success"
    FAILED = "failed"
    TIMEOUT = "timeout"

@runtime_checkable
class AgentProvider(Protocol):
    """Protocol for loading and persisting agents.

    Implementations provide agent configuration storage and retrieval,
    enabling the evolution system to load agents and persist evolved
    instructions.

    Examples:
        Implement a minimal in-memory provider:

        ```python
        class InMemoryProvider:
            def __init__(self):
                self._agents = {}

            def get_agent(self, name: str) -> LlmAgent:
                if not name:
                    raise ValueError("Agent name cannot be empty")
                if name not in self._agents:
                    raise KeyError(f"Agent not found: {name}")
                return self._agents[name]

            def save_instruction(self, name: str, instruction: str) -> None:
                if not name:
                    raise ValueError("Agent name cannot be empty")
                if name not in self._agents:
                    raise KeyError(f"Agent not found: {name}")
                self._agents[name].instruction = instruction

            def list_agents(self) -> list[str]:
                return list(self._agents.keys())
        ```

        Verify protocol compliance:

        ```python
        from gepa_adk.ports import AgentProvider

        provider = InMemoryProvider()
        assert isinstance(provider, AgentProvider)  # Runtime check works
        ```

    Note:
        All implementations must provide get_agent(), save_instruction(),
        and list_agents() methods. Use @runtime_checkable to enable
        isinstance() checks for protocol compliance.
    """

    def get_agent(self, name: str) -> "LlmAgent":
        """Load an agent by its unique name.

        Args:
            name: The unique identifier for the agent.

        Returns:
            The configured LlmAgent instance ready for use.

        Raises:
            KeyError: If no agent with the given name exists.
            ValueError: If name is empty or invalid.

        Examples:
            Load a named agent:

            ```python
            provider = MyAgentProvider()
            agent = provider.get_agent("my_agent")
            print(agent.instruction)
            ```

        Note:
            Only non-empty names are accepted. Configured agents ready
            for use with the evolution system should be returned.
        """
        ...

    def save_instruction(self, name: str, instruction: str) -> None:
        """Persist an evolved instruction for a named agent.

        Args:
            name: The unique identifier for the agent.
            instruction: The new instruction text to persist.

        Raises:
            KeyError: If no agent with the given name exists.
            ValueError: If name is empty or invalid.
            IOError: If persistence fails (implementation-specific).

        Examples:
            Save an evolved instruction:

            ```python
            provider.save_instruction(
                "my_agent", "You are a helpful assistant specialized in coding."
            )
            ```

        Note:
            Only after successful persistence should subsequent calls to
            get_agent() return an agent with the updated instruction.
            Implementations should validate empty names before processing.
        """
        ...

    def list_agents(self) -> list[str]:
        """List all available agent names.

        Returns:
            A list of agent name strings. Empty list if no agents.

        Examples:
            Discover available agents:

            ```python
            provider = MyAgentProvider()
            for name in provider.list_agents():
                print(f"Found agent: {name}")
            ```

        Note:
            Ordering of returned names is not guaranteed by the protocol.
            Some implementations may return names in a specific order,
            but callers should not rely upon any particular sequence.
        """
        ...