bbt-tuner 0.1.0

Adaptive Top-2 Bounding-Box Hyperparameter Tuner

Bounding-Box Tuner (BBT)

Adaptive Top-2 Bounding-Box Hyperparameter Tuner
Lightweight hyperparameter search with median-based early pruning.

Bounding-Box Tuner (BBT) implements a simple but effective strategy to balance exploration and exploitation:

1. Top-2 bounding box sampling: At each iteration, define a hyper-rectangular “box” around your two best configurations and sample new candidates inside it.
2. Adaptive exploration schedule: Start with 35 % global random sampling, then decay to 10 % to focus on the promising region. (It can be adjusted)
3. Median-based partial-training pruning: After every epoch e, prune any trial whose validation score falls below the median of all previous epoch-e scores.
4. Optional parallel evaluation via n_workers.

---

🚀 Features

• Easy integration: Plug BBT into any training loop via a one-line objective function
• Fast partial training: Each trial runs for up to max_epochs epochs, but can be cut short if it underperforms
• Minimal dependencies: Only standard Python libraries (numpy, scipy, statistics)
• Configurable: Control total trials (max_trials), warm-up samples (init_samples), early stops, and more
• Parallel evaluation: run up to n_workers trials concurrently
• Configurable exploration: set your own explore_rate_start & explore_rate_end

---

🔧 Installation

Install directly from GitHub:

git clone https://github.com/abdulvahapmutlu/bounding-box-tuner-bbt.git
cd bounding-box-tuner-bbt
pip install -r requirements.txt

---

⚡ Quickstart

from bbt.tuner import adaptive_top2_box_tuner
from bbt.utils import param_space_dict

def objective_fn(params, train_ds, val_ds, epoch):
    """
    Train one epoch with `params` on train_ds,
    evaluate on val_ds, and return a scalar metric.
    """
    # YOUR TRAINING LOOP HERE
    return val_accuracy

best_params, best_score, trials_log, elapsed = adaptive_top2_box_tuner(
    train_dataset=my_train_ds,
    val_dataset=my_val_ds,
    param_space_dict=param_space_dict,
    objective_fn=objective_fn,
    max_trials=30,
    init_samples=5,
    early_stopping_rounds=10,
    max_epochs=5,
    explore_rate_start=0.35,    # initial random-sampling probability
    explore_rate_end=0.10,      # final random-sampling probability
    n_workers=0                 # number of parallel workers
)

print("Best params:", best_params)
print("Best validation score:", best_score)
print(f"Ran {len(trials_log)} trials in {elapsed:.1f}s.")

---

📚 API Reference

adaptive_top2_box_tuner(...)

adaptive_top2_box_tuner(
    train_dataset,
    val_dataset,
    param_space_dict: dict,
    objective_fn: Callable[[dict, Any, Any, int], float],
    max_trials: int = 50,
    init_samples: int = 10,
    early_stopping_rounds: int = 30,
    max_epochs: int = 5,
    explore_rate_start: float = 0.35,
    explore_rate_end: float = 0.10,
    n_workers: int = 1,
) -> Tuple[dict, float, List[dict], float]

• Returns

  1. best_params (dict): highest-scoring hyperparameter set

  2. best_score (float): corresponding validation metric

  3. trials_log (list of dict)

  4. total_time (float)

     • "params": dict
     • "score": float
     • "pruned": bool
     • "epoch_scores": {epoch: score}

  5. total_time (float): elapsed seconds

• Key args

  • param_space_dict: map each hyperparameter to its sampling info (min/max, type, etc.)
  • objective_fn: called once per epoch—return validation score
  • max_trials, init_samples, early_stopping_rounds, max_epochs: control search budget & pruning
  • explore_rate_start: starting probability of global random sampling
  • explore_rate_end: ending probability of global random sampling
  • n_workers: number of parallel processes (uses multiprocessing.Pool)

See bbt/utils.py for helpers:

• sample_valid_params(param_space_dict)
• sample_valid_params_bounding_box(box)

---

🙌 Contributing

1. Fork the repo
2. Create a branch: git checkout -b feature/YourFeature
3. Write code & tests
4. Open a Pull Request

Please follow PEP 8 and include tests for new functionality.

---

📄 License

This project is licensed under the MIT License. See LICENSE for details.