Tuners

@dataclass(frozen=True)
class Observation:
    """One parameter set the tuner may learn from: `score` is the trial's
    raw journal-direction score (None = that set failed); `pending` marks a
    set in flight on the same candidate (a constant-liar hint)."""

    params: dict
    score: float | None
    pending: bool = False


class Tuner(Protocol):
    name: str
    params: dict  # persisted verbatim into SearchMeta.tuner_params for resume

    def ask(
        self,
        space: "ParamSpace",
        history: Sequence[Observation],
        *,
        higher_is_better: bool,
        seed: int,
    ) -> dict:
        """The next parameter set to evaluate (every declared name present,
        values inside the declared domain)."""
        ...