{"id":51019784,"url":"https://github.com/pszemraj/phasesweep","last_synced_at":"2026-06-21T15:30:52.405Z","repository":{"id":365520606,"uuid":"1239235660","full_name":"pszemraj/phasesweep","owner":"pszemraj","description":"YAML-driven phase-chained hyperparameter sweeps with Optuna: each phase's winner is set for all following sweeps [of other params]","archived":false,"fork":false,"pushed_at":"2026-06-17T16:58:35.000Z","size":2248,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T18:26:31.835Z","etag":null,"topics":["hyperparameter-optimization","hyperparameter-search","ml-experimentation","ml-experiments","optuna","orchestration","yaml-configuration"],"latest_commit_sha":null,"homepage":"https://deepwiki.com/pszemraj/phasesweep","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pszemraj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T22:34:26.000Z","updated_at":"2026-05-18T02:52:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pszemraj/phasesweep","commit_stats":null,"previous_names":["pszemraj/phasesweep"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/pszemraj/phasesweep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pszemraj%2Fphasesweep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pszemraj%2Fphasesweep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pszemraj%2Fphasesweep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pszemraj%2Fphasesweep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pszemraj","download_url":"https://codeload.github.com/pszemraj/phasesweep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pszemraj%2Fphasesweep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34616509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hyperparameter-optimization","hyperparameter-search","ml-experimentation","ml-experiments","optuna","orchestration","yaml-configuration"],"created_at":"2026-06-21T15:30:48.202Z","updated_at":"2026-06-21T15:30:52.396Z","avatar_url":"https://github.com/pszemraj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# phasesweep\n\n\u003e Orchestration layer for YAML-driven, phase-chained hyperparameter sweeps over your own training scripts\n\nYour trainer runs the experiments. `phasesweep` decides what to try next. Define phased Optuna sweeps in YAML; each phase's winner locks in as a fixed override for every phase downstream.\n\nUse `phasesweep` when a full joint sweep is too expensive and the search can be broken into inspectable stages, such as architecture depth, then learning rate, then regularization. Use one phase with the full search space when dimensions strongly interact.\n\n![dag diagram](docs/images/diagramA_dag.png)\n\n## Requirements\n\n- Python 3.10+, OS: Linux or macOS[^1]\n- A trainer command that **writes a metric artifact** and **accepts at least one [supported override format](docs/config.md#override-formats)**[^2]\n- GPU optional: CUDA devices are auto-detected for same-host lease management\n\n[^1]: Windows is unsupported; process cleanup and host locks rely on POSIX process groups and `flock`. If you're mad about this, you should be using [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) anyway\n[^2]: phasesweep orchestrates sweeps but never trains anything itself; your trainer must handle both of these.\n\n## Install\n\nphasesweep is currently installed from Git:\n\n```bash\npip install \"phasesweep @ git+https://github.com/pszemraj/phasesweep.git\"\n# weights-and-biases integration is optional:\npip install \"phasesweep[wandb] @ git+https://github.com/pszemraj/phasesweep.git\"\n# all dev dependencies:\npip install \"phasesweep[dev,wandb] @ git+https://github.com/pszemraj/phasesweep.git\"\n```\n\nFor local development from a checkout:\n\n```bash\ngit clone https://github.com/pszemraj/phasesweep.git\ncd phasesweep\n# activate venv of your choice, then:\npip install -e \".[dev,wandb]\"\n```\n\n## Quickstart\n\nTo run the bundled toy example from a checkout:\n\n```bash\nphasesweep validate examples/experiment.yaml\nphasesweep run examples/experiment.yaml --dry-run\nphasesweep run examples/experiment.yaml\nphasesweep show-winners examples/experiment.yaml\nphasesweep status examples/experiment.yaml\n```\n\nThe example launches a deterministic fake trainer, runs 32 short trials, and writes outputs under `runs/`.\n\n## Config Sketch\n\nAdapt this shape to your own trainer.\n\n\u003e [!IMPORTANT]\n\u003e The script in `trial_command` must parse the override format you choose. The default is `argparse`, where `{overrides}` renders flags such as `--n_layers 8 --lr 0.0003`; see [supported override formats](docs/config.md#override-formats).\n\n```yaml\nexperiment: tiny_lm_16mb\nstorage: sqlite:///./runs/phases.db\nworkdir: ./runs\ntrial_command: \"python train.py --out {trial_dir}/result.json {overrides}\"\n\nmetric:\n  name: eval_loss\n  goal: minimize\n  extractor: { type: json, path: result.json, key: eval_loss }\n\nphases:\n  - name: depth\n    n_trials: 4\n    sampler: { type: grid }\n    search_space:\n      n_layers: { type: categorical, choices: [4, 8, 12, 16] }\n\n  - name: lr\n    inherits: [depth]\n    n_trials: 12\n    search_space:\n      lr: { type: float, low: 1.0e-5, high: 1.0e-2, log: true }\n```\n\n## Runtime Boundaries\n\n- Bring your own trainer; see the [trainer contract](docs/config.md#trainer-contract).\n- Sequential phases are greedy. They do not replace joint optimization when parameters interact strongly.\n- Use one orchestrator per experiment on one host. Same-host conflicts are rejected with advisory locks.\n- SQLite is for sequential `n_jobs == 1` studies. See [runtime behavior](docs/runtime.md#concurrency-model) for parallel storage and locking details.\n\n## Docs\n\n- [Config guide](docs/config.md): trainer contract, override formats, experiment YAML, suites, search spaces, gates, promotion, extractors.\n- [Typed config reference](docs/config_reference.yaml): schema-complete YAML reference with every field, type, default, enum, and major validation constraint.\n- [Runtime behavior](docs/runtime.md): filesystem layout, locks, GPU leases, process cleanup, fingerprints, resume.\n- [Development](docs/development.md): test commands and test-suite map.\n- [Roadmap](docs/roadmap.md): future work outside the current single-host design.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpszemraj%2Fphasesweep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpszemraj%2Fphasesweep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpszemraj%2Fphasesweep/lists"}