phasesweep 0.3.6__tar.gz

phasesweep-0.3.6/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: Checks
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install static-check dependencies
+        run: >-
+          python -m pip install
+          'ruff>=0.5' 'mypy>=1.10' 'types-PyYAML>=6.0'
+          'optuna==4.9.0' 'cmaes>=0.10'
+          'pydantic>=2.0' 'pyyaml>=6.0' 'click>=8.1' 'mcp>=1.27,<1.28'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy src
+      # Fast in-process contracts, run from src/ without building the package.
+      # The maintainer approved this step for one Python version within about
+      # 20 seconds of CI time; anything slower stays local with the full suite.
+      # Collecting the whole suite runs the integration-tier guard over every
+      # test module without executing one; it imports each module, so a test
+      # that needs Hydra or W&B must import it inside the test. The size check
+      # covers every tracked src and test module, not only the ones a commit
+      # touched.
+      - name: Contract tests
+        run: |
+          bash scripts/check_module_size.sh
+          python -m pip install 'pytest>=7'
+          PYTHONPATH=src python -m pytest --collect-only -q -p no:cacheprovider
+          PYTHONPATH=src python -m pytest -p no:cacheprovider \
+            tests/test_ledger_contract.py tests/test_error_routing.py \
+            tests/test_tier_guard.py tests/test_ledger_read_paths.py

phasesweep-0.3.6/.github/workflows/publish.yml

@@ -0,0 +1,155 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+# Scope concurrency by release tag so distinct releases cannot replace an older pending run.
+concurrency:
+  group: pypi-publish-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build-distributions:
+    if: github.event.release.prerelease == false
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out the release commit
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.13"
+      - name: Install packaging tools
+        run: python -m pip install build packaging twine
+      - name: Validate the release tag and commit
+        id: release
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          if ! git merge-base --is-ancestor HEAD origin/main; then
+            echo "Release tag ${RELEASE_TAG} is not contained in main." >&2
+            exit 1
+          fi
+          python - <<'PY'
+          import os
+          from pathlib import Path
+
+          from packaging.version import InvalidVersion, Version
+
+          tag = os.environ["RELEASE_TAG"]
+          if not tag.startswith("v"):
+              raise SystemExit(f"release tag must start with 'v': {tag!r}")
+          try:
+              version = Version(tag[1:])
+          except InvalidVersion as error:
+              raise SystemExit(f"release tag is not a PEP 440 version: {tag!r}") from error
+          # Post releases and epochs remain valid stable public PEP 440 versions.
+          if version.is_prerelease or version.is_devrelease or version.local is not None:
+              raise SystemExit(f"release tag must be a stable public version: {tag!r}")
+          with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output:
+              print(f"version={version}", file=output)
+          PY
+      - name: Build distributions
+        env:
+          # An annotated RC tag on the same commit must not override the release tag.
+          SETUPTOOLS_SCM_OVERRIDES_FOR_PHASESWEEP: >-
+            {scm.git.describe_command = ["git", "describe", "--dirty", "--tags",
+            "--long", "--abbrev=40", "--exact-match", "--match",
+            "${{ github.event.release.tag_name }}"]}
+        run: python -m build
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+      - name: Verify distribution versions
+        env:
+          EXPECTED_VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          python - <<'PY'
+          import os
+          import tarfile
+          from email.parser import BytesParser
+          from pathlib import Path
+          from zipfile import ZipFile
+
+          from packaging.utils import canonicalize_name
+          from packaging.version import Version
+
+          expected_version = Version(os.environ["EXPECTED_VERSION"])
+          wheels = list(Path("dist").glob("*.whl"))
+          sdists = list(Path("dist").glob("*.tar.gz"))
+          if len(wheels) != 1 or len(sdists) != 1:
+              raise SystemExit(f"expected one wheel and one sdist, found {wheels!r} and {sdists!r}")
+          with ZipFile(wheels[0]) as archive:
+              metadata_paths = [
+                  name for name in archive.namelist() if name.endswith(".dist-info/METADATA")
+              ]
+              if len(metadata_paths) != 1:
+                  raise SystemExit(
+                      f"expected one .dist-info/METADATA in {wheels[0]}, found {metadata_paths!r}"
+                  )
+              metadata_path = metadata_paths[0]
+              wheel_metadata = BytesParser().parsebytes(archive.read(metadata_path))
+          with tarfile.open(sdists[0]) as archive:
+              metadata_members = [
+                  member
+                  for member in archive.getmembers()
+                  if member.name.endswith("/PKG-INFO") and len(Path(member.name).parts) == 2
+              ]
+              if len(metadata_members) != 1:
+                  names = [member.name for member in metadata_members]
+                  raise SystemExit(
+                      f"expected one top-level PKG-INFO in {sdists[0]}, found {names!r}"
+                  )
+              metadata_member = metadata_members[0]
+              metadata_file = archive.extractfile(metadata_member)
+              if metadata_file is None:
+                  raise SystemExit(f"could not read {metadata_member.name} from {sdists[0]}")
+              sdist_metadata = BytesParser().parse(metadata_file)
+          for artifact, metadata in (
+              (wheels[0], wheel_metadata),
+              (sdists[0], sdist_metadata),
+          ):
+              if canonicalize_name(metadata["Name"]) != "phasesweep":
+                  raise SystemExit(f"unexpected project name in {artifact}: {metadata['Name']!r}")
+              actual_version = Version(metadata["Version"])
+              if actual_version != expected_version:
+                  raise SystemExit(
+                      f"release tag expects {expected_version}, but {artifact} contains {actual_version}"
+                  )
+          PY
+      - name: Store distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-to-pypi:
+    if: github.event.release.prerelease == false
+    needs: build-distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/phasesweep
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-distributions
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          attestations: true

