Docstring Templates¶

"""Domain models and entities for gepa-adk.

This package contains the core domain models that represent the fundamental
concepts in genetic algorithm evolution, including configuration, iteration
records, results, and candidate solutions.

Attributes:
    EvolutionConfig (class): Configuration for evolution parameters.
    IterationRecord (class): Record of a single iteration's metrics.
    EvolutionResult (class): Complete evolution run results.
    Candidate (class): Individual solution candidate.

Examples:
    Basic usage with configuration:

    ```python
    from gepa_adk.domain import EvolutionConfig

    config = EvolutionConfig(
        max_iterations=100,
        population_size=50,
        mutation_rate=0.15
    )
    ```

See Also:
    - [`gepa_adk.domain.exceptions`][gepa_adk.domain.exceptions]: Exception hierarchy.
    - [`gepa_adk.domain.types`][gepa_adk.domain.types]: Type aliases and constants.

Note:
    All models are immutable by default (frozen dataclasses) for thread safety.
"""

class EvolutionEngine:
    """Execute genetic algorithm evolution runs.

    Attributes:
        config (EvolutionConfig): Evolution configuration parameters.
        population (list[Candidate]): Current population of candidates.

    Examples:
        Run evolution:

        ```python
        engine = EvolutionEngine(config)
        result = engine.run()
        assert result.best_score > 0
        ```

    See Also:
        - [`EvolutionConfig`][gepa_adk.domain.models.EvolutionConfig]:
          Configuration parameters.

    Note:
        Engine maintains population state across iterations for efficiency.
    """

def __init__(
    self,
    config: EvolutionConfig,
    *,
    seed: int | None = None,
) -> None:
    """Initialize the evolution engine.

    Args:
        config: Evolution configuration parameters.

    Other Parameters:
        seed (int | None): Random seed for reproducibility.

    Raises:
        ConfigurationError: If configuration is invalid.

    Note:
        Random seed ensures reproducible evolution runs when provided.
    """

def evolve_population(
    self,
    iterations: int,
) -> EvolutionResult:
    """Evolve the population for specified iterations.

    Args:
        iterations: Number of generations to evolve.

    Returns:
        EvolutionResult with best candidate and metrics.

    Raises:
        EvolutionError: If evolution fails.

    Examples:
        Evolve for 100 generations:

        ```python
        result = engine.evolve_population(100)
        print(f"Best score: {result.best_score}")
        ```

    Note:
        Each iteration applies selection, crossover, and mutation in sequence.
    """

def _calculate_fitness(candidate: Candidate) -> float:
    """Calculate fitness score for a candidate.

    Args:
        candidate: Solution candidate to evaluate.

    Returns:
        Fitness score (higher is better).

    Note:
        Uses weighted sum of objective functions for multi-criteria optimization.
    """

from typing import Protocol


class FitnessFunction(Protocol):
    """Protocol for fitness evaluation functions.

    Examples:
        Implement a fitness function:

        ```python
        def my_fitness(candidate: Candidate) -> float:
            return sum(candidate.genes)
        ```
    """

    def __call__(self, candidate: Candidate) -> float:
        """Evaluate candidate fitness.

        Args:
            candidate: Solution candidate to evaluate.

        Returns:
            Fitness score (higher is better).
        """

from dataclasses import dataclass


@dataclass(slots=True)
class IterationRecord:
    """Record of a single evolution iteration.

    Attributes:
        iteration (int): Iteration number (0-indexed).
        best_score (float): Best fitness score in this iteration.
        avg_score (float): Average fitness score across population.
        diversity (float): Population diversity metric.

    Examples:
        Create a record:

        ```python
        record = IterationRecord(
            iteration=0,
            best_score=0.95,
            avg_score=0.67,
            diversity=0.42
        )
        assert record.best_score > record.avg_score
        ```
    """

    iteration: int
    best_score: float
    avg_score: float
    diversity: float

from enum import Enum


class SelectionStrategy(str, Enum):
    """Selection strategies for parent selection.

    Examples:
        Access enum value:

        ```python
        assert SelectionStrategy.TOURNAMENT.value == "tournament"
        ```
    """

    TOURNAMENT = "tournament"
    ROULETTE = "roulette"
    RANK = "rank"

from typing import NamedTuple


class ScoreRange(NamedTuple):
    """Min and max fitness scores.

    Attributes:
        min_score (float): Minimum observed fitness.
        max_score (float): Maximum observed fitness.
    """

    min_score: float
    max_score: float

from typing import TypedDict


class EvolutionMetrics(TypedDict, total=False):
    """Serialized evolution metrics.

    Attributes:
        generations (int): Number of generations completed.
        best_score (float): Best fitness achieved.
        convergence (float): Convergence metric.
    """

    generations: int
    best_score: float
    convergence: float

class EvolutionError(Exception):
    """Base exception for evolution errors.

    Args:
        message: Human-readable error message.
        cause: Optional underlying exception.

    Note:
        All domain exceptions inherit from this base for consistent handling.
    """

def create_population(
    size: int,
    *,
    gene_length: int = 10,
) -> list[Candidate]:
    """Create initial random population.

    Args:
        size: Number of candidates to generate.

    Other Parameters:
        gene_length (int): Number of genes per candidate.

    Returns:
        List of randomly initialized candidates.

    Examples:
        Create population:

        ```python
        population = create_population(50, gene_length=20)
        assert len(population) == 50
        ```
    """

from typing import Generator


def evolve_generations(
    config: EvolutionConfig,
) -> Generator[IterationRecord, None, None]:
    """Stream evolution progress by generation.

    Args:
        config: Evolution configuration.

    Yields:
        IterationRecord for each generation.

    Examples:
        Stream evolution:

        ```python
        for record in evolve_generations(config):
            print(f"Gen {record.iteration}: {record.best_score}")
        ```
    """

def validate_config(config: EvolutionConfig) -> None:
    """Validate evolution configuration.

    Args:
        config: Configuration to validate.

    Warns:
        UserWarning: If configuration values are suboptimal.
    """

from warnings import deprecated


@deprecated("Use `evolve_population()` instead. Will be removed in v2.0.")
def run_evolution(config: EvolutionConfig) -> EvolutionResult:
    """Run evolution with legacy algorithm.

    Args:
        config: Evolution configuration.

    Returns:
        Evolution results.

    See Also:
        - [`evolve_population()`][gepa_adk.core.evolve_population]:
          Preferred replacement API.
    """