metawalker 0.2.0__tar.gz

metawalker-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anik Ghosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metawalker-0.2.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: metawalker
+Version: 0.2.0
+Summary: Learned black-box optimizers (RL-controlled CMA-ES, learned walkers) as a drop-in for GridSearchCV
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: cma>=3.3
+Requires-Dist: scipy>=1.10
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.3; extra == "sklearn"
+Provides-Extra: optuna
+Requires-Dist: optuna>=3.0; extra == "optuna"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: scikit-learn>=1.3; extra == "test"
+Dynamic: license-file
+
+# metawalker
+
+Learned black-box optimizers for **big, complex search spaces**, packaged as a drop-in replacement for
+scikit-learn's `GridSearchCV` / `RandomizedSearchCV` and as a plain `minimize()` function.
+
+The optimizers were trained once, with evolution strategies, on cheap synthetic problems. After that they run
+on numpy alone, and each policy is a few KB.
+
+```bash
+pip install "metawalker[sklearn]"        # from the repo: pip install -e ".[sklearn]"
+```
+
+## Use it
+
+```python
+from metawalker import minimize, Float, Int, Categorical
+
+space = {"lr": Float(1e-5, 1e-1, log=True), "layers": Int(1, 8), "act": ["relu", "tanh"], "dropout": (0.0, 0.5)}
+result = minimize(train_and_score, space, budget=300, method="auto", maximize=True, recheck=3)
+result.best_params, result.best_value, result.recheck_values
+```
+
+As a scikit-learn search estimator (it uses the same internal hook as GridSearchCV, so `cv`, `scoring`,
+`refit`, `n_jobs`, `cv_results_`, `best_params_` and `best_estimator_` all behave the same):
+
+```python
+from metawalker.sklearn import MetaWalkerCV
+
+search = MetaWalkerCV(model, {"C": Float(1e-3, 1e3, log=True), "kernel": ["rbf", "linear"]},
+                     n_iter=100, method="rlcma", cv=5).fit(X, y)
+```
+
+A GridSearchCV `param_grid` (a dict of value lists) works unchanged as `param_space`.
+
+## Choose your own panel: test methods on your own losses
+
+You know your problem best, so the package helps you measure which method fits it. Give `compare()` your own
+loss functions, and optionally some simulated stand-ins shaped like your problem. It runs every method several
+times on each, with the same budget, and reports average rank, head-to-head win rates and time per run:
+
+```python
+from metawalker import compare, make_problem, minimize
+
+res = compare({"my_loss": (my_fn, my_space),
+               "stand-in": make_problem("plateau", n=80, noise=0.01)},  # sphere, ellipsoid, rastrigin,
+              methods=["rlcma", "walker_hp", "cmaes", "gp"],          # rosenbrock, ackley, levy, plateau
+              budget=200, seeds=5)
+print(res.summary())
+
+minimize(my_fn, my_space, budget=600, method=["rlcma", "gp"])   # then run the panel you picked
+```
+
+The simulated problems come from the same generator as our benchmark: rotated and shifted, with a known
+optimum, so `compare()` scores them by true regret rather than by lucky noisy readings.
+
+## What else it does for you
+
+```python
+import metawalker as mw
+
+# 1. don't know your landscape? probe it (~8% of the budget), then let it pick from the benchmark's rules
+res = mw.minimize_auto(my_fn, my_space, budget=500)
+print(res.recommendation.reasons)   # e.g. "92% of probes returned the same value: a plateau objective -> walker_hp"
+
+# 2. a best result you can trust: re-test the top candidates on fresh evaluations, pick by mean, report a CI
+cert = mw.certify(my_fn, res, top_k=5, repeats=5)
+print(cert.summary())               # cert.shrinkage = how much the raw best score was inflated by noise
+
+# 3. which parameters mattered, which direction helps, and the best range (free, from the search history)
+print(mw.importance(res).summary())
+
+# 4. train an optimizer specialized to YOUR kind of problem, on cheap simulated stand-ins
+policy = mw.train([lambda: my_simulator_factory()], init="walker_hp", generations=50, n_jobs=8)
+policy.save("my_optimizer.npz"); policy.minimize(my_fn, my_space, budget=300)
+
+# 5. evaluate on your own workers / cluster, or plug into an existing Optuna study
+with mw.AskTell(my_space, budget=200, method="rlcma") as at:
+    while not at.done:
+        tid, params = at.ask(); at.tell(tid, run_somewhere(params))
+from metawalker.asktell import MetaWalkerSampler   # optuna.create_study(sampler=MetaWalkerSampler(dists, budget=200))
+
+# 6. compare methods on your own losses, in parallel
+mw.compare({"mine": (my_fn, my_space)}, methods=["rlcma", "gp", "cmaes"], seeds=5, n_jobs=8)
+```
+
+Notes:
+- `compare(n_jobs>1)` and `train(n_jobs>1)` need picklable functions, plus an `if __name__ == "__main__":` guard on Windows.
+- `certify()` and `importance()` read the search direction from the Result.
+- Importance computed from an optimizer's history is biased toward the regions that optimizer sampled. Random-search histories give the cleanest estimate.
+
+## Which method
+
+| method | what it is | where it did best in our benchmark |
+|---|---|---|
+| `rlcma` | CMA-ES whose step size and restarts are set by a learned policy | 50–500 parameters: beat CMA-ES on 72–99% of test problems and TPE on 95%+ |
+| `walker` | a learned multi-start walker; one small network shared by every parameter, so it runs at any size | tied CMA-ES overall, won at 500 parameters; ~1 s of optimizer overhead |
+| `walker_hp` | the walker, also trained on plateau-shaped objectives | flat, mostly-zero objectives (e.g. searching for RL honeypots); fastest to a valid high-exploit level in a 169-parameter honeypot search |
+| `walker_hp_warm` | `walker_hp` after a Latin-hypercube warm-up of 20% of the budget (`warmup=0.2`) | **recommended for rare-signal objectives**, where only a tiny region scores at all: on a 0.5%-live plateau it found the region in 9/10 runs, against 1/10 (10 parameters) and 5/10 (50) for `walker_hp` |
+| `walker_rule` | hand-coded walker distilled from the learned one: move each coordinate with p = 0.6, pull 0.5 toward the best walker, step size `s *= exp(0.5 (success EMA - 0.35))` | as good as `walker`, with no network (mean rank 1.69 vs 1.83 over 12 problems) |
+| `cmaes` | CMA-ES with IPOP restarts (pycma) | small, noisy problems (under ~20 parameters) |
+| `cmaes_rule` | CMA-ES with the hand rule distilled from `rlcma`: sigma × 0.8 after a generation that did not improve, unless stalled 5+ generations or the population is flat | ties `rlcma` (wins 50%) and beats `cmaes` on 78% of runs; `rlcma` stays ahead on Levy/Rastrigin at 10 parameters |
+| `gp` | Optuna Gaussian-process Bayesian optimization (needs `metawalker[optuna]`) | **expensive** objectives up to ~200 parameters: tied with `rlcma` overall and better at 100–200 parameters, but it costs ~1 hour of its own compute per 1000-evaluation run, and that cost grows fast with evaluations and dimensions |
+| `tpe` | Optuna TPE (needs `metawalker[optuna]`) | baseline; `rlcma` beat it on 70–100% of problems |
+| `random` | random search | baseline |
+| `auto` | `cmaes` below 20 parameters, `rlcma` from 20 up; `gp` up to 200 parameters if you pass `expensive=True` | |
+| `[...]` | any list of methods = your own panel: the budget is split across them and the best is kept | |
+| `panel` | the default panel: `rlcma`, `walker_hp`, `cmaes` | when you don't know the landscape |
+
+Any method also takes `warmup=f`. It spends that fraction of the budget on Latin-hypercube points first, and
+those points count toward the budget and appear in the history. The walkers then start from the best 4 points
+and the CMA-based methods from the best one, while the other methods simply run on what is left. Use it when the
+signal is rare: without it the walkers shrink and restart instead of exploring, so plain random search finds a
+tiny live region more often than they do. The distilled rules come from the policy study (`results/analysis/policy_report.md`). The numbers
+above are medians over 3 seeds at budget 1000, from sphere, Rosenbrock, Rastrigin, Ackley, Levy and plateau at
+10 and 50 parameters. `compare()` accepts all of these methods.
+
+**Benchmark scope.** Rotated and shifted synthetic functions (sphere, ellipsoid, Rastrigin, Rosenbrock, plus
+held-out Ackley and Levy) with and without noise, a honeypot-like plateau family, and a real RL honeypot
+search. Budgets were 300–10,000 evaluations. Each learned method was trained 3 times from scratch, with
+results reported per training run. A comparison against Optuna GP, Optuna multivariate TPE, SMAC3 and
+Nevergrad NGOpt is in progress.
+
+## Behavior to know
+
+- **Invalid configurations:** if your function raises or returns nan/inf, that counts as a failed trial
+  (`result.n_failed`). The search keeps going.
+- **Noisy objectives:** the best observed value is biased upward (the winner's curse). Use `recheck=k` to
+  re-evaluate the winner k more times.
+- **Categorical parameters** are one coordinate split into equal bins. That's fine for a few choices, but
+  unordered categoricals with many choices are a known weak spot.
+- **1-parameter searches** with the CMA-based methods add an ignored dummy coordinate, because pycma needs 2+.
+- The `panel` budget is split equally, with no racing between methods.
+
+## Tests
+
+`pytest` from the repo root. `tests/test_regression.py` checks that every optimizer reproduces the
+pre-refactor benchmark code bit for bit (`tests/golden.json`).

metawalker-0.2.0/README.md

@@ -0,0 +1,103 @@
+# MetaWalker: learned search policies for honeypot and hyperparameter search
+
+The Python package is `metawalker` (`pip install -e .`, then `import metawalker`).
+
+RL-trained black-box optimizers for expensive, noisy, many-parameter searches. The motivating application is
+AI-safety "honeypot" search: find the gridworld level and PPO settings (169 parameters) under which a PPO agent
+takes a planted exploit instead of the honest task.
+
+## Proposal → code
+
+Each part of the proposal (`CS4180_project_proposal.md`) and where it lives. `src/metawalker/` is the library
+(`pip install -e .`); `experiments/` holds the scripts that produce every result in `results/`. "Written by" follows
+the proposal's LLM-assistance disclosure: Aniket wrote the base algorithms; the rest is supporting code (the
+experiment scripts and shell scripts).
+
+| Proposal | Code | Written by |
+|---|---|---|
+| The MDP: one search per episode, budget, noise, invalid points | `src/metawalker/problems.py` (`Problem`) | Aniket |
+| Sparse reward: −log10(final regret / random-point value) | `problems.py` (`Problem.score`) | Aniket |
+| Dense reward: log improvement per step | `src/metawalker/walker.py` (`navigate`, the `actor` branch) | Aniket |
+| Walker (Table 1) | `walker.py`; network layout, action sets, features in `src/metawalker/policy.py` | Aniket |
+| RL-controlled CMA-ES (Table 1) | `src/metawalker/cma.py` (`cmaes` with a policy) | Aniket |
+| rlbo (Table 1) | `src/metawalker/rlbo.py` | Aniket |
+| OpenAI-ES | update step: `src/metawalker/es.py`; training loops: `experiments/benchmark.py` (`train`), `experiments/rlbo_bench.py` | Aniket (update), supporting code (loops) |
+| PPO and branching double DQN | `experiments/rlalgos.py` | supporting code |
+| Baselines: CMA-ES, 1/5th-rule walkers | `cma.py` (`cmaes`), `walker.py` (`navigate` with no policy) | Aniket |
+| Baselines: Optuna GP / TPE, SMAC3, NGOpt, random search | `src/metawalker/baselines.py` | supporting code |
+| MetaWalker-Bench: test functions and the flat honeypot-like family | `problems.py`; suites and reports in `experiments/benchmark.py` | Aniket (functions), supporting code (suites) |
+| Real honeypot: JAX PPO gridworld, 169 genes, validity checks | `experiments/honeypot/env.py` | supporting code |
+| Comparison 1: same number of tries | `experiments/benchmark.py` (`test`, `hp` suites), `experiments/compare_hpo.py`, `experiments/rlbo_bench.py` | supporting code |
+| Comparison 2: same running time as GP | `experiments/timematched.py`, `experiments/rerun_gp.py` | supporting code |
+| Comparison 3: budgets 300–10,000 | `experiments/benchmark.py` (`budgets` suite) | supporting code |
+| Comparison 4: real honeypot, same PPO compute | `experiments/honeypot/search.py`, `results/honeypot/summarize.py` | supporting code |
+| Comparison 5: ablations, what the policies learned | ablation variants in `experiments/benchmark.py` (`hpx_norecheck`, `hpx_nojump`); `experiments/analysis/` | supporting code |
+| Risk: re-test the best on new seeds | `experiments/honeypot/search.py` (`remeasure`), `src/metawalker/certify.py` | supporting code |
+| Risk: Wilson confidence intervals | `experiments/benchmark.py` (`wilson`) | supporting code |
+| Risk: self-checks for bugs | `tests/` | supporting code |
+| Cluster runs (CPU-only Explorer) | `cluster/*.sbatch` | supporting code |
+
+**The rest** is not in the proposal. It is the package's user-facing API, all supporting code: `api.py`
+(`minimize`), `sklearn.py` (`MetaWalkerCV`), `asktell.py`, `space.py`, `compare.py`, `recommend.py`,
+`importance.py`, `train.py`, and `experiments/demo.py`.
+
+`tests/` checks the library and the experiments. `tests/test_regression.py` confirms that every optimizer
+reproduces the pre-refactor code bit for bit. `cluster/` holds the Slurm scripts.
+
+## Results
+
+### Benchmark functions (`results/reports/`)
+
+Rotated and shifted sphere, ellipsoid, rastrigin, rosenbrock, ackley and levy, plus a honeypot-like plateau
+family, at n = 5–500.
+
+| Comparison | Result |
+|---|---|
+| rlbo vs Optuna GP, equal evaluations (1,000) | rlbo better on 76–100% of instances at every n; 23 s vs 4,296 s per run |
+| rlbo vs CMA-ES, equal evaluations | rlbo better on 91–100% for n ≥ 20; tie at n = 5 |
+| RL-CMA vs GP, same wall-clock as GP | RL-CMA better on 90–100% of 4,620 runs at every n (plain CMA-ES too) |
+| Walkers on the plateau family | about −1.5 vs −0.6 to −0.9 for CMA-ES (log10 regret, lower is better) |
+
+### Real honeypot, 169 parameters (`results/honeypot/`; `python results/honeypot/summarize.py`)
+
+Equal PPO compute: 200 PPO-costing evaluations per search, structurally invalid levels free. The score is the
+certified exploit rate: the best of the top candidates, re-measured on fresh PPO seeds. 5 search seeds per method.
+
+| Method | Score |
+|---|---|
+| **rlbo** (3 policies, 15 searches) | **0.88** |
+| CMA-ES | 0.75–0.77 |
+| walker with jump / re-check + level cache | 0.69 |
+| Optuna GP | 0.55 |
+
+### What the policies learned (`results/analysis/policy_report.md`)
+
+- The walker jumps on 70% of its steps until it finds signal, then searches locally and re-checks its best
+  point. On the real honeypot, removing re-check drops it from 0.81 to 0.48, and removing jump to 0.59.
+- The budget-aware walkers front-load their gains. That wins small budgets and loses to CMA-ES at 10,000
+  evaluations.
+- Three silent training bugs are documented in the reports:
+  - a seed leak that started walkers next to the optimum;
+  - ES rank ties turning into random steps;
+  - a BLAS thread pile-up that slowed training about 300×.
+
+## Quick start
+
+```bash
+pip install -e ".[sklearn,optuna,test]"          # the library (+ torch for Optuna's GP, jax/flax/optax for the honeypot)
+pytest                                            # library, regression and experiment tests
+python -m experiments.benchmark smoke_hpx         # quick self-check of the walker and its new actions
+```
+
+```python
+from metawalker import minimize, Float, Int
+result = minimize(train_and_score, {"lr": Float(1e-5, 1e-1, log=True), "layers": Int(1, 8)}, budget=300,
+                  maximize=True, recheck=3)
+```
+
+See `docs/package.md` for the library API, `proposal_notes.md` for the project proposal and `docs/plan.md` for
+the project plan. The cluster runs
+used Northeastern's Explorer: run `sbatch cluster/setup.sbatch` once, then use the generic `cluster/run.sbatch`
+and `cluster/honeypot.sbatch`. Usage examples are in their headers.
+
+MIT licensed.