phasesweep-0.3.6/.gitignore

@@ -0,0 +1,180 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_version.py
+
+# phasesweep local outputs
+runs/
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Golden ledger fixtures are committed on purpose: real PhaseSweep output whose
+# trial logs (*.log) and artifact trees would otherwise be ignored above.
+# See tests/fixtures/ledgers/README.md.
+!tests/fixtures/ledgers/**

phasesweep-0.3.6/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "examples/tiny_decoder_enwik8/upstream"]
+	path = examples/tiny_decoder_enwik8/upstream
+	url = https://github.com/pszemraj/decoder-pytorch-template.git

phasesweep-0.3.6/.pre-commit-config.yaml

@@ -0,0 +1,67 @@
+# Every hook is `repo: local` with `language: system`: it runs the tool already
+# installed in the active development environment (`pip install -e ".[dev]"`),
+# so pre-commit builds no per-hook environments, needs no network, and uses the
+# same tool versions as manual runs. Activate that environment before
+# committing or pushing.
+minimum_pre_commit_version: "3.2.0"
+default_install_hook_types: [pre-commit, pre-push]
+default_stages: [pre-commit]
+
+repos:
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff check
+        entry: ruff check --force-exclude --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-format
+        name: ruff format
+        entry: ruff format --force-exclude
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: pathlint
+        name: pathlint
+        entry: pathlint
+        language: system
+        files: ^(src|tests)/.*\.py$
+      # doc_check.py is a maintainer script outside the repository; without it
+      # the hook reports the skip and passes. Its report prints only on failure.
+      - id: doc-check
+        name: doc-check (strict)
+        entry: >-
+          bash -c 'script="$HOME/scripts/py/doc_check.py";
+          [ -f "$script" ] || { echo "doc_check.py not found; skipped"; exit 0; };
+          out=$(python "$script" --strict "$@") || { printf "%s\n" "$out"; exit 1; }' --
+        language: system
+        files: ^src/.*\.py$
+        verbose: true
+      - id: module-size
+        name: module size
+        entry: bash scripts/check_module_size.sh
+        language: system
+        files: ^(src|tests)/.*\.py$
+      # Runs on every commit: the contracts span all of src/ and the pytest
+      # configuration.
+      - id: contract-tests
+        name: contract tests
+        entry: pytest tests/test_ledger_contract.py tests/test_error_routing.py tests/test_tier_guard.py -q -p no:cacheprovider
+        language: system
+        pass_filenames: false
+        always_run: true
+      # Collecting the whole suite runs the integration-tier guard over every
+      # test module without executing any test.
+      - id: tier-guard
+        name: tier guard (whole-suite collection)
+        entry: pytest --collect-only -q -p no:cacheprovider
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: mypy
+        name: mypy
+        entry: mypy src
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

phasesweep-0.3.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Szemraj
+
+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.

phasesweep-0.3.6/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: phasesweep
+Version: 0.3.6
+Summary: YAML-driven phase-chained hyperparameter sweeps with Optuna: each phase's winner is set for all following sweeps.
+Author: Peter Szemraj
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pszemraj/phasesweep
+Project-URL: Documentation, https://github.com/pszemraj/phasesweep/tree/main/docs
+Project-URL: Repository, https://github.com/pszemraj/phasesweep.git
+Project-URL: Issues, https://github.com/pszemraj/phasesweep/issues
+Keywords: experiments,hyperparameter-optimization,machine-learning,optuna,sweeps
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: optuna<4.10,>=4.0
+Requires-Dist: cmaes>=0.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.1
+Provides-Extra: wandb
+Requires-Dist: wandb<0.29,>=0.28; extra == "wandb"
+Provides-Extra: mcp
+Requires-Dist: mcp<1.28,>=1.27; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: hydra-core<1.4,>=1.3; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: setuptools-scm[simple]>=9.2; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: mcp<1.28,>=1.27; extra == "dev"
+Requires-Dist: pre-commit>=3.2; extra == "dev"
+Requires-Dist: pathlint>=0.2; extra == "dev"
+Dynamic: license-file
+
+# PhaseSweep
+
+PhaseSweep runs phase-chained hyperparameter sweeps from one ordinary YAML file. That file contains your trainer configuration, the metric, and the search plan. PhaseSweep materializes the configured trainer input for every trial, decides what to try next, persists each phase winner, and carries selected values forward as fixed inputs to later phases.
+
+This is useful when a full joint sweep is too expensive or hard to interpret. For example, choose architecture depth, then tune learning rate, then regularization. The [configuration guide](https://github.com/pszemraj/phasesweep/blob/main/docs/config.md#phase-composition) explains the inheritance model and its tradeoffs.
+
+![PhaseSweep phase DAG](https://raw.githubusercontent.com/pszemraj/phasesweep/main/docs/images/diagramA_dag.png)
+
+## How it works
+
+The starter generated by `phasesweep init` searches depth before learning rate (abridged; the full file also sets storage, the working directory, and the metric extractor):
+
+```yaml
+experiment: phasesweep_starter
+
+# The trainer receives one complete generated YAML per trial.
+trial_command: "python -m phasesweep.examples.fake_train --config {config_path}"
+
+trainer_config:
+  model:
+    n_layers: 8
+    dropout: 0.1
+  optimizer:
+    lr: 0.0003
+    weight_decay: 0.05
+
+metric:
+  name: eval_loss
+  goal: minimize
+
+phases:
+  - name: depth
+    n_trials: 2
+    sampler: { type: grid }
+    search_space:
+      model.n_layers: { type: categorical, choices: [6, 8] }
+
+  - name: learning_rate
+    inherits: [depth] # the winning model.n_layers is fixed here
+    n_trials: 2
+    sampler: { type: grid }
+    search_space:
+      optimizer.lr: { type: categorical, choices: [0.0001, 0.0003] }
+```
+
+The packaged fake trainer uses the optional `report_objective(...)` envelope
+helper. Your own trainer can report through W&B, ordinary JSON, or logs without
+importing PhaseSweep.
+
+## Install and try it
+
+Requirements: Python 3.11+ and a POSIX host for real runs. GPUs are optional.
+
+```bash
+python -m pip install phasesweep
+phasesweep --version
+
+mkdir phasesweep-demo && cd phasesweep-demo
+phasesweep init                       # writes the starter experiment.yaml
+phasesweep validate experiment.yaml   # checks it without launching anything
+phasesweep run experiment.yaml        # four tiny trials, a few seconds
+```
+
+`phasesweep init` never overwrites an existing file; use `-o PATH` for another
+destination.
+
+The run log shows the phase chaining directly (abridged):
+
+```text
+[depth/trial_0] python -m phasesweep.examples.fake_train --config .../trainer_config.yaml
+[depth/trial_1] python -m phasesweep.examples.fake_train --config .../trainer_config.yaml
+phase=depth WINNER trial=0 metric=0.3 params={'model.n_layers': 8}
+[learning_rate/trial_0] python -m phasesweep.examples.fake_train --config .../trainer_config.yaml
+[learning_rate/trial_1] python -m phasesweep.examples.fake_train --config .../trainer_config.yaml
+phase=learning_rate WINNER trial=0 metric=0.3 params={'optimizer.lr': 0.0003}
+```
+
+The `depth` winner's `model.n_layers: 8` is injected into every `learning_rate` trial's complete YAML. Winners persist in the working directory, so you can inspect them any time (abridged):
+
+```bash
+phasesweep show-winners experiment.yaml
+```
+
+```yaml
+phase: learning_rate
+metric:
+  eval_loss: 0.3
+  goal: minimize
+trial_number: 0
+params:
+  optimizer.lr: 0.0003
+effective_overrides:
+  model.n_layers: 8
+  optimizer.lr: 0.0003
+# ... completion state, fingerprints, objective provenance, and confound
+# verdicts on the ranked population follow
+```
+
+The starter uses `storage: auto`, so its ledger and outputs live together under
+`<workdir>/<experiment>/`. The ledger is an Optuna journal: `phasesweep status`
+prints its path, and Optuna's own CLI and dashboard can
+[read it](https://github.com/pszemraj/phasesweep/blob/main/docs/runtime.md#inspect-the-ledger-with-optuna). See
+[runtime behavior](https://github.com/pszemraj/phasesweep/blob/main/docs/runtime.md) for state layout, current-format
+requirements, locks, cleanup, GPU isolation, and resume.
+
+## Use your own trainer
+
+Choose the input interface your trainer already accepts:
+
+| Input | Command placeholder |
+| --- | --- |
+| Complete base-plus-overrides YAML (`yaml_file`, default) | `--config {config_path}` |
+| Command-line flags (`argparse`) | `{overrides}` produces `--key=value` |
+| Native Hydra overrides (`hydra`) | `{overrides}` produces `key=value` |
+| Nested overrides-only JSON (`json_file`) | `--overrides {overrides_path}` |
+
+> [!TIP]
+> `phasesweep run experiment.yaml --dry-run` prints one rendered command per
+> phase without launching work. Use it to check that your placeholders render
+> what the trainer expects.
+
+For ordinary JSON output, pass an output path under `{trial_dir}` to your
+trainer and select it with `extractor: {type: json, path: result.json, key: eval.loss}`.
+For W&B, use `extractor: {type: wandb, entity: YOUR_ENTITY, project: YOUR_PROJECT, metric_key: eval/loss}`,
+have the trainer honor the supplied W&B identity, and install the extra:
+
+```bash
+python -m pip install "phasesweep[wandb]"
+```
+
+`metric.goal` ranks each trial's selected scalar. Log matching selects the
+last observation by default; W&B selects an exact finished-summary key.
+The trainer owns evaluation, early stopping, checkpoint selection, and
+aggregation. Inheritance transfers parameters, not model weights.
+
+See the [configuration guide](https://github.com/pszemraj/phasesweep/blob/main/docs/config.md) for input types, reporting,
+credentials, and selection details. The [Tiny Decoder Enwik8
+example](https://github.com/pszemraj/phasesweep/blob/main/examples/tiny_decoder_enwik8/README.md) is a complete real-trainer
+integration.
+
+## Connect an agent
+
+The optional MCP server connects an AI agent to experiments you have approved without exposing config or storage paths, trainer commands, environment values, or raw logs. Sampled winner values follow the catalog's `visible_params` policy. Follow the [MCP setup](https://github.com/pszemraj/phasesweep/blob/main/docs/mcp_setup.md) to install the extra, review the catalog authority boundary, configure a client-owned connection, and verify the result.
+
+## Reference
+
+- [Configuration guide](https://github.com/pszemraj/phasesweep/blob/main/docs/config.md): Experiment YAML, search spaces, inheritance, gates, and objective extractors.
+- [Configuration reference](https://github.com/pszemraj/phasesweep/blob/main/docs/config_reference.yaml): per-key types, defaults, valid values, interactions, and lifecycle warnings.
+- [Runtime behavior](https://github.com/pszemraj/phasesweep/blob/main/docs/runtime.md): filesystem layout, locks, GPU leases, process supervision, fingerprints, and resume.
+- [MCP setup](https://github.com/pszemraj/phasesweep/blob/main/docs/mcp_setup.md): installed-package agent onboarding and client-owned setup.
+- [MCP operator reference](https://github.com/pszemraj/phasesweep/blob/main/docs/mcp.md): catalog fields, tools, authorization, run state, and recovery.
+- [Toy experiment and MCP catalog](https://github.com/pszemraj/phasesweep/blob/main/examples/experiment.yaml): a checkout-local CLI example backed by the packaged fake trainer, plus an [MCP catalog](https://github.com/pszemraj/phasesweep/blob/main/examples/catalog.yaml) whose detached-run state and experiment outputs use absolute scratch paths under `/tmp`.
+- [Tiny Decoder Enwik8 example](https://github.com/pszemraj/phasesweep/blob/main/examples/tiny_decoder_enwik8/README.md): real-trainer integration.
+- [Durability invariants](https://github.com/pszemraj/phasesweep/blob/main/docs/invariants.md): the ordering rules the ledger, publication, and recovery paths must hold, and the test that owns each one.
+- [Development](https://github.com/pszemraj/phasesweep/blob/main/docs/development.md): source checkout, contributor setup, and quality gates.
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/pszemraj/phasesweep)
+
+## License
+
+MIT. See [LICENSE](https://github.com/pszemraj/phasesweep/blob/main/LICENSE).