Struct OnlineTuner 

pub struct OnlineTuner { /* private fields */ }

A real-time, in-loop hyperparameter tuner.

Construct one with OnlineTuner::builder; drive it with suggest/observe once per training round (or the combined drive_round). See the module documentation for the full contract.

Implementations

impl OnlineTuner

pub fn builder() -> OnlineTunerBuilder

Starts building a tuner. The default direction is Direction::Maximize and the default policy is the clustered UCB bandit with the default window (Mabc::ucb_default).

pub fn suggest(&mut self) -> Choice<'_>

The hyperparameter choices for the coming round, one per cluster.

O(clusters × arms) (arms is a small constant) and allocation-free: it rewrites the preallocated choice buffer in place and returns a borrowed Choice. Call it once per round, before observe.

pub fn observe(&mut self, round_return: f64)

Credits round_return to the arms/knobs the last suggest chose, sliding the policy forward one round. O(clusters) and allocation-free.

Direction is honoured here: under Direction::Minimize a smaller return is better. Call once per round, after suggest.

pub fn drive_round<F>(&mut self, run: F)

where F: FnOnce(&Choice<'_>) -> f64,

Runs one round through the tuner: suggest, evaluate, observe.

The oniro-free shape of the per-round callback seam: run receives the round’s Choice and returns the round’s return, which is then observed. Exactly equivalent to a manual suggest/observe pair, but it keeps the borrow scoping correct for you.

pub const fn rounds(&self) -> u64

The number of rounds observed so far.

pub fn clusters(&self) -> usize

The number of clusters this tuner manages.

pub const fn direction(&self) -> Direction

The optimization direction.

pub fn is_flush_boundary(&self) -> bool

true when the round just observed lands on a flush interval boundary — the caller’s cue to snapshot the tuner into a journal (off the hot path). Always false if no interval was configured with OnlineTunerBuilder::flush_every.

pub fn snapshot(&self) -> Result<StateBlob>

Serializes the full tuner state into a versioned StateBlob.

This allocates (it builds JSON) and is meant to be called at interval boundaries — is_flush_boundary — never on the hot path. A caller persists the blob through any Storage::put_state to make the online run a replayable, resumable study.

Errors

Error::Storage if the state cannot be serialized — which for JSON means a non-finite windowed sum, i.e. a non-finite return was observed.

pub fn restore(&mut self, blob: &StateBlob) -> Result<()>

Restores tuner state from a snapshot blob.

The snapshot must describe the same shape — same cluster names, same policy, same arm counts and window — as this tuner, or the restore is refused rather than silently loading mismatched state.

Errors

Error::Storage if the blob is not an ONLINE_BLOB_KIND payload, cannot be decoded, or does not match this tuner’s shape.

Trait Implementations

impl Debug for OnlineTuner

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.