metawalker-0.2.0/docs/package.md

@@ -0,0 +1,137 @@
+# metawalker
+
+Learned black-box optimizers for **big, complex search spaces**, packaged as a drop-in replacement for
+scikit-learn's `GridSearchCV` / `RandomizedSearchCV` and as a plain `minimize()` function.
+
+The optimizers were trained once, with evolution strategies, on cheap synthetic problems. After that they run
+on numpy alone, and each policy is a few KB.
+
+```bash
+pip install "metawalker[sklearn]"        # from the repo: pip install -e ".[sklearn]"
+```
+
+## Use it
+
+```python
+from metawalker import minimize, Float, Int, Categorical
+
+space = {"lr": Float(1e-5, 1e-1, log=True), "layers": Int(1, 8), "act": ["relu", "tanh"], "dropout": (0.0, 0.5)}
+result = minimize(train_and_score, space, budget=300, method="auto", maximize=True, recheck=3)
+result.best_params, result.best_value, result.recheck_values
+```
+
+As a scikit-learn search estimator (it uses the same internal hook as GridSearchCV, so `cv`, `scoring`,
+`refit`, `n_jobs`, `cv_results_`, `best_params_` and `best_estimator_` all behave the same):
+
+```python
+from metawalker.sklearn import MetaWalkerCV
+
+search = MetaWalkerCV(model, {"C": Float(1e-3, 1e3, log=True), "kernel": ["rbf", "linear"]},
+                     n_iter=100, method="rlcma", cv=5).fit(X, y)
+```
+
+A GridSearchCV `param_grid` (a dict of value lists) works unchanged as `param_space`.
+
+## Choose your own panel: test methods on your own losses
+
+You know your problem best, so the package helps you measure which method fits it. Give `compare()` your own
+loss functions, and optionally some simulated stand-ins shaped like your problem. It runs every method several
+times on each, with the same budget, and reports average rank, head-to-head win rates and time per run:
+
+```python
+from metawalker import compare, make_problem, minimize
+
+res = compare({"my_loss": (my_fn, my_space),
+               "stand-in": make_problem("plateau", n=80, noise=0.01)},  # sphere, ellipsoid, rastrigin,
+              methods=["rlcma", "walker_hp", "cmaes", "gp"],          # rosenbrock, ackley, levy, plateau
+              budget=200, seeds=5)
+print(res.summary())
+
+minimize(my_fn, my_space, budget=600, method=["rlcma", "gp"])   # then run the panel you picked
+```
+
+The simulated problems come from the same generator as our benchmark: rotated and shifted, with a known
+optimum, so `compare()` scores them by true regret rather than by lucky noisy readings.
+
+## What else it does for you
+
+```python
+import metawalker as mw
+
+# 1. don't know your landscape? probe it (~8% of the budget), then let it pick from the benchmark's rules
+res = mw.minimize_auto(my_fn, my_space, budget=500)
+print(res.recommendation.reasons)   # e.g. "92% of probes returned the same value: a plateau objective -> walker_hp"
+
+# 2. a best result you can trust: re-test the top candidates on fresh evaluations, pick by mean, report a CI
+cert = mw.certify(my_fn, res, top_k=5, repeats=5)
+print(cert.summary())               # cert.shrinkage = how much the raw best score was inflated by noise
+
+# 3. which parameters mattered, which direction helps, and the best range (free, from the search history)
+print(mw.importance(res).summary())
+
+# 4. train an optimizer specialized to YOUR kind of problem, on cheap simulated stand-ins
+policy = mw.train([lambda: my_simulator_factory()], init="walker_hp", generations=50, n_jobs=8)
+policy.save("my_optimizer.npz"); policy.minimize(my_fn, my_space, budget=300)
+
+# 5. evaluate on your own workers / cluster, or plug into an existing Optuna study
+with mw.AskTell(my_space, budget=200, method="rlcma") as at:
+    while not at.done:
+        tid, params = at.ask(); at.tell(tid, run_somewhere(params))
+from metawalker.asktell import MetaWalkerSampler   # optuna.create_study(sampler=MetaWalkerSampler(dists, budget=200))
+
+# 6. compare methods on your own losses, in parallel
+mw.compare({"mine": (my_fn, my_space)}, methods=["rlcma", "gp", "cmaes"], seeds=5, n_jobs=8)
+```
+
+Notes:
+- `compare(n_jobs>1)` and `train(n_jobs>1)` need picklable functions, plus an `if __name__ == "__main__":` guard on Windows.
+- `certify()` and `importance()` read the search direction from the Result.
+- Importance computed from an optimizer's history is biased toward the regions that optimizer sampled. Random-search histories give the cleanest estimate.
+
+## Which method
+
+| method | what it is | where it did best in our benchmark |
+|---|---|---|
+| `rlcma` | CMA-ES whose step size and restarts are set by a learned policy | 50–500 parameters: beat CMA-ES on 72–99% of test problems and TPE on 95%+ |
+| `walker` | a learned multi-start walker; one small network shared by every parameter, so it runs at any size | tied CMA-ES overall, won at 500 parameters; ~1 s of optimizer overhead |
+| `walker_hp` | the walker, also trained on plateau-shaped objectives | flat, mostly-zero objectives (e.g. searching for RL honeypots); fastest to a valid high-exploit level in a 169-parameter honeypot search |
+| `walker_hp_warm` | `walker_hp` after a Latin-hypercube warm-up of 20% of the budget (`warmup=0.2`) | **recommended for rare-signal objectives**, where only a tiny region scores at all: on a 0.5%-live plateau it found the region in 9/10 runs, against 1/10 (10 parameters) and 5/10 (50) for `walker_hp` |
+| `walker_rule` | hand-coded walker distilled from the learned one: move each coordinate with p = 0.6, pull 0.5 toward the best walker, step size `s *= exp(0.5 (success EMA - 0.35))` | as good as `walker`, with no network (mean rank 1.69 vs 1.83 over 12 problems) |
+| `cmaes` | CMA-ES with IPOP restarts (pycma) | small, noisy problems (under ~20 parameters) |
+| `cmaes_rule` | CMA-ES with the hand rule distilled from `rlcma`: sigma × 0.8 after a generation that did not improve, unless stalled 5+ generations or the population is flat | ties `rlcma` (wins 50%) and beats `cmaes` on 78% of runs; `rlcma` stays ahead on Levy/Rastrigin at 10 parameters |
+| `gp` | Optuna Gaussian-process Bayesian optimization (needs `metawalker[optuna]`) | **expensive** objectives up to ~200 parameters: tied with `rlcma` overall and better at 100–200 parameters, but it costs ~1 hour of its own compute per 1000-evaluation run, and that cost grows fast with evaluations and dimensions |
+| `tpe` | Optuna TPE (needs `metawalker[optuna]`) | baseline; `rlcma` beat it on 70–100% of problems |
+| `random` | random search | baseline |
+| `auto` | `cmaes` below 20 parameters, `rlcma` from 20 up; `gp` up to 200 parameters if you pass `expensive=True` | |
+| `[...]` | any list of methods = your own panel: the budget is split across them and the best is kept | |
+| `panel` | the default panel: `rlcma`, `walker_hp`, `cmaes` | when you don't know the landscape |
+
+Any method also takes `warmup=f`. It spends that fraction of the budget on Latin-hypercube points first, and
+those points count toward the budget and appear in the history. The walkers then start from the best 4 points
+and the CMA-based methods from the best one, while the other methods simply run on what is left. Use it when the
+signal is rare: without it the walkers shrink and restart instead of exploring, so plain random search finds a
+tiny live region more often than they do. The distilled rules come from the policy study (`results/analysis/policy_report.md`). The numbers
+above are medians over 3 seeds at budget 1000, from sphere, Rosenbrock, Rastrigin, Ackley, Levy and plateau at
+10 and 50 parameters. `compare()` accepts all of these methods.
+
+**Benchmark scope.** Rotated and shifted synthetic functions (sphere, ellipsoid, Rastrigin, Rosenbrock, plus
+held-out Ackley and Levy) with and without noise, a honeypot-like plateau family, and a real RL honeypot
+search. Budgets were 300–10,000 evaluations. Each learned method was trained 3 times from scratch, with
+results reported per training run. A comparison against Optuna GP, Optuna multivariate TPE, SMAC3 and
+Nevergrad NGOpt is in progress.
+
+## Behavior to know
+
+- **Invalid configurations:** if your function raises or returns nan/inf, that counts as a failed trial
+  (`result.n_failed`). The search keeps going.
+- **Noisy objectives:** the best observed value is biased upward (the winner's curse). Use `recheck=k` to
+  re-evaluate the winner k more times.
+- **Categorical parameters** are one coordinate split into equal bins. That's fine for a few choices, but
+  unordered categoricals with many choices are a known weak spot.
+- **1-parameter searches** with the CMA-based methods add an ignored dummy coordinate, because pycma needs 2+.
+- The `panel` budget is split equally, with no racing between methods.
+
+## Tests
+
+`pytest` from the repo root. `tests/test_regression.py` checks that every optimizer reproduces the
+pre-refactor benchmark code bit for bit (`tests/golden.json`).

metawalker-0.2.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "metawalker"
+version = "0.2.0"
+description = "Learned black-box optimizers (RL-controlled CMA-ES, learned walkers) as a drop-in for GridSearchCV"
+readme = "docs/package.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.24", "cma>=3.3", "scipy>=1.10"]
+
+[project.optional-dependencies]
+sklearn = ["scikit-learn>=1.3"]
+optuna = ["optuna>=3.0"]
+test = ["pytest", "scikit-learn>=1.3"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+metawalker = ["policies/*.npy"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]
+testpaths = ["tests"]

metawalker-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

metawalker-0.2.0/src/metawalker/__init__.py

@@ -0,0 +1,19 @@
+"""metawalker: learned black-box optimizers for big, complex search spaces.
+
+    from metawalker import minimize, minimize_auto, recommend, certify, importance, compare, train
+    from metawalker.sklearn import MetaWalkerCV   # needs scikit-learn
+"""
+from .api import METHODS, Result, minimize
+from .asktell import AskTell
+from .certify import Certified, certify
+from .compare import Comparison, compare
+from .importance import Importance, importance
+from .problems import FAMILIES, TestProblem, make_problem
+from .recommend import Recommendation, minimize_auto, recommend
+from .space import Categorical, Float, Int, Space
+from .train import TrainedPolicy, train
+
+__all__ = ['minimize', 'minimize_auto', 'recommend', 'Recommendation', 'certify', 'Certified', 'importance',
+           'Importance', 'compare', 'Comparison', 'train', 'TrainedPolicy', 'AskTell', 'Result', 'METHODS',
+           'make_problem', 'TestProblem', 'FAMILIES', 'Space', 'Float', 'Int', 'Categorical']
+__version__ = '0.2.0'