BayesianOptimization Repo Skill

Use this repo skill when a user asks about the bayesian-optimization package, its bayes_opt import, Gaussian-process Bayesian optimization, black-box function maximization, small hyperparameter optimization, acquisition functions, constraints, typed/categorical parameters, sequential domain reduction, or maintaining this package's source checkout.

This skill is self-contained. Do not send future agents to original repository notebooks or examples for package usage; use the bundled references and scripts below. Checkout-only test and docs commands are confined to the maintainer sub-skill.

Install and import baseline

Package users normally install one of:

pip install bayesian-optimization
conda install -c conda-forge bayesian-optimization

Minimal import check:

from bayes_opt import BayesianOptimization


def objective(x, y):
    return -x**2 - (y - 1.0) ** 2 + 1.0

optimizer = BayesianOptimization(
    f=objective,
    pbounds={"x": (-2.0, 2.0), "y": (-3.0, 3.0)},
    random_state=1,
    verbose=0,
)
optimizer.maximize(init_points=1, n_iter=1)
assert optimizer.max is not None

For an environment-level diagnostic, run scripts/check_env.py. Add --run-subskill-smokes when you want it to execute the bundled tiny smoke helpers as well.

Route map

Core optimizer and HPO workflows

Read sub-skills/optimizer-workflows/SKILL.md when the task involves:

• creating BayesianOptimization(f=..., pbounds=...);
• maximize, max, res, probe, register, suggest, or random_sample;
• manual ask-tell loops for external evaluations;
• saving/loading JSON state, changing bounds, tuning GP parameters, or using predict;
• converting a loss into a maximization target;
• small scikit-learn HPO recipes and validation.

Acquisition control

Read sub-skills/acquisition-control/SKILL.md when the task involves:

• UCB, Expected Improvement, Probability of Improvement, Constant Liar, or GPHedge;
• choosing exploration/exploitation settings such as kappa, xi, exploration_decay, and exploration_decay_delay;
• lower-level acquisition suggest(gp, target_space, n_random, n_smart, ...);
• asynchronous/batch-like suggestions, acquisition portfolios, or custom AcquisitionFunction subclasses;
• acquisition errors such as empty target spaces, invalid xi/kappa, stale UtilityFunction snippets, and constraint incompatibility.

Advanced domain features

Read sub-skills/advanced-domain-features/SKILL.md when the task involves:

• SciPy NonlinearConstraint and ConstraintModel;
• known constrained observations with constraint_value;
• integer bounds (low, high, int), categorical bounds, or custom BayesParameter subclasses;
• TargetSpace array/dict conversion, masks, and typed kernel transforms;
• SequentialDomainReductionTransformer, minimum_window, and all-float domain reduction limitations.

Repository maintenance

Read sub-skills/repo-maintenance/SKILL.md only when the user is editing or validating a bayesian-optimization source checkout. It covers focused pytest selection, Ruff/lint commands, notebook/docs checks, CI Python/NumPy matrix behavior, dependency markers, build validation, and release/publish boundaries. Do not use it for ordinary package usage.

Cross-cutting references

• references/troubleshooting.md: install, import, dependency marker, no-CLI, old API, and route-selection failures that cut across sub-skills.
• references/repo-provenance.md: source commit, package version, evidence paths, and refresh baseline for this skill.
• references/repo-routing-metadata.json: structured metadata consumed by DisCo's managed repo-skills router importer.

Quick decisions

• The package maximizes. If the real metric is a loss, return -loss.
• pbounds names must match objective and constraint keyword arguments.
• No GPU backend is required for selected package workflows; this is a CPU scientific Python package built on NumPy, SciPy, and scikit-learn.
• There is no public package CLI. Use Python APIs and bundled diagnostic scripts.
• Avoid old code that calls optimizer.suggest(UtilityFunction(...)); current v3.3.x optimizer-level suggest() takes no acquisition argument. Pass an acquisition instance into the optimizer constructor instead.
• Use dict parameters for clarity, especially with typed or categorical domains. Raw arrays follow pbounds insertion order and expanded internal dimensions.

Handoff checklist

Before answering a user or running a diagnostic, identify:

1. Is this package usage or source-checkout maintenance?
2. Is the objective unconstrained or constrained?
3. Are parameters ordinary floats, typed integers/categories, or custom domain objects?
4. Is acquisition selection part of the task, or can the optimizer default be used?
5. Does the requested check require only CPU runtime dependencies, or a broader development environment for notebooks/docs/lint?

Then load the smallest matching sub-skill and use its bundled references and scripts.