Models

@dataclass(slots=True, frozen=True, kw_only=True)
class TokenRollup:
    """Token usage summed over evaluated rows and reflection calls.

    Each counter is the sum over the rows that reported usage. A row that
    reported none is counted in ``rows_unknown``, never as zero tokens. The
    counters are None only when no row reported usage and at least one row
    was unknown; nothing evaluated gives zeros. A rollup built with
    ``split()`` also carries its ``evaluation`` and ``reflection`` parts,
    and its counters cover both; a rollup built by ``from_batch()`` is a
    plain rollup without splits.

    Attributes:
        input_tokens (int | None): Prompt tokens over the counted rows, or
            None when unknown.
        output_tokens (int | None): Generated tokens over the counted rows,
            or None when unknown.
        total_tokens (int | None): Total tokens over the counted rows, or
            None when unknown.
        rows_counted (int): Rows that reported usage.
        rows_unknown (int): Rows that reported no usage.
        evaluation (TokenRollup | None): The evaluated rows' part of a split
            rollup, or None for a rollup without splits.
        reflection (TokenRollup | None): The reflection calls' part of a
            split rollup, one row per call, or None when no reflection call
            was observed.

    Examples:
        Summing an evaluation batch and serializing the result:

        ```python
        from gepa_adk.domain.models import TokenRollup

        rollup = TokenRollup.from_batch(batch)
        print(rollup.total_tokens, rollup.rows_unknown)
        data = rollup.to_dict()  # None counters become "unknown"
        assert TokenRollup.from_dict(data) == rollup
        ```

    Notes:
        The evaluation part covers the rows the adapters evaluated with
        traces; rows evaluated without traces, such as a separate valset
        pass, are not observed. The reflection part counts each reflection
        call that returned; a call whose executor captured no events is
        unknown. The parts are rollups without splits of their own.
    """

    input_tokens: int | None
    output_tokens: int | None
    total_tokens: int | None
    rows_counted: int
    rows_unknown: int
    evaluation: "TokenRollup | None" = None
    reflection: "TokenRollup | None" = None

    @classmethod
    def _build(
        cls,
        sums: tuple[int, int, int],
        rows_counted: int,
        rows_unknown: int,
    ) -> "TokenRollup":
        """Build a rollup, making counters unknown only under the unknown rule.

        Args:
            sums: Input, output and total token sums over counted rows.
            rows_counted: Rows that reported usage.
            rows_unknown: Rows that reported no usage.

        Returns:
            The rollup, with None counters when no row was counted and at
            least one row was unknown.
        """
        if rows_counted == 0 and rows_unknown > 0:
            return cls(
                input_tokens=None,
                output_tokens=None,
                total_tokens=None,
                rows_counted=0,
                rows_unknown=rows_unknown,
            )
        return cls(
            input_tokens=sums[0],
            output_tokens=sums[1],
            total_tokens=sums[2],
            rows_counted=rows_counted,
            rows_unknown=rows_unknown,
        )

    @classmethod
    def from_batch(cls, batch: Any) -> "TokenRollup":
        """Sum the token usage reported by each row of an evaluation batch.

        Reads ``batch.trajectories[i]`` for each row of ``batch.scores``. A
        trajectory whose ``token_usage`` or ``total_token_usage`` is a
        ``TokenUsage`` counts its three numbers; any other row (no
        trajectories, a trajectory without usage, a dict) is unknown.

        Args:
            batch: An ``EvaluationBatch`` or any object with ``scores`` and
                an optional ``trajectories`` sequence.

        Returns:
            The rollup of the batch. An empty batch gives zeros.
        """
        trajectories = getattr(batch, "trajectories", None) or []
        sums = [0, 0, 0]
        counted = 0
        unknown = 0
        for i in range(len(batch.scores)):
            usage = _row_usage(trajectories[i]) if i < len(trajectories) else None
            if usage is None:
                unknown += 1
                continue
            counted += 1
            sums[0] += usage.input_tokens
            sums[1] += usage.output_tokens
            sums[2] += usage.total_tokens
        return cls._build((sums[0], sums[1], sums[2]), counted, unknown)

    @classmethod
    def split(
        cls,
        *,
        evaluation: "TokenRollup | None",
        reflection: "TokenRollup | None",
    ) -> "TokenRollup":
        """Build a rollup from its evaluation and reflection parts.

        Args:
            evaluation: The evaluated rows' rollup, or None when absent.
            reflection: The reflection calls' rollup, or None when no
                reflection call was observed.

        Returns:
            A rollup whose counters combine both parts (a None part adds
            nothing; counters are None only when nothing was counted and
            something was unknown) and whose ``evaluation`` and
            ``reflection`` are the parts as given.

        Raises:
            ValueError: If a part has splits of its own; parts are rollups
                without splits, and a nested split would be flattened on
                save and load.
        """
        for name, part in (("evaluation", evaluation), ("reflection", reflection)):
            if part is not None and part._has_split():
                raise ValueError(
                    f"TokenRollup.split() {name} part must not have splits of its own"
                )
        total = cls._leaf_sum(evaluation, reflection)
        return cls(
            input_tokens=total.input_tokens,
            output_tokens=total.output_tokens,
            total_tokens=total.total_tokens,
            rows_counted=total.rows_counted,
            rows_unknown=total.rows_unknown,
            evaluation=evaluation,
            reflection=reflection,
        )

    @classmethod
    def _leaf_sum(
        cls, first: "TokenRollup | None", second: "TokenRollup | None"
    ) -> "TokenRollup":
        """Add the counters of two optional rollups, ignoring their splits.

        Args:
            first: A rollup, or None to add nothing.
            second: A rollup, or None to add nothing.

        Returns:
            A rollup without splits; zeros when both are None.
        """
        parts = [part for part in (first, second) if part is not None]
        sums = (
            sum(part.input_tokens or 0 for part in parts),
            sum(part.output_tokens or 0 for part in parts),
            sum(part.total_tokens or 0 for part in parts),
        )
        return cls._build(
            sums,
            sum(part.rows_counted for part in parts),
            sum(part.rows_unknown for part in parts),
        )

    def combine(self, other: "TokenRollup") -> "TokenRollup":
        """Add another rollup to this one.

        Counted rows and both row counts add up. A None counter on either
        side is treated as absent. When either side has splits, the result
        combines split-wise: a side without splits counts as evaluation,
        and a split absent on both sides stays None.

        Args:
            other: The rollup to add.

        Returns:
            A new rollup; its counters are None only when no row was counted
            and at least one row was unknown.
        """
        if not (self._has_split() or other._has_split()):
            return self._leaf_sum(self, other)
        return TokenRollup.split(
            evaluation=_combine_optional(
                self._evaluation_part(), other._evaluation_part()
            ),
            reflection=_combine_optional(self.reflection, other.reflection),
        )

    def _has_split(self) -> bool:
        """Tell whether this rollup carries an evaluation or reflection part.

        Returns:
            True when either split is set.
        """
        return self.evaluation is not None or self.reflection is not None

    def _evaluation_part(self) -> "TokenRollup | None":
        """Return the part of this rollup that counts as evaluation.

        Returns:
            The ``evaluation`` split of a split rollup, or this whole rollup
            when it has no splits.
        """
        if self._has_split():
            return self.evaluation
        return self

    def to_dict(self) -> dict[str, Any]:
        """Serialize this rollup to a stdlib-only dict.

        Returns:
            Dict with the five counters, where a None counter is written as
            ``"unknown"``, plus ``"evaluation"`` and ``"reflection"``, each
            the part's dict or None when absent. Output is directly
            ``json.dumps()``-compatible.
        """
        data = self._counters_dict()
        data["evaluation"] = _rollup_to_dict(self.evaluation)
        data["reflection"] = _rollup_to_dict(self.reflection)
        return data

    def _counters_dict(self) -> dict[str, Any]:
        """Serialize the five counters of this rollup.

        Returns:
            Dict with the five counters; a None counter is ``"unknown"``.
        """
        return {
            "input_tokens": (
                "unknown" if self.input_tokens is None else self.input_tokens
            ),
            "output_tokens": (
                "unknown" if self.output_tokens is None else self.output_tokens
            ),
            "total_tokens": (
                "unknown" if self.total_tokens is None else self.total_tokens
            ),
            "rows_counted": self.rows_counted,
            "rows_unknown": self.rows_unknown,
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> "TokenRollup":
        """Reconstruct a TokenRollup from a dict.

        Args:
            data: Dict produced by ``to_dict()``. A counter may be an int,
                None or ``"unknown"``. ``"evaluation"`` and ``"reflection"``
                are read when present; absent or None means no split. The
                parts load as rollups without splits of their own.

        Returns:
            Reconstructed TokenRollup; ``"unknown"`` and None load as None.

        Raises:
            KeyError: If a row count is missing from the dict or a part.
        """
        evaluation = data.get("evaluation")
        reflection = data.get("reflection")
        return cls(
            **cls._counters_from_dict(data),
            evaluation=(
                None
                if evaluation is None
                else cls(**cls._counters_from_dict(evaluation))
            ),
            reflection=(
                None
                if reflection is None
                else cls(**cls._counters_from_dict(reflection))
            ),
        )

    @staticmethod
    def _counters_from_dict(data: dict[str, Any]) -> dict[str, Any]:
        """Read the five counters of a serialized rollup.

        Args:
            data: A serialized rollup.

        Returns:
            Keyword arguments for the five counters.

        Raises:
            KeyError: If a row count is missing from the dict.
        """
        return {
            "input_tokens": _unknown_or_int(data.get("input_tokens")),
            "output_tokens": _unknown_or_int(data.get("output_tokens")),
            "total_tokens": _unknown_or_int(data.get("total_tokens")),
            "rows_counted": data["rows_counted"],
            "rows_unknown": data["rows_unknown"],
        }

@dataclass(slots=True, frozen=True)
class VideoFileInfo:
    """Metadata for a validated video file.

    This is an immutable record containing validated metadata about a video
    file. Created by VideoBlobService.validate_video_file() after checking
    that the file exists, is within size limits, and has a valid MIME type.

    Attributes:
        path (str): Absolute path to the video file.
        size_bytes (int): File size in bytes.
        mime_type (str): MIME type of the video (e.g., "video/mp4").

    Examples:
        Creating video file info:

        ```python
        from gepa_adk.domain.models import VideoFileInfo

        info = VideoFileInfo(
            path="/data/video.mp4",
            size_bytes=1024000,
            mime_type="video/mp4",
        )
        print(f"File: {info.path}, Size: {info.size_bytes}, Type: {info.mime_type}")
        ```

    Notes:
        A frozen dataclass ensuring immutability after validation.
        Instances cannot be modified once created, guaranteeing
        consistency of validated file metadata.
    """

    path: str
    size_bytes: int
    mime_type: str

@dataclass(slots=True, kw_only=True)
class EvolutionConfig:
    """Configuration parameters for an evolution run.

    Defines the parameters that control how evolution proceeds, including
    iteration limits, concurrency settings, and stopping criteria.

    Attributes:
        max_iterations (int): Maximum number of evolution iterations. 0 means
            just evaluate baseline without evolving.
        max_concurrent_evals (int): Maximum concurrent evaluation rows per batch
            in evolve(). Does not apply to evolve_group() or evolve_workflow().
            Must be at least 1.
        min_improvement_threshold (float): Minimum score improvement to accept
            a new candidate. Set to 0.0 to accept any improvement.
        patience (int): Number of iterations without improvement before stopping
            early. Set to 0 to disable early stopping.
        reflection_model (str | BaseLlm): Model for reflection/mutation
            operations: a non-empty model identifier string or a ``BaseLlm``
            instance (e.g. a ``LiteLlm`` with a custom ``api_base`` or
            temperature), which is passed to the reflection agent unchanged.
        frontier_type (FrontierType): Frontier tracking strategy for Pareto
            selection (default: INSTANCE). OBJECTIVE, HYBRID and CARTESIAN
            require per-example objective scores. The single-agent adapter
            forwards non-empty ``dimension_scores`` dictionaries from scorer
            metadata automatically when every example provides them; mixed
            batches raise ``ConfigurationError`` naming the example index.
        acceptance_metric (Literal["sum", "mean"]): Aggregation method for
            acceptance decisions on iteration evaluation batches. "sum" uses
            sum of scores (default, aligns with upstream GEPA). "mean" uses
            mean of scores (legacy behavior).
        use_merge (bool): Enable merge proposals for genetic crossover.
            Defaults to False.
        max_merge_invocations (int): Maximum number of merge attempts per run.
            Defaults to 10. Must be non-negative.
        reflection_prompt (str | None): Custom reflection/mutation prompt template.
            If provided, this template is used instead of the default when the
            reflection model proposes improved text. Required placeholders:
            - {component_text}: The current component text being evolved
            - {trials}: Trial data with feedback and trajectory for each test case
            If None or empty string, the default prompt template is used.
        stop_callbacks (list[StopperProtocol]): List of stopper callbacks for
            custom stop conditions. Each callback receives a StopperState and
            returns True to signal stop. Defaults to an empty list.
        seed (int | None): Random seed for deterministic engine decisions.
            When set, a seeded ``random.Random`` is created and shared across
            all stochastic components (candidate selector, merge proposer).
            ``None`` (default) preserves current random behavior.
        reflection_max_trials (int | None): Maximum number of trials per
            component sent to the reflection prompt. When a component has
            more, failing trials (score below 1.0) fill up to half the slots
            (rounded up) and passing trials fill the rest, each in batch
            order. ``None`` (default) sends every trial. Must be at least 1.
        reflection_max_trial_chars (int | None): Maximum length of any string
            value inside a trial sent to the reflection prompt, at any depth.
            Longer strings are cut and end with a
            ``…[truncated, N chars omitted]`` marker. ``None`` (default)
            leaves strings intact. Must be at least 1.
        reflection_timeout_seconds (int | None): Seconds the reflection agent
            may run for one proposal before the executor stops it. ``None``
            (default) keeps the executor's own default (300 seconds in
            ``AgentExecutor``). A timed-out reflection skips the iteration
            with ``skip_reason="reflection_timeout"`` and counts toward
            ``patience``; a reflection that keeps raising a retryable
            provider error after one retry is skipped the same way with
            ``skip_reason="reflection_error"``, and one cut off at the
            output-token limit (or opening a reasoning tag it never closes)
            with ``skip_reason="incomplete_proposal"``. Must be an ``int`` (not
            ``bool``) of at least 1.
        max_consecutive_reflection_errors (int): Number of consecutive
            ``reflection_error`` skips whose causes share the same exception
            type and message after which the engine stops retrying and raises
            a non-retryable ``ReflectionError`` carrying the partial result
            (``StopReason.ERROR``). A different error, or any other
            iteration in between, resets the count. Defaults to 3. Must be at least 1.
        reflection_minibatch_size (int | None): Number of trainset rows a
            proposal runs on before it earns its full evaluation. Each
            iteration the engine draws a fresh seeded sample of this many
            rows, evaluates the proposal on them and compares its mean score
            with the parent's cached scores on the same rows. Only a strictly
            higher mean earns the full trainset pass and the scoring pass; a
            proposal that loses or ties is recorded with
            ``skip_reason="minibatch_rejected"``. ``None`` (default), or a
            size at least the trainset size, evaluates every proposal on the
            full trainset. Must be an ``int`` of at least 1.
        on_iteration (OnIterationCallback | None): Called once per iteration,
            after its IterationRecord is appended to the history and before
            stop conditions are checked, with the record and the id of the
            candidate it concerns. Skipped iterations are reported too: an
            ``empty_proposal`` skip passes ``None`` as the id and a
            ``duplicate`` skip passes the duplicate proposal's id. The baseline
            evaluation triggers no call. An awaitable return value is awaited
            before the loop continues, and an exception raised by the callback
            propagates out of ``run()``. ``None`` (default) disables it.
        proposal_validator (ProposalValidator | None): Called with each
            evolved component's name and proposed text after reflection and
            before schema validation or evaluation. The first non-None
            return rejects the proposal: the iteration is recorded with
            ``skip_reason="proposal_rejected"``, ``score=0.0`` and the reason
            in ``rejection_reason``, nothing is evaluated, and the rejection
            counts toward ``patience``. An exception raised by the validator
            propagates out of ``run()``. ``None`` (default) accepts every
            proposal.
        checkpoint_path (Path | str | None): JSON file the engine writes its state
            to after the baseline and after every recorded iteration,
            atomically (a temporary file beside it, then ``os.replace``).
            A ``str`` is converted to ``Path`` in ``__post_init__``, so the
            stored value is a ``Path`` or ``None``. ``None`` (default) writes no
            checkpoint. The engine refuses it together with a
            ``candidate_selector``, because Pareto state is not checkpointed.
        resume (bool): When True, ``run()`` restores the state in
            ``checkpoint_path`` instead of evaluating the baseline, and
            continues the iteration count, the stagnation counter and the
            evaluation counter without re-evaluating a scored candidate.
            Requires ``checkpoint_path``. Defaults to False, which starts
            fresh and overwrites an existing checkpoint on its first write.

    Examples:
        Creating a configuration with defaults:

        ```python
        from gepa_adk.domain.models import EvolutionConfig

        config = EvolutionConfig(max_iterations=100, patience=10)
        print(config.max_iterations)  # 100
        print(config.reflection_model)  # ollama_chat/gpt-oss:20b
        print(config.max_consecutive_reflection_errors)  # 3
        ```

        Aborting after the first repeat of an identical reflection error:

        ```python
        config = EvolutionConfig(max_consecutive_reflection_errors=2)
        ```

    Notes:
        All numeric parameters are validated in __post_init__ to ensure
        they meet their constraints. Cross-field consistency is also checked
        (e.g., use_merge requires max_merge_invocations > 0, stop_callbacks,
        on_iteration and proposal_validator must be callable). Invalid values
        raise ConfigurationError.

        Determinism applies to engine decisions only (candidate selection,
        component selection, merge proposals). LLM inference is inherently
        stochastic and not covered by the seed guarantee.
    """

    max_iterations: int = 50
    max_concurrent_evals: int = 5
    min_improvement_threshold: float = 0.01
    patience: int = 5
    reflection_model: "str | BaseLlm" = "ollama_chat/gpt-oss:20b"
    frontier_type: FrontierType = FrontierType.INSTANCE
    acceptance_metric: Literal["sum", "mean"] = "sum"
    use_merge: bool = False
    max_merge_invocations: int = 10
    reflection_prompt: str | None = None
    stop_callbacks: list["StopperProtocol"] = field(default_factory=list)
    seed: int | None = None
    reflection_max_trials: int | None = None
    reflection_max_trial_chars: int | None = None
    reflection_timeout_seconds: int | None = None
    max_consecutive_reflection_errors: int = 3
    reflection_minibatch_size: int | None = None
    on_iteration: OnIterationCallback | None = None
    proposal_validator: ProposalValidator | None = None
    checkpoint_path: Path | str | None = None
    resume: bool = False

    def __post_init__(self) -> None:
        """Validate configuration parameters after initialization.

        Raises:
            ConfigurationError: If any parameter violates its constraints,
                including non-finite floats (NaN, Inf), cross-field consistency
                rules (e.g., use_merge requires max_merge_invocations > 0,
                stop_callbacks, on_iteration and proposal_validator must be
                callable), a reflection cap (reflection_max_trials,
                reflection_max_trial_chars) below 1, a
                ``max_consecutive_reflection_errors`` below 1, a
                ``reflection_timeout_seconds`` or ``reflection_minibatch_size``
                that is not ``None`` or an
                ``int`` of at least 1, or a ``reflection_model`` that is
                ``None`` or an empty string, or ``resume=True`` without a
                ``checkpoint_path``.

        Notes:
            Operates automatically after dataclass __init__ completes. Validates
            all fields including finite-float checks, cross-field consistency,
            and raises ConfigurationError with context on failure. A non-string
            ``reflection_model`` passes this check; the resolver in
            ``gepa_adk.api`` rejects values that are not a ``BaseLlm``.
            A ``str`` ``checkpoint_path`` is converted to ``Path``.
        """
        if self.max_iterations < 0:
            raise ConfigurationError(
                "max_iterations must be non-negative",
                field="max_iterations",
                value=self.max_iterations,
                constraint=">= 0",
            )

        if self.max_concurrent_evals < 1:
            raise ConfigurationError(
                "max_concurrent_evals must be at least 1",
                field="max_concurrent_evals",
                value=self.max_concurrent_evals,
                constraint=">= 1",
            )

        if self.max_consecutive_reflection_errors < 1:
            raise ConfigurationError(
                "max_consecutive_reflection_errors must be at least 1",
                field="max_consecutive_reflection_errors",
                value=self.max_consecutive_reflection_errors,
                constraint=">= 1",
            )

        if not math.isfinite(self.min_improvement_threshold):
            raise ConfigurationError(
                "min_improvement_threshold must be a finite number",
                field="min_improvement_threshold",
                value=self.min_improvement_threshold,
                constraint="finite float",
            )

        if self.min_improvement_threshold < 0.0:
            raise ConfigurationError(
                "min_improvement_threshold must be non-negative",
                field="min_improvement_threshold",
                value=self.min_improvement_threshold,
                constraint=">= 0.0",
            )

        if self.patience < 0:
            raise ConfigurationError(
                "patience must be non-negative",
                field="patience",
                value=self.patience,
                constraint=">= 0",
            )

        if not self.reflection_model:
            raise ConfigurationError(
                "reflection_model must be a non-empty string or BaseLlm instance",
                field="reflection_model",
                value=self.reflection_model,
                constraint="non-empty string",
            )

        if not isinstance(self.frontier_type, FrontierType):
            try:
                self.frontier_type = FrontierType(self.frontier_type)
            except ValueError as exc:
                raise ConfigurationError(
                    "frontier_type must be a supported FrontierType value",
                    field="frontier_type",
                    value=self.frontier_type,
                    constraint=", ".join(t.value for t in FrontierType),
                ) from exc

        if self.acceptance_metric not in ("sum", "mean"):
            raise ConfigurationError(
                "acceptance_metric must be 'sum' or 'mean'",
                field="acceptance_metric",
                value=self.acceptance_metric,
                constraint="sum|mean",
            )

        if self.max_merge_invocations < 0:
            raise ConfigurationError(
                "max_merge_invocations must be non-negative",
                field="max_merge_invocations",
                value=self.max_merge_invocations,
                constraint=">= 0",
            )

        self._validate_reflection_caps()
        self._validate_reflection_timeout()
        self._validate_minibatch_size()
        self._validate_checkpoint()

        # Cross-field consistency checks
        self._validate_consistency()

        # Validate reflection_prompt if provided
        self._validate_reflection_prompt()

    def _validate_reflection_caps(self) -> None:
        """Validate the optional caps on what the reflector sees.

        Raises:
            ConfigurationError: If ``reflection_max_trials`` or
                ``reflection_max_trial_chars`` is set to a value below 1.
        """
        for name, value in (
            ("reflection_max_trials", self.reflection_max_trials),
            ("reflection_max_trial_chars", self.reflection_max_trial_chars),
        ):
            if value is not None and value < 1:
                raise ConfigurationError(
                    f"{name} must be at least 1 or None",
                    field=name,
                    value=value,
                    constraint=">= 1 or None",
                )

    def _validate_reflection_timeout(self) -> None:
        """Validate the optional reflection timeout.

        Raises:
            ConfigurationError: If ``reflection_timeout_seconds`` is set and
                is not an ``int`` (a ``bool`` is rejected) of at least 1.
        """
        value = self.reflection_timeout_seconds
        if value is None:
            return
        if isinstance(value, bool) or not isinstance(value, int) or value < 1:
            raise ConfigurationError(
                "reflection_timeout_seconds must be an int of at least 1 or None",
                field="reflection_timeout_seconds",
                value=value,
                constraint="int >= 1 or None",
            )

    def _validate_minibatch_size(self) -> None:
        """Validate the optional reflection minibatch size.

        Raises:
            ConfigurationError: If ``reflection_minibatch_size`` is neither
                ``None`` nor an ``int`` (a ``bool`` does not count) of at
                least 1.
        """
        value = self.reflection_minibatch_size
        if value is None:
            return
        if isinstance(value, bool) or not isinstance(value, int) or value < 1:
            raise ConfigurationError(
                "reflection_minibatch_size must be an int of at least 1 or None",
                field="reflection_minibatch_size",
                value=value,
                constraint="int >= 1 or None",
            )

    def _validate_checkpoint(self) -> None:
        """Normalise ``checkpoint_path`` and check ``resume`` against it.

        Raises:
            ConfigurationError: If ``checkpoint_path`` is neither None, a
                ``str`` nor a ``Path``, or if ``resume`` is True and
                ``checkpoint_path`` is None.
        """
        if isinstance(self.checkpoint_path, str):
            self.checkpoint_path = Path(self.checkpoint_path)
        elif self.checkpoint_path is not None and not isinstance(
            self.checkpoint_path, Path
        ):
            raise ConfigurationError(
                "checkpoint_path must be a str, a Path or None",
                field="checkpoint_path",
                value=self.checkpoint_path,
                constraint="str, Path or None",
            )
        if self.resume and self.checkpoint_path is None:
            raise ConfigurationError(
                "resume=True requires checkpoint_path",
                field="checkpoint_path",
                value=None,
                constraint="not None when resume=True",
            )

    def _validate_consistency(self) -> None:
        """Validate cross-field consistency rules.

        Raises:
            ConfigurationError: If use_merge is True but max_merge_invocations
                is zero, if stop_callbacks contains non-callable items, or if
                on_iteration or proposal_validator is set and not callable.

        Notes:
            Hard errors raise ConfigurationError; soft issues log warnings.
            Called from __post_init__ after individual field validation.
        """
        if self.use_merge and self.max_merge_invocations == 0:
            raise ConfigurationError(
                "use_merge=True requires max_merge_invocations > 0",
                field="max_merge_invocations",
                value=self.max_merge_invocations,
                constraint="> 0 when use_merge=True",
            )

        if (
            self.patience > 0
            and self.max_iterations > 0
            and self.patience > self.max_iterations
        ):
            logger.warning(
                "config.patience.exceeds_max_iterations",
                patience=self.patience,
                max_iterations=self.max_iterations,
                message="patience exceeds max_iterations; early stopping will never trigger",
            )

        for i, callback in enumerate(self.stop_callbacks):
            if not callable(callback):
                raise ConfigurationError(
                    f"stop_callbacks[{i}] is not callable",
                    field=f"stop_callbacks[{i}]",
                    value=type(callback).__name__,
                    constraint="must be callable",
                )

        if self.on_iteration is not None and not callable(self.on_iteration):
            raise ConfigurationError(
                "on_iteration is not callable",
                field="on_iteration",
                value=type(self.on_iteration).__name__,
                constraint="must be callable or None",
            )

        if self.proposal_validator is not None and not callable(
            self.proposal_validator
        ):
            raise ConfigurationError(
                "proposal_validator is not callable",
                field="proposal_validator",
                value=type(self.proposal_validator).__name__,
                constraint="must be callable or None",
            )

    def _validate_reflection_prompt(self) -> None:
        """Validate reflection_prompt and handle empty string.

        Converts empty string to None with info log. Warns if required
        placeholders are missing but allows the config to be created.

        Notes:
            Soft validation approach - missing placeholders trigger warnings
            but don't prevent config creation for maximum flexibility.
        """
        # Handle empty string as "use default"
        if self.reflection_prompt == "":
            logger.info(
                "config.reflection_prompt.empty",
                message="Empty reflection_prompt provided, using default template",
            )
            # Use object.__setattr__ because slots=True prevents direct assignment
            object.__setattr__(self, "reflection_prompt", None)
            return

        # Skip validation if None
        if self.reflection_prompt is None:
            return

        # Warn about missing placeholders
        if "{component_text}" not in self.reflection_prompt:
            logger.warning(
                "config.reflection_prompt.missing_placeholder",
                placeholder="component_text",
                message="reflection_prompt is missing {component_text} placeholder",
            )

        if "{trials}" not in self.reflection_prompt:
            logger.warning(
                "config.reflection_prompt.missing_placeholder",
                placeholder="trials",
                message="reflection_prompt is missing {trials} placeholder",
            )