Core API

async def evolve_group(  # noqa: C901, PLR0912, PLR0913  # decomposition tracked in #506; public API keyword arguments
    agents: dict[str, LlmAgent],
    primary: str,
    trainset: list[dict[str, Any]],
    *,
    components: dict[str, list[str]] | None = None,
    critic: LlmAgent | None = None,
    scorer: Scorer | None = None,
    share_session: bool = True,
    config: EvolutionConfig | None = None,
    state_guard: StateGuard | None = None,
    component_selector: ComponentSelectorProtocol | str | None = None,
    reflection_agent: LlmAgent | None = None,
    trajectory_config: TrajectoryConfig | None = None,
    workflow: SequentialAgent | LoopAgent | ParallelAgent | None = None,
    session_service: BaseSessionService | None = None,
    app: App | None = None,
    runner: Runner | None = None,
    registry: ComponentHandlerRegistry | None = None,
) -> MultiAgentEvolutionResult:
    """Evolve multiple agents together with per-agent component configuration.

    Optimizes specified components for each agent by targeting the primary
    agent's output score. When share_session=True, agents execute sequentially
    with shared session state, enabling later agents to access earlier
    agents' outputs via template strings.

    Args:
        agents (dict[str, LlmAgent]): Named ADK agents to evolve together as dict mapping agent
            names to LlmAgent instances. Must have at least one agent.
        primary (str): Name of the agent whose output is used for scoring.
            Must match one of the agent names in the dict.
        trainset (list[dict[str, Any]]): Training examples for evaluation. Each example should
            have an "input" key and optionally an "expected" key.

    Keyword Args:
        components (dict[str, list[str]] | None): Per-agent component configuration
            mapping agent names to lists of component names to evolve. If None, defaults
            to evolving "instruction" for all agents. Use empty list to exclude an agent
            from evolution. Available component names: "instruction", "output_schema",
            "generate_content_config".
        critic (LlmAgent | None): Optional critic agent for scoring. If None and no scorer is
            given, the primary agent must have an output_schema for
            schema-based scoring. Mutually exclusive with scorer.
        scorer (Scorer | None): Optional object implementing the Scorer protocol
            (``score`` and ``async_score``). When given, it scores the
            primary agent's output directly and takes precedence over
            schema-based scoring. Mutually exclusive with critic.
        share_session (bool): Whether agents share session state during
            execution. When True (default), uses SequentialAgent.
            When False, only the primary agent runs in its own session; other
            agents are not executed.
        config (EvolutionConfig | None): Evolution configuration. If None, uses EvolutionConfig
            defaults. Its ``reflection_max_trials`` and
            ``reflection_max_trial_chars`` bound the trials each
            reflection call sees, and its ``reflection_timeout_seconds``
            bounds each reflection call's run time. ``max_concurrent_evals``
            does not apply here: MultiAgentAdapter has no corresponding limit.
        state_guard (StateGuard | None): Optional StateGuard instance for validating and
            repairing state injection tokens in evolved instructions.
        component_selector (ComponentSelectorProtocol | str | None): Optional selector
            instance or selector name for choosing which components to update.
        reflection_agent (LlmAgent | None): Optional ADK agent for proposals. If None, creates a
            default reflection agent using config.reflection_model (a model
            string, or a ``BaseLlm`` instance passed through unchanged).
        trajectory_config (TrajectoryConfig | None): Trajectory capture settings (uses
            defaults if None).
        workflow (SequentialAgent | LoopAgent | ParallelAgent | None): Optional original
            workflow structure to preserve during evaluation. When provided, LoopAgent
            iterations and ParallelAgent concurrency are preserved instead of flattening
            to SequentialAgent. Used internally by evolve_workflow(); not typically set
            directly.
        session_service (BaseSessionService | None): Optional ADK session service for
            state management. If None (default), creates an InMemorySessionService
            internally. Pass a custom service (e.g., SqliteSessionService,
            DatabaseSessionService; on ADK 2.x SQL-backed services need the
            ``gepa-adk[db]`` extra, which installs ``google-adk[db]``) to persist
            sessions alongside other agent executions in a shared database.
            ``SqliteSessionService`` sets no busy timeout or WAL of its own, so on a
            loaded disk a write can wait past the five-second default of Python's
            sqlite3 connection (which aiosqlite uses) and raise ``database is
            locked``. The internal executor retries that error under its default
            ``RetryPolicy`` (three attempts, 0.5 s backoff, doubling) before the row
            counts as a failed evaluation.
        app (App | None): Optional ADK App instance. When provided, evolution uses the app's
            configuration. Note that App does not hold services directly; pass
            a Runner for service extraction, or combine with session_service param.
        runner (Runner | None): Optional ADK Runner instance. When provided, evolution extracts
            and uses the runner's session_service for all agent executions
            (evolved agents, critic, and reflection agent). Takes precedence
            over both app and session_service parameters. This enables seamless
            integration with existing ADK infrastructure.
        registry (ComponentHandlerRegistry | None): Optional ComponentHandlerRegistry
            that resolves every component name; defaults to the default registry that
            ``register_handler()`` and ``register_mapping_components()`` fill.

    Returns:
        MultiAgentEvolutionResult containing evolved_components dict
        mapping qualified component names (agent.component format) to their
        optimized values, along with score metrics, iteration history
        (each record names its ``candidate_id`` and ``parent_ids``),
        original_components (filtered to the qualified keyspace),
        schema_version (4), and stop_reason propagated from the engine
        result.

    Raises:
        ConfigurationError: If pre-flight validation fails: invalid agent
            names, non-LlmAgent critic, both critic and scorer given, a
            scorer that does not implement Scorer, empty trainset, duplicate
            or empty component names per agent, EvolutionConfig
            consistency errors, or a component name the resolved registry
            holds no handler for.
        MultiAgentValidationError: If agents dict is empty, primary agent
            not found, or no scorer and primary lacks output_schema.
        ValueError: If components mapping contains unknown agents or is
            missing entries for agents.
        EvolutionError: If evolution fails during execution. A reflection
            call that keeps raising a retryable provider error is skipped
            with ``skip_reason="reflection_error"``; a non-retryable one
            raises ``ReflectionError``. A reflection cut off at the
            output-token limit, or one that opens a reasoning tag it never
            closes, is skipped with ``skip_reason="incomplete_proposal"``.
            An error raised after the baseline
            was scored carries the engine's ``EvolutionResult`` for the
            recorded iterations in ``partial_result``.

    Examples:
        Basic usage with per-agent components (API v0.3.x):

        ```python
        from google.adk.agents import LlmAgent
        from google.adk.models.lite_llm import LiteLlm
        from gepa_adk import evolve_group

        generator = LlmAgent(
            name="generator",
            model=LiteLlm(model="ollama_chat/gpt-oss:20b"),
            instruction="Generate code based on the requirement.",
        )
        critic = LlmAgent(
            name="critic",
            model=LiteLlm(model="ollama_chat/gpt-oss:20b"),
            instruction="Review the code in {generator_output}.",
        )
        validator = LlmAgent(
            name="validator",
            model=LiteLlm(model="ollama_chat/gpt-oss:20b"),
            instruction="Validate the reviewed code.",
            output_schema=ValidationResult,
        )

        result = await evolve_group(
            agents={
                "generator": generator,
                "critic": critic,
                "validator": validator,
            },
            primary="validator",
            trainset=training_data,
            components={
                "generator": ["instruction", "output_schema"],
                "critic": ["instruction"],
                "validator": ["instruction"],
            },
        )

        # Access evolved components using qualified names
        print(result.evolved_components["generator.instruction"])
        print(result.evolved_components["critic.instruction"])
        print(result.evolved_components["validator.instruction"])
        ```

        Exclude an agent from evolution:

        ```python
        result = await evolve_group(
            agents={"generator": gen, "static_validator": val},
            primary="generator",
            trainset=training_data,
            components={
                "generator": ["instruction"],
                "static_validator": [],  # Excluded from evolution
            },
        )
        ```

        Using custom session service for persistence:

        ```python
        # Requires the gepa-adk[db] extra (google-adk[db]) on ADK 2.x
        from google.adk.sessions import SqliteSessionService

        # Use SQLite for session persistence
        session_service = SqliteSessionService(db_path="evolution_sessions.db")

        result = await evolve_group(
            agents={"generator": gen, "critic": critic},
            primary="critic",
            trainset=training_data,
            session_service=session_service,  # Sessions persisted to SQLite
        )
        ```

        Using App/Runner for existing infrastructure integration:

        ```python
        from google.adk.runners import Runner

        # Requires the gepa-adk[db] extra (google-adk[db]) on ADK 2.x
        from google.adk.sessions import DatabaseSessionService

        # Configure Runner with your production session service
        runner = Runner(
            app_name="my_app",
            agent=generator,  # Any agent from the group
            session_service=DatabaseSessionService(connection_string="..."),
        )

        # Evolution uses Runner's session_service for all operations
        result = await evolve_group(
            agents={"generator": gen, "refiner": ref},
            primary="refiner",
            trainset=training_data,
            runner=runner,  # Services extracted from runner
        )
        ```

    Notes:
        Breaking change in v0.3.x: The `agents` parameter changed from
        `list[LlmAgent]` to `dict[str, LlmAgent]`. Candidate keys now use
        qualified names (agent.component) instead of {agent_name}_instruction.

        For reproducible evolution, pass a seeded config:
        ``config=EvolutionConfig(seed=42)``.

        The returned result copies ``baseline_failed_evaluations``,
        ``total_failed_evaluations`` and ``token_usage`` from the engine
        result.
    """
    # Pre-flight validation (T012a + Story 2.5)
    _pre_flight_validate_group(agents, trainset, critic, components, scorer=scorer)

    # Default components: evolve "instruction" for all agents
    if components is None:
        components = {name: ["instruction"] for name in agents}

    # Resolve every component name through one registry for this round (#451)
    resolved_registry = registry if registry is not None else component_handlers
    for comp_list in components.values():
        for comp_name in comp_list:
            _resolve_handler(comp_name, resolved_registry)

    # Capture original instructions for StateGuard validation
    original_instructions = {
        name: str(agent.instruction) for name, agent in agents.items()
    }

    # Log precedence warnings if multiple config sources provided (#227 T009)
    if runner is not None and app is not None:
        logger.warning(
            "evolve_group.precedence.runner_over_app",
            message="Both runner and app provided; using runner (runner takes precedence)",
            runner_app_name=runner.app_name,
            app_name=app.name,
        )

    # Resolve services using precedence rules: runner > app > session_service > default (#227)
    resolved_session_service, _artifact_service = _resolve_evolution_services(
        runner=runner,
        app=app,
        session_service=session_service,
    )

    # Resolve app_name for session isolation (#239)
    resolved_app_name = _resolve_app_name(runner=runner, app=app)

    # Create unified executor for consistent session management (FR-003)
    executor = AgentExecutor(
        session_service=resolved_session_service,
        app_name=resolved_app_name,
    )

    # Build scorer with executor (FR-005); an explicit scorer wins
    if scorer is None and critic:
        scorer = CriticScorer(critic_agent=critic, executor=executor)

    # Resolve config for reflection_model
    resolved_config = config or EvolutionConfig()
    rng = (
        random.Random(resolved_config.seed)  # noqa: S311  # evolution sampling, not security
        if resolved_config.seed is not None
        else None
    )

    # Create reflection-based proposer with executor (FR-006)
    # Use provided reflection_agent or create a default one
    if reflection_agent is None:
        reflection_agent = LlmAgent(
            name="reflection_agent",
            model=_resolve_model_for_agent(resolved_config.reflection_model),
            instruction=resolved_config.reflection_prompt or REFLECTION_INSTRUCTION,
        )
    adk_reflection_fn = create_adk_reflection_fn(
        reflection_agent,
        executor=executor,
        timeout_seconds=resolved_config.reflection_timeout_seconds,
    )
    proposer = AsyncReflectiveMutationProposer(
        adk_reflection_fn=adk_reflection_fn,
        max_trials=resolved_config.reflection_max_trials,
        max_trial_chars=resolved_config.reflection_max_trial_chars,
    )

    # Create adapter with executor (FR-004)
    adapter = MultiAgentAdapter(
        agents=agents,
        primary=primary,
        components=components,
        scorer=scorer,
        share_session=share_session,
        session_service=resolved_session_service,
        trajectory_config=trajectory_config,
        proposer=proposer,
        executor=executor,
        workflow=workflow,  # Preserve workflow structure (#215)
        registry=resolved_registry,
    )

    # Build seed candidate using qualified names (agent.component format per ADR-012)
    primary_agent = agents[primary]
    # Extract all configured components using their handlers
    seed_candidate_components: dict[str, str] = {}
    for agent_name, comp_list in components.items():
        agent = agents[agent_name]
        for comp_name in comp_list:
            qualified_name = f"{agent_name}.{comp_name}"
            handler = _resolve_handler(comp_name, resolved_registry)
            seed_candidate_components[qualified_name] = handler.serialize(agent)
    # Add required "instruction" key for engine compatibility
    seed_candidate_components["instruction"] = str(primary_agent.instruction)
    initial_candidate = Candidate(components=seed_candidate_components)

    # Create engine
    resolved_component_selector: ComponentSelectorProtocol | None = None
    if component_selector is not None:
        if isinstance(component_selector, str):
            resolved_component_selector = create_component_selector(component_selector)
        else:
            resolved_component_selector = component_selector

    engine = AsyncGEPAEngine(
        adapter=adapter,
        config=resolved_config,
        initial_candidate=initial_candidate,
        batch=trainset,
        component_selector=resolved_component_selector,
        rng=rng,
    )

    # Run evolution
    evolution_result = await engine.run()

    # Extract best candidate components from engine state using qualified names
    # The engine stores evolved_components from the candidate, which now uses
    # qualified names (agent.component format per ADR-012)
    evolved_components = _extract_evolved_components(
        evolution_result=evolution_result,
        seed_components=seed_candidate_components,
        agents=agents,
        components=components,
        primary=primary,
    )

    # Apply StateGuard validation to instruction components only
    if state_guard is not None:
        validated_components = {}
        for qualified_name, evolved_value in evolved_components.items():
            # Only apply StateGuard to instruction components
            if qualified_name.endswith(".instruction"):
                agent_name = qualified_name.rsplit(".", 1)[0]
                original_instruction = original_instructions.get(agent_name, "")
                validated_components[qualified_name] = _apply_state_guard_validation(
                    state_guard=state_guard,
                    original_component_text=original_instruction,
                    evolved_component_text=evolved_value,
                    agent_name=agent_name,
                )
            else:
                # Non-instruction components pass through unchanged
                validated_components[qualified_name] = evolved_value
        evolved_components = validated_components

    # Filter original_components to the qualified keyspace used by
    # evolved_components, stripping engine-internal keys (e.g. bare
    # "instruction" added for engine compatibility).
    orig = evolution_result.original_components
    if orig is not None:
        orig = {k: v for k, v in orig.items() if k in evolved_components}

    # Convert EvolutionResult to MultiAgentEvolutionResult
    return MultiAgentEvolutionResult(
        schema_version=evolution_result.schema_version,
        stop_reason=evolution_result.stop_reason,
        evolved_components=evolved_components,
        original_score=evolution_result.original_score,
        final_score=evolution_result.final_score,
        primary_agent=primary,
        iteration_history=evolution_result.iteration_history,
        total_iterations=evolution_result.total_iterations,
        original_components=orig,
        baseline_failed_evaluations=evolution_result.baseline_failed_evaluations,
        total_failed_evaluations=evolution_result.total_failed_evaluations,
        token_usage=evolution_result.token_usage,
    )