Each Oracle class implements a particular hyperparameter tuning algorithm. An Oracle is passed as an argument to a Tuner. The Oracle tells the Tuner which hyperparameters should be tried next.

Most Oracle classes can be combined with any user-defined Tuner subclass. Hyperband requires the Tuner class to implement additional Oracle-specific functionality (see Hyperband documentation). If you do not need to subclass Tuner (the most common case), we also provide a number of convenience classes that package a Tuner and an Oracle together (e.g kerastuner.RandomSearch, kerastuner.BayesianOptimization, and kerastuner.Hyperband).


BayesianOptimizationOracle class:

kerastuner.oracles.BayesianOptimization(objective, max_trials, num_initial_points=None, alpha=0.0001, beta=2.6, seed=None, hyperparameters=None, allow_new_entries=True, tune_new_entries=True)

Bayesian optimization oracle.

It uses Bayesian optimization with a underlying Gaussian process model. The acquisition function used is upper confidence bound (UCB), which can be found in the following link:



HyperbandOracle class:

kerastuner.oracles.Hyperband(objective, max_epochs, factor=3, hyperband_iterations=1, seed=None, hyperparameters=None, allow_new_entries=True, tune_new_entries=True)

Oracle class for Hyperband.

Note that to use this Oracle with your own subclassed Tuner, your Tuner class must be able to handle in Tuner.run_trial three special hyperparameters that will be set by this Tuner:

These hyperparameters will be set during the "successive halving" portion of the Hyperband algorithm.

Example run_trial:

def run_trial(self, trial, *args, **kwargs):
    hp = trial.hyperparameters
    if "tuner/trial_id" in hp:
        past_trial =['tuner/trial_id'])
        model = self.load_model(past_trial)
        model =

    initial_epoch = hp['tuner/initial_epoch']
    last_epoch = hp['tuner/epochs']

    for epoch in range(initial_epoch, last_epoch):
        for step in range(...):
            # Run model training step here.



RandomSearchOracle class:

kerastuner.oracles.RandomSearch(objective, max_trials, seed=None, hyperparameters=None, allow_new_entries=True, tune_new_entries=True)

Random search oracle.



Oracle class:, max_trials=None, hyperparameters=None, allow_new_entries=True, tune_new_entries=True)

Implements a hyperparameter optimization algorithm.

Attributes: objective: String. Name of model metric to minimize or maximize, e.g. "val_accuracy". max_trials: The maximum number of hyperparameter combinations to try. hyperparameters: HyperParameters class instance. Can be used to override (or register in advance) hyperparamters in the search space. tune_new_entries: Whether hyperparameter entries that are requested by the hypermodel but that were not specified in hyperparameters should be added to the search space, or not. If not, then the default value for these parameters will be used. allow_new_entries: Whether the hypermodel is allowed to request hyperparameter entries not listed in hyperparameters.

_populate_space method:


Fill the hyperparameter space with values for a trial.

This method should be overridden in subclasses and called in create_trial in order to populate the hyperparameter space with values.

Args: trial_id: The id for this Trial.

Returns: A dictionary with keys "values" and "status", where "values" is a mapping of parameter names to suggested values, and "status" is the TrialStatus that should be returned for this trial (one of "RUNNING", "IDLE", or "STOPPED").

_score_trial method:


Score a completed Trial.

This method can be overridden in subclasses to provide a score for a set of hyperparameter values. This method is called from end_trial on completed Trials.

Args: trial: A completed Trial object.

create_trial method:


Create a new Trial to be run by the Tuner.

A Trial corresponds to a unique set of hyperparameters to be run by Tuner.run_trial.

Args: tuner_id: A ID that identifies the Tuner requesting a Trial. Tuners that should run the same trial (for instance, when running a multi-worker model) should have the same ID.

Returns: A Trial object containing a set of hyperparameter values to run in a Tuner.

end_trial method:

Oracle.end_trial(trial_id, status='COMPLETED')

Record the measured objective for a set of parameter values.

Args: trial_id: String. Unique id for this trial. status: String, one of "COMPLETED", "INVALID". A status of "INVALID" means a trial has crashed or been deemed infeasible.

get_best_trials method:


Returns the best Trials.

get_state method:


Returns the current state of this object.

This method is called during save.

set_state method:


Sets the current state of this object.

This method is called during reload.


state: Dict. The state to restore for this object.

update_trial method:

Oracle.update_trial(trial_id, metrics, step=0)

Used by a worker to report the status of a trial.

Args: trial_id: A previously seen trial id. metrics: Dict of float. The current value of this trial's metrics. step: (Optional) Float. Used to report intermediate results. The current value in a timeseries representing the state of the trial. This is the value that metrics will be associated with.

Returns: Trial object. Trial.status will be set to "STOPPED" if the Trial should be stopped early.