Metadata-Version: 2.4
Name: wlearn-bo
Version: 0.1.0
Summary: Bayesian optimization with Gaussian processes for hyperparameter tuning
Author: Anton Zemlyansky
License-Expression: Apache-2.0
Project-URL: Homepage, https://wlearn.org
Project-URL: Repository, https://github.com/wlearn-org/bo
Project-URL: Issues, https://github.com/wlearn-org/bo/issues
Keywords: bayesian-optimization,gaussian-process,hyperparameter-tuning,automl,wlearn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# wlearn-bo Python

Python wrapper for the wlearn C11 Bayesian optimization engine.

## Install

```bash
pip install wlearn-bo
```

## Example

```python
from wlearn_bo import BayesianOptimizer

space = {
    "lr": {"type": "log_uniform", "low": 1e-4, "high": 1.0},
    "depth": {"type": "int_uniform", "low": 2, "high": 12},
    "booster": {"type": "categorical", "values": ["gbtree", "dart"]},
    "dropout": {
        "type": "uniform",
        "low": 0.0,
        "high": 0.5,
        "condition": {"booster": "dart"},
    },
}

opt = BayesianOptimizer(space, seed=42)
for _ in range(30):
    params = opt.suggest()
    score = evaluate(params)
    opt.observe(params, score)

print(opt.best_score, opt.n_obs)
```

## API

- `BayesianOptimizer(search_space, **opts)` creates an optimizer.
- `suggest()` returns one parameter dict.
- `suggest_liar(score)` returns one suggestion using constant-liar batch BO.
- `suggest_batch(n)` returns `n` suggestions.
- `observe(params, score)` records a finite objective value; larger is better.
- `n_obs`, `best_score`, `n_contexts` expose optimizer state.
- `dispose()` releases native memory early in long-running optimization services.

Search parameter types: `uniform`, `log_uniform`, `int_uniform`,
`int_log_uniform`, `categorical`. Conditional parameters use
`condition: {parent: value}`.

Options: `kernel` (`matern52`, `matern32`, `se`), `acquisition_fn` (`ei`,
`ucb`, `pi`), `kappa`, `xi`, `n_restarts_hyper`, `n_restarts_acq`, `max_obs`,
`min_obs_for_gp`, `seed`.

BO state is intentionally ephemeral; warm-start by replaying `observe()` calls.

## Development

The canonical native source is repository root `src/`; `py/csrc/` is generated
for Python builds. Use `WLEARN_PYTHON=/path/to/python make test-py` from the
repository root to force a specific Python environment.

## Conditional parameters

Conditions may refer to parents declared later and may have multiple parents.
All parents must be active and match. Missing parents and cycles are rejected;
an empty condition is unconditional. Object values compare independently of key
order, while booleans remain distinct from numbers. Decoding evaluates dependencies
in order without changing the compiled coordinate order.
