PhaseSweep

PhaseSweep runs hyperparameter sweeps in ordered phases: choose model depth, then tune learning rate with the winning depth fixed, then regularization. One YAML file holds your trainer configuration, objective, and search plan. Each trial receives a complete trainer input with inherited, fixed, and sampled values applied.

Requires Python 3.11+ and Linux or macOS. GPUs are optional; the starter uses a packaged toy trainer. The project is unstable, so review the launch contract before using your own trainer.

Install and try it

Install from PyPI:

pip install phasesweep
phasesweep --version

mkdir phasesweep-demo && cd phasesweep-demo
phasesweep init                     # writes starter.yaml without overwriting files
phasesweep validate starter.yaml    # checks the config without launching work
phasesweep run starter.yaml         # runs four toy-trainer trials
phasesweep show-winners starter.yaml
phasesweep status starter.yaml --trials

The starter compares two depths, then two learning rates. Its run.log includes these winner lines (abridged; trial numbers depend on grid order):

phase=depth WINNER trial=0 metric=0.3 params={'model.n_layers': 8}
phase=learning_rate WINNER trial=0 metric=0.3 params={'optimizer.lr': 0.0003}

The depth winner's model.n_layers: 8 becomes a fixed input to every learning-rate trial. Inheritance transfers parameter values; the trainer owns initialization and checkpoint loading. The complete starter YAML and phase composition guide explain the configuration and its tradeoffs.

Results live under runs/phasesweep_starter/ beside the config, including run.log. show-winners prints concise phase winners, the generation directory, and publication state; finished phases appear as unpublished while later phases run. status --trials inspects recorded attempts. See inspection commands for the output.

Use your own trainer

phasesweep init --list lists the templates. Replace the command, configuration keys, and objective extractor in the closest template:

Configure	Choices and details
Trainer input	Complete YAML, command-line flags, Hydra overrides, or nested JSON: input interfaces.
Objective	Python report_objective(...), the phasesweep report-objective command, JSON, logs, W&B, or MLflow: reporting and extractors.
Environment	execution.cwd, env, and execution.inherit_env: trainer contract.

Preview commands and the launch contract before training. Configuration errors name the relevant keys; explain gives their types, defaults, interactions, and warnings:

phasesweep run starter.yaml --dry-run
phasesweep explain
phasesweep explain 'phases[].sampler'

W&B and MLflow require their optional extras, phasesweep[wandb] and phasesweep[mlflow]; follow the W&B setup or MLflow guide. For noisy measurements, see small-budget advice and repeats.

Scope and continuation

PhaseSweep drives Optuna's grid, random, TPE, and CMA-ES samplers on one host, with an Optuna journal for persistent trials. GPU trials can run in parallel on that host; distributed sweeps and early pruning are outside its scope.

Apple silicon Macs discover one MPS device for same-host leasing, and the trainer selects its compute device. See GPU isolation.

With persistent storage, rerun the same config to resume interrupted work. Continuation and reruns covers aborted phases, trial budgets, and --from-phase NAME.

Connect an agent

The optional MCP server exposes experiments approved in an operator-owned catalog. Tool responses omit config and storage paths, trainer commands, environment values, and raw logs; sampled winner values follow visible_params. MCP setup covers installation, catalog permissions, client configuration, and verification. phasesweep mcp call invokes one tool from a shell without a client.

Reference

• Configuration guide and per-key reference.
• Minimal configuration: one toy-trainer attempt from the checkout root.
• Runtime: outputs, locks, leases, supervision, fingerprints, and resume.
• MCP operator reference: catalog fields, tools, authorization, run state, and recovery.
• Toy experiment and MCP catalog: checkout-local examples with MCP state and outputs under /tmp.
• Tiny Decoder Enwik8: real-trainer integration.
• Durability invariants: ledger, publication, and recovery rules, with their tests.
• Development: contributor setup, quality gates, and declined requests.

License

MIT. See LICENSE.