Reflection agents

def create_text_reflection_agent(model: str) -> LlmAgent:
    """Create a reflection agent for text components.

    Creates an LlmAgent configured for free-form text reflection with no
    validation tools. Suitable for instructions, descriptions, and other
    text components that don't require structured validation.

    Args:
        model: Model name/identifier (e.g., "gemini-2.5-flash").

    Returns:
        Configured LlmAgent with text reflection instruction and no tools.

    Examples:
        Create agent for instruction reflection:

        ```python
        from gepa_adk.engine.reflection_agents import create_text_reflection_agent

        agent = create_text_reflection_agent(model="gemini-2.5-flash")

        # Agent has:
        # - name="text_reflector"
        # - instruction with {component_text} and {trials} placeholders
        # - output_key="proposed_component_text"
        # - No tools
        ```

    See Also:
        - [`REFLECTION_INSTRUCTION`][gepa_adk.engine.adk_reflection.REFLECTION_INSTRUCTION]:
          Default instruction template.
    """
    logger.debug(
        "reflection_agent.create",
        agent_type="text",
        model=model,
    )

    return LlmAgent(
        name="text_reflector",
        model=model,
        instruction=REFLECTION_INSTRUCTION,
        output_key="proposed_component_text",
    )

def create_schema_reflection_agent(model: str) -> LlmAgent:
    """Create a reflection agent for output_schema components.

    Creates an LlmAgent configured with:
    - Schema-focused reflection instruction
    - validate_output_schema tool for self-validation
    - Explicit instruction to use validation tool before returning

    This agent can validate proposed Pydantic schemas before returning them,
    reducing wasted evolution iterations on invalid syntax.

    Args:
        model: Model name/identifier (e.g., "gemini-2.5-flash").

    Returns:
        Configured LlmAgent with schema validation tool.

    Examples:
        Create agent for schema reflection:

        ```python
        from gepa_adk.engine.reflection_agents import create_schema_reflection_agent

        agent = create_schema_reflection_agent(model="gemini-2.5-flash")

        # Agent has:
        # - name="schema_reflector"
        # - tools=[FunctionTool(validate_output_schema)]
        # - instruction with validation guidance
        # - output_key="proposed_component_text"
        ```

    See Also:
        - [`SCHEMA_REFLECTION_INSTRUCTION`]:
          Schema instruction template.
        - [`validate_output_schema`]:
          Validation tool function.

    Note:
        The agent uses `output_key` for text output extraction, not `output_schema`.
        This avoids ADK's limitation where tools and output_schema cannot be used
        together. The agent returns plain text (the Pydantic class definition).
    """
    logger.debug(
        "reflection_agent.create",
        agent_type="schema",
        model=model,
    )

    return LlmAgent(
        name="schema_reflector",
        model=model,
        instruction=SCHEMA_REFLECTION_INSTRUCTION,
        tools=[FunctionTool(validate_output_schema)],
        output_key="proposed_component_text",
    )

def create_config_reflection_agent(model: str) -> LlmAgent:
    """Create a reflection agent for generate_content_config components.

    Creates an LlmAgent configured for LLM generation configuration reflection.
    The agent receives parameter guidelines and valid ranges to help propose
    optimal configurations based on trial results.

    Args:
        model: Model name/identifier (e.g., "gemini-2.5-flash").

    Returns:
        Configured LlmAgent with config reflection instruction.

    Examples:
        Create agent for config reflection:

        ```python
        from gepa_adk.engine.reflection_agents import create_config_reflection_agent

        agent = create_config_reflection_agent(model="gemini-2.5-flash")

        # Agent has:
        # - name="config_reflector"
        # - instruction with parameter guidelines
        # - output_key="proposed_component_text"
        # - No tools (validation happens in handler)
        ```

    See Also:
        - [`CONFIG_REFLECTION_INSTRUCTION`]:
          Config instruction template.

    Note:
        The agent does not use validation tools because config validation
        is built into the GenerateContentConfigHandler.apply() method.
        Invalid configs are gracefully rejected there.
    """
    logger.debug(
        "reflection_agent.create",
        agent_type="config",
        model=model,
    )

    return LlmAgent(
        name="config_reflector",
        model=model,
        instruction=CONFIG_REFLECTION_INSTRUCTION,
        output_key="proposed_component_text",
    )

def get_reflection_agent(component_name: str, model: str) -> LlmAgent:
    """Get appropriate reflection agent for a component.

    Convenience function that uses the global registry to create an agent
    based on component name. Falls back to text reflection for unknown components.

    Args:
        component_name: Component being evolved (e.g., "output_schema").
        model: Model name/identifier.

    Returns:
        Configured LlmAgent for the component type.

    Examples:
        Auto-select agent:

        ```python
        from gepa_adk.engine.reflection_agents import get_reflection_agent

        # Returns schema agent with validation tool
        schema_agent = get_reflection_agent("output_schema", "gemini-2.5-flash")

        # Returns text agent without tools
        text_agent = get_reflection_agent("instruction", "gemini-2.5-flash")

        # Unknown components get text agent (fallback)
        fallback_agent = get_reflection_agent("custom", "gemini-2.5-flash")
        ```

    See Also:
        - [`component_registry`]: Default registry.
    """
    return component_registry.get_agent(component_name, model)