API Reference / base /

tuning.py

Base classes for hyperparameter tuning.

Classes

TuningResult

class base.tuning.TuningResult

Encapsulates the outcome of a hyperparameter optimization run.

Attributes

best_params
dict
The configuration of parameters yielding the highest score.
best_score
float
The validation score achieved by the best_params.
best_estimator
Any
The model instance retrained on the full dataset using best_params.
cv_results
dict
A comprehensive log of all evaluation scores, split times, and parameter combinations.
n_iterations
int
The total number of parameter variations explored.
total_time
float
The wall-clock time consumed by the entire search in seconds.

See Also

BaseTuner

Produces these results.

ParameterGrid

class base.tuning.ParameterGrid

Cartesian product of parameter values for exhaustive search.

Generates every possible combination of parameter values defined in the search space.
Constructor 
__init__(
    self,
    param_grid: Union[Dict, List[Dict]],
)

Parameters

param_grid
dict or list of dict
A dictionary where keys are parameter names and values are lists of settings to try. Alternatively, a list of such dictionaries to define disjoint search spaces.

See Also

ParameterDistribution

Sampled search spaces for random search.

Exhaustively search a support vector machine space:

python 
>>> from tuiml.base import ParameterGrid
>>> grid = ParameterGrid({'C': [1, 10], 'kernel': ['linear', 'rbf']})
>>> len(grid)
4
>>> list(grid)[0]
{'C': 1, 'kernel': 'linear'}

ParameterDistribution

class base.tuning.ParameterDistribution

Distribution of parameters for random search.

Constructor 
__init__(
    self,
    param_distributions: Dict,
)

Parameters

param_distributions
dict

Dictionary with parameters as keys and distributions as values. Values can be:

  • •List: uniform choice from list
  • •Tuple (low, high): uniform continuous
  • •Tuple (low, high, 'log'): log-uniform
  • •Tuple (low, high, 'int'): uniform integer
  • •Callable: distribution that returns a sample

See Also

ParameterGrid

Exhaustive search spaces for grid search.
python 
>>> from tuiml.base import ParameterDistribution
>>> dist = ParameterDistribution({
...     'C': (0.1, 10, 'log'),      # Log-uniform between 0.1 and 10
...     'kernel': ['linear', 'rbf'], # Uniform choice
...     'gamma': (0.001, 1)          # Uniform continuous
... })
>>> sample = dist.sample()

Methods

sample (self, random_state: Optional[int]=None) -> Dict[str, Any]

Sample one parameter combination from the distributions.

Parameters
random_state
int
Seed for the random number generator used for sampling.
Returns
params
dict
One sampled value per parameter.

BaseTuner

class base.tuning.BaseTuner(ABC)

Abstract base class for hyperparameter optimization strategies.

Tuners manage the selection of parameters, the execution of cross-validation, and the selection of the 'best' model configuration.
Constructor 
__init__(
    self,
    estimator,
    scoring: Union[str, Callable] = 'accuracy',
    cv: int = 5,
    refit: bool = True,
    verbose: int = 0,
    n_jobs: int = 1,
    random_seed: Optional[int] = None,
    progress_callback: Optional[Callable] = None,
)

Parameters

estimator
Algorithm
The model template to optimize.
scoring
str or callable = "accuracy"
The evaluation metric used to rank parameter combinations. Built-in options are "accuracy", "neg_mse", and "r2"; a callable must accept (y_true, y_pred) and return a float.
cv
int = 5
The number of folds for cross-validation.
refit
bool = True
Whether to retrain the model on the entire training set using the best found parameters after the search completes.
verbose
int = 0
The level of progress logging (higher values produce more detail).
n_jobs
int = 1
The number of parallel processes to use during cross-validation. Requires joblib; falls back to sequential execution otherwise.
random_seed
int
Seed for reproducible random sampling. If None, the global TuiML seed is used, falling back to 42.
progress_callback
callable
Function invoked with a progress dictionary after each evaluated parameter combination.

Attributes

best_params_
dict
Parameter combination with the highest mean cross-validation score.
best_score_
float
Mean cross-validation score of best_params_.
best_estimator_
Any
Estimator refitted on the full training data with best_params_ (available when refit=True).
cv_results_
dict
Log of scores, timings, and parameters for every combination tried.

See Also

ParameterGrid

Search space for grid search.
ParameterDistribution

Search space for random search.
TuningResult

Structured result container.

Methods

fit (self, X: np.ndarray, y: np.ndarray) -> 'BaseTuner'

Run the search to find the best parameters.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Training features.
y
np.ndarray of shape (n_samples,)
Target values.
Returns
self
BaseTuner
The fitted tuner, with best_params_, best_score_, best_estimator_, and cv_results_ populated.
predict (self, X: np.ndarray) -> np.ndarray

Predict with the best estimator found by the search.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
y_pred
np.ndarray of shape (n_samples,)
Predictions from best_estimator_.
Raises
RuntimeError
If the tuner has not been fitted yet.
score (self, X: np.ndarray, y: np.ndarray) -> float

Score the best estimator on the given data.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
y
np.ndarray of shape (n_samples,)
True target values.
Returns
score
float
Score of best_estimator_ under the tuner's scoring metric.