---

name: optimizer-workflows description: "Use BayesianOptimization for ordinary black-box optimization, manual ask-tell loops, persistence, prediction, and small ML hyperparameter optimization." disable-model-invocation: true metadata: disco-role: operating license: MIT

Optimizer Workflows

Use this sub-skill when a user wants to run the core bayes_opt.BayesianOptimization lifecycle for a black-box objective or a small machine-learning hyperparameter optimization job. This route is self-contained: future agents should not need to open the original repository docs, notebooks, tests, or examples.

Load This When

• The user has a Python function or external evaluation service and wants to optimize scalar parameters with Bayesian optimization.
• The task mentions BayesianOptimization, pbounds, maximize, max, res, probe, register, suggest, random_sample, set_bounds, set_gp_params, save_state, load_state, or predict.
• The user asks how to turn a loss into an optimization target, persist an optimizer, resume a run, validate results, or handle duplicate/noisy observations.
• The user wants a tiny scikit-learn HPO pattern using bayesian-optimization.

Core Rules To Apply First

1. The package maximizes target values. Convert losses to scores, commonly by returning -loss or using a scikit-learn scorer whose larger value is better.
2. pbounds keys must match the objective function keyword arguments exactly. Dict inputs are safest. Array/list inputs use the pbounds insertion order.
3. Keep objective functions deterministic enough for the GP when possible. For noisy objectives, set allow_duplicate_points=True only when repeated evaluations at the same coordinates are intentional.
4. Use f=None only for manual ask-tell loops: call suggest(), evaluate outside the optimizer, then register(params, target). Do not call eager probe(..., lazy=False) or maximize() with f=None.
5. After maximize(), call predict(..., fit_gp=True) before relying on GP predictions; the final registered point may not be included in the fitted GP until prediction refits it.
6. Save/load state as JSON with a newly constructed compatible optimizer: same objective-compatible kwargs, pbounds, acquisition strategy, constraints, duplicate policy, and any bounds transformer.

Bundled References

• API reference: constructor and method signatures, lifecycle semantics, TargetSpace result behavior, predict return shapes, and state persistence details.
• Workflow recipes: basic optimization, manual ask-tell evaluations, tiny HPO patterns, loss sign handling, persistence, duplicate/noisy recipes, bounds updates, and result validation.
• Troubleshooting: symptoms, causes, and fixes for key mismatches, duplicate points, unfitted GP errors, stale state loads, target-sign mistakes, bounds/type changes, slow objectives, and f=None misuse.

Bundled Smoke Scripts

• scripts/bo_core_smoke.py: deterministic core API smoke test. It runs a tiny optimizer, validates max/res, exercises probe, register, suggest, random_sample, set_bounds, set_gp_params, predict, duplicate handling, and optional JSON save/load.
• scripts/sklearn_hpo_smoke.py: deterministic tiny scikit-learn HPO diagnostic with synthetic data. It demonstrates both maximizing a score and negating a loss, with safe integer casting for model hyperparameters.

Run scripts only in an environment where bayesian-optimization and its normal Python dependencies are installed. Both scripts support --help, use bounded synthetic data, do not download from the network, and avoid destructive writes.

Routing Boundaries

Stay in this sub-skill for the optimizer lifecycle, public result validation, manual ask-tell loops, persistence/resume patterns, predict semantics, noisy or duplicate objectives, bounds updates, GP parameter tuning through set_gp_params, and ordinary small HPO recipes.

Route elsewhere for features that have distinct APIs or deeper contracts:

• Acquisition choices, custom acquisition functions, ConstantLiar, GPHedge, and exploration/exploitation controls: ../acquisition-control/SKILL.md.
• Constraints, typed/categorical parameters beyond simple wrapper casting, custom BayesParameter, and sequential domain reduction: ../advanced-domain-features/SKILL.md.
• Repository editing, tests, docs, release, packaging, linting, and maintainer workflows: ../repo-maintenance/SKILL.md.

Minimal Decision Flow

1. Identify objective type:
   • In-process Python function: create BayesianOptimization(f=objective, ...).
   • External/manual evaluation: create BayesianOptimization(f=None, ...) and use ask-tell with suggest()/register().
2. Define pbounds with exact parameter names and realistic finite bounds. Prefer log-transformed parameters for scale-sensitive HPO (log10_C, log_learning_rate) and transform inside the objective wrapper.
3. Choose a budget. For smoke tests use tiny values such as init_points=2, n_iter=2; for expensive tasks, increase only after validating objective sign, result shape, and runtime.
4. Run maximize(init_points=..., n_iter=...) or the ask-tell loop.
5. Validate optimizer.max is not None, has keys target and params, all returned params are within intended bounds, len(optimizer.res) matches the number of registered observations, and the best target uses the intended metric sign.
6. Persist long or expensive runs with save_state(path). To resume, recreate a compatible optimizer and call load_state(path) before more suggestions or maximize(init_points=0, n_iter=...).
7. If predictions or uncertainty are needed, call predict() with explicit fit_gp=True after at least one observation; use return_std=True or return_cov=True, never both.

Handoff Checklist For Future Agents

• Objective wrapper returns a finite scalar target and uses the correct sign.
• pbounds keys and objective kwargs match exactly.
• Random seeds are set where reproducibility matters.
• allow_duplicate_points is justified for noise; otherwise duplicate errors are treated as a signal to change the loop.
• State files are JSON and loaded into an optimizer with compatible settings.
• Any advanced acquisition, constraint, typed-parameter, or domain-reduction need has been routed to the sibling sub-skill instead of duplicated here.