slimconfig 0.1.0__tar.gz

slimconfig-0.1.0/LICENSE

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

slimconfig-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: slimconfig
+Version: 0.1.0
+Summary: YAML configs onto typed dataclass schemas — a lightweight Hydra stand-in
+Author: Zeyu Yang
+License: MIT
+Project-URL: Homepage, https://github.com/zeyuyang8/slimconfig
+Project-URL: Repository, https://github.com/zeyuyang8/slimconfig
+Keywords: config,yaml,omegaconf,dataclass,hydra
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: omegaconf<2.4,>=2.3
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# slimconfig
+
+YAML configs merged onto typed dataclass schemas — a lightweight Hydra stand-in in ~300 lines,
+built on [OmegaConf](https://omegaconf.readthedocs.io).
+
+Two rules, enforced at load time:
+
+* **Every field is required.** A schema's leaves all default to `MISSING`, so a config has to set
+  each one explicitly — a nullable field that is "off" is still written out as `null`, an empty
+  collection as `[]`. Nothing is silently inherited.
+* **Unknown keys are rejected.** A typo in a YAML key is an error, not a value that goes nowhere.
+
+Plus what a research/experiment runner actually needs: Hydra-style `defaults:` composition, a
+`mode` dispatcher, and a run folder that snapshots the exact config it ran with.
+
+## Install
+
+```bash
+pip install slimconfig
+```
+
+## Load a config
+
+```python
+# train.py
+import sys
+from dataclasses import dataclass, field
+from omegaconf import MISSING
+from slimconfig import load_config
+
+@dataclass
+class Optim:
+    lr: float = MISSING
+    warmup_steps: int = MISSING
+
+@dataclass
+class TrainConfig:
+    run_dir: str = MISSING
+    model: str = MISSING
+    optim: Optim = field(default_factory=Optim)
+    resume_from: str | None = MISSING   # "off" must still be spelled `null`
+
+cfg = load_config(TrainConfig, sys.argv[1:])   # -> a real TrainConfig instance
+print(cfg.optim.lr)
+```
+
+```yaml
+# configs/train.yaml
+run_dir: runs/${now:%Y%m%d-%H%M%S}
+model: llama-3-8b
+optim:
+  lr: 2.0e-4
+  warmup_steps: 100
+resume_from: null
+```
+
+```bash
+python train.py configs/train.yaml                 # a file
+python train.py configs/train.yaml optim.lr=1e-4   # ...plus dotted overrides, later wins
+```
+
+Leave `warmup_steps` out and the load fails with
+`TrainConfig is missing required field(s): optim.warmup_steps` — before anything runs.
+
+## Share configs with `defaults:`
+
+Any YAML may carry a top-level `defaults:` list of paths. Listed files merge first, in order, and
+the current file wins on top; composition is recursive, and cycles are caught.
+
+```yaml
+# configs/train_7b.yaml
+defaults: [configs/train.yaml, configs/optim/cosine.yaml]
+model: llama-3-7b
+```
+
+Paths resolve **relative to the current working directory** (the project root scripts are launched
+from), so one path convention holds wherever the including file lives. Absolute paths work too.
+
+## Interpolation resolvers
+
+On top of OmegaConf's own `${a.b}` interpolation, importing slimconfig registers:
+
+| Resolver | Meaning |
+| --- | --- |
+| `${now:%Y%m%d-%H%M%S}` | the load time, `strftime`-formatted — one consistent stamp per process |
+| `${from_yaml:configs/data.yaml,dataset.name}` | one value read out of *another* config, so a config can track a value another file owns without duplicating it |
+
+## Dispatch on `mode`
+
+For a single entry point that fans out to several jobs, `dispatch` reads `mode`, opens and
+snapshots `run_dir`, then calls the matching handler:
+
+```python
+# run.py
+import sys
+from slimconfig import dispatch
+
+MODES = {
+    "train": (TrainConfig, train),      # load TrainConfig strictly, call train(cfg)
+    "eval": (EvalConfig, evaluate),
+    "sweep": run_sweep,                 # bare handler: gets the raw specs, loads its own schema
+}
+raise SystemExit(dispatch(MODES, sys.argv[1:]))
+```
+
+`mode` and `run_dir` are ordinary config keys, so a schema loaded this way declares them itself
+(unknown keys are rejected).
+
+## Run folders
+
+`start_run(run_dir, config)` (called for you by `dispatch`) creates the folder and writes:
+
+* `config.yaml` — the fully-resolved config, re-runnable as-is: `python run.py <run_dir>/config.yaml`
+* `run_meta.json` — argv, cwd, git commit + dirty flag, start time, host
+
+Everything a run produces goes in that same folder, so a result is never separated from the config
+that made it. The snapshot is best-effort — provenance never aborts a run.
+
+## API
+
+| | |
+| --- | --- |
+| `load_config(schema, specs)` | merge specs onto a dataclass schema → a populated instance |
+| `merge_specs(specs)` | merge specs into one unvalidated `DictConfig` |
+| `peek(specs, key)` | read one top-level key before choosing a schema |
+| `dispatch(modes, specs)` | `mode` → handler, with the run folder opened and snapshotted |
+| `start_run(run_dir, config)` | create the run folder, write `config.yaml` + `run_meta.json` |
+| `load_mapping_yaml(path)` | one YAML → `DictConfig`, with `defaults:` composed |
+| `load_yaml(path)` | one YAML → `dict`, plain PyYAML, no composition |
+
+A *spec* is a YAML file path, a `dotted.key=value` string, or a ready-made mapping/`DictConfig` —
+so a caller can merge values it computed at runtime under the same "later wins" rule.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

slimconfig-0.1.0/README.md

@@ -0,0 +1,144 @@
+# slimconfig
+
+YAML configs merged onto typed dataclass schemas — a lightweight Hydra stand-in in ~300 lines,
+built on [OmegaConf](https://omegaconf.readthedocs.io).
+
+Two rules, enforced at load time:
+
+* **Every field is required.** A schema's leaves all default to `MISSING`, so a config has to set
+  each one explicitly — a nullable field that is "off" is still written out as `null`, an empty
+  collection as `[]`. Nothing is silently inherited.
+* **Unknown keys are rejected.** A typo in a YAML key is an error, not a value that goes nowhere.
+
+Plus what a research/experiment runner actually needs: Hydra-style `defaults:` composition, a
+`mode` dispatcher, and a run folder that snapshots the exact config it ran with.
+
+## Install
+
+```bash
+pip install slimconfig
+```
+
+## Load a config
+
+```python
+# train.py
+import sys
+from dataclasses import dataclass, field
+from omegaconf import MISSING
+from slimconfig import load_config
+
+@dataclass
+class Optim:
+    lr: float = MISSING
+    warmup_steps: int = MISSING
+
+@dataclass
+class TrainConfig:
+    run_dir: str = MISSING
+    model: str = MISSING
+    optim: Optim = field(default_factory=Optim)
+    resume_from: str | None = MISSING   # "off" must still be spelled `null`
+
+cfg = load_config(TrainConfig, sys.argv[1:])   # -> a real TrainConfig instance
+print(cfg.optim.lr)
+```
+
+```yaml
+# configs/train.yaml
+run_dir: runs/${now:%Y%m%d-%H%M%S}
+model: llama-3-8b
+optim:
+  lr: 2.0e-4
+  warmup_steps: 100
+resume_from: null
+```
+
+```bash
+python train.py configs/train.yaml                 # a file
+python train.py configs/train.yaml optim.lr=1e-4   # ...plus dotted overrides, later wins
+```
+
+Leave `warmup_steps` out and the load fails with
+`TrainConfig is missing required field(s): optim.warmup_steps` — before anything runs.
+
+## Share configs with `defaults:`
+
+Any YAML may carry a top-level `defaults:` list of paths. Listed files merge first, in order, and
+the current file wins on top; composition is recursive, and cycles are caught.
+
+```yaml
+# configs/train_7b.yaml
+defaults: [configs/train.yaml, configs/optim/cosine.yaml]
+model: llama-3-7b
+```
+
+Paths resolve **relative to the current working directory** (the project root scripts are launched
+from), so one path convention holds wherever the including file lives. Absolute paths work too.
+
+## Interpolation resolvers
+
+On top of OmegaConf's own `${a.b}` interpolation, importing slimconfig registers:
+
+| Resolver | Meaning |
+| --- | --- |
+| `${now:%Y%m%d-%H%M%S}` | the load time, `strftime`-formatted — one consistent stamp per process |
+| `${from_yaml:configs/data.yaml,dataset.name}` | one value read out of *another* config, so a config can track a value another file owns without duplicating it |
+
+## Dispatch on `mode`
+
+For a single entry point that fans out to several jobs, `dispatch` reads `mode`, opens and
+snapshots `run_dir`, then calls the matching handler:
+
+```python
+# run.py
+import sys
+from slimconfig import dispatch
+
+MODES = {
+    "train": (TrainConfig, train),      # load TrainConfig strictly, call train(cfg)
+    "eval": (EvalConfig, evaluate),
+    "sweep": run_sweep,                 # bare handler: gets the raw specs, loads its own schema
+}
+raise SystemExit(dispatch(MODES, sys.argv[1:]))
+```
+
+`mode` and `run_dir` are ordinary config keys, so a schema loaded this way declares them itself
+(unknown keys are rejected).
+
+## Run folders
+
+`start_run(run_dir, config)` (called for you by `dispatch`) creates the folder and writes:
+
+* `config.yaml` — the fully-resolved config, re-runnable as-is: `python run.py <run_dir>/config.yaml`
+* `run_meta.json` — argv, cwd, git commit + dirty flag, start time, host
+
+Everything a run produces goes in that same folder, so a result is never separated from the config
+that made it. The snapshot is best-effort — provenance never aborts a run.
+
+## API
+
+| | |
+| --- | --- |
+| `load_config(schema, specs)` | merge specs onto a dataclass schema → a populated instance |
+| `merge_specs(specs)` | merge specs into one unvalidated `DictConfig` |
+| `peek(specs, key)` | read one top-level key before choosing a schema |
+| `dispatch(modes, specs)` | `mode` → handler, with the run folder opened and snapshotted |
+| `start_run(run_dir, config)` | create the run folder, write `config.yaml` + `run_meta.json` |
+| `load_mapping_yaml(path)` | one YAML → `DictConfig`, with `defaults:` composed |
+| `load_yaml(path)` | one YAML → `dict`, plain PyYAML, no composition |
+
+A *spec* is a YAML file path, a `dotted.key=value` string, or a ready-made mapping/`DictConfig` —
+so a caller can merge values it computed at runtime under the same "later wins" rule.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

slimconfig-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "slimconfig"
+# One source of truth: slimconfig.__version__ (see [tool.setuptools.dynamic] below).
+dynamic = ["version"]
+description = "YAML configs onto typed dataclass schemas — a lightweight Hydra stand-in"
+readme = "README.md"
+license = {text = "MIT"}
+# 3.12+: the loader uses PEP 695 syntax (`type Spec = ...`, `def load_config[T]`).
+requires-python = ">=3.12"
+dependencies = [
+    # Pinned below 2.4: 2.4.0.dev deprecates register_new_resolver, which config.py uses for the
+    # ${now:...} / ${from_yaml:...} resolvers — a stable 2.3.x keeps that API warning-free.
+    "omegaconf>=2.3,<2.4",
+    "pyyaml",
+]
+authors = [
+    {name = "Zeyu Yang"},
+]
+keywords = ["config", "yaml", "omegaconf", "dataclass", "hydra"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+]
+
+[project.urls]
+Homepage = "https://github.com/zeyuyang8/slimconfig"
+Repository = "https://github.com/zeyuyang8/slimconfig"
+
+[tool.setuptools.dynamic]
+version = {attr = "slimconfig.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["slimconfig*"]
+
+[tool.setuptools.package-data]
+slimconfig = ["py.typed"]
+
+[tool.ruff]
+line-length = 150
+
+[tool.ruff.lint]
+extend-ignore = ["E203"]
+
+[tool.ruff.lint.per-file-ignores]
+# Every config problem is reported as ValueError, including the isinstance guards (TRY004 wants
+# TypeError there); the ${now:...} stamp is intentionally local time (DTZ005).
+"src/slimconfig/config.py" = ["TRY004", "DTZ005"]

slimconfig-0.1.0/setup.cfg

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

slimconfig-0.1.0/src/slimconfig/__init__.py

@@ -0,0 +1,31 @@
+# slimconfig — YAML configs onto typed dataclass schemas, a lightweight Hydra stand-in.
+#
+#     from slimconfig import load_config
+#     cfg = load_config(MyConfig, sys.argv[1:])   # MyConfig: a dataclass of MISSING fields
+#
+# See config.py for the YAML loader + `defaults:` composition and the ${now:...} / ${from_yaml:...}
+# resolvers, and structured.py for the typed, all-fields-required schema loader, the `mode` dispatcher,
+# and the run-folder snapshot.
+
+from .config import load_mapping_yaml, load_yaml
+from .structured import (
+    Spec,
+    dispatch,
+    load_config,
+    merge_specs,
+    peek,
+    start_run,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Spec",
+    "dispatch",
+    "load_config",
+    "load_mapping_yaml",
+    "load_yaml",
+    "merge_specs",
+    "peek",
+    "start_run",
+]

slimconfig-0.1.0/src/slimconfig/config.py

@@ -0,0 +1,105 @@
+# slimconfig.config — the YAML layer: read a file, compose its `defaults:` chain.
+#
+# Read a YAML config into an OmegaConf DictConfig and compose any `defaults: [...]` chain:
+#   * load_mapping_yaml — load a YAML, require a top-level mapping, compose any `defaults:` chain
+#     (current file wins), and return a DictConfig.
+#   * load_yaml — plain PyYAML: read a YAML file into a dict (no `defaults:` composition).
+# The typed, all-fields-required loader (load_config) lives in structured.py.
+#
+# Importing this module also registers two OmegaConf interpolation resolvers (once, process-wide):
+#   * ${now:<strftime>}          — stamp a value with the load time.
+#   * ${from_yaml:<path>,<key>}  — read one value OUT of another config file, so a config can track
+#                                  a value another owns without duplicating it.
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+from omegaconf import DictConfig, ListConfig, OmegaConf
+
+# ``${now:<strftime>}`` — interpolate the current time into any config value (Hydra-style). Registered
+# at import so every OmegaConf-loaded config has it. ``replace=True`` keeps re-import idempotent;
+# ``use_cache=True`` gives ONE consistent timestamp for the whole load (and per process).
+OmegaConf.register_new_resolver(
+    "now", lambda fmt: datetime.now().strftime(fmt), replace=True, use_cache=True
+)
+
+# Sentinel telling OmegaConf.select "not found" apart from a real ``null`` value at the key.
+_NOT_FOUND = object()
+
+
+def _select_from_yaml(path: str, key: str) -> Any:
+    cfg = load_mapping_yaml(path.strip())
+    val = OmegaConf.select(cfg, key.strip(), default=_NOT_FOUND, throw_on_missing=True)
+    if val is _NOT_FOUND:
+        raise ValueError(f"${{from_yaml:{path},{key}}}: {path!r} has no key {key.strip()!r}")
+    return val
+
+
+OmegaConf.register_new_resolver("from_yaml", _select_from_yaml, replace=True, use_cache=True)
+
+
+def load_yaml(path: str | Path) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as f:
+        try:
+            cfg = yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Config {path} is not valid YAML: {e}") from e
+    if not isinstance(cfg, dict):
+        raise ValueError(f"Config {path} did not parse to a mapping (got {type(cfg).__name__})")
+    return cfg
+
+
+def load_mapping_yaml(path: str) -> DictConfig:
+    return _compose(Path(path).resolve(), visiting=())
+
+
+def _load_one(path: Path) -> DictConfig:
+    try:
+        loaded = OmegaConf.load(path)
+    except OSError as e:
+        # OmegaConf.load raises OSError("Invalid loaded object type: <type>") for a top-level SCALAR
+        # yaml (42 / 3.14 / true) before we can type-check it. Re-raise THAT as the same path-naming
+        # ValueError so a scalar fails like every other non-mapping shape. A genuine IO error
+        # (missing/unreadable file -> FileNotFoundError) is NOT a parse problem -> let it propagate.
+        if isinstance(e, FileNotFoundError) or "Invalid loaded object type" not in str(e):
+            raise
+        raise ValueError(
+            f"config file {str(path)!r} did not parse to a mapping (got {type(e).__name__}: {e})"
+        ) from e
+    if not isinstance(loaded, DictConfig):
+        raise ValueError(
+            f"config file {str(path)!r} did not parse to a mapping (got {type(loaded).__name__})"
+        )
+    return loaded
+
+
+def _compose(path: Path, visiting: tuple[Path, ...]) -> DictConfig:
+    if path in visiting:
+        chain = " -> ".join(str(p) for p in (*visiting, path))
+        raise ValueError(f"`defaults` cycle detected: {chain}")
+    loaded = _load_one(path)
+    defaults = loaded.pop("defaults", None)
+    if defaults is None:
+        return loaded
+    if not isinstance(defaults, ListConfig):
+        raise ValueError(
+            f"config file {str(path)!r}: top-level `defaults` must be a list of yaml paths, "
+            f"got {type(defaults).__name__}"
+        )
+    merged: DictConfig = OmegaConf.create({})  # type: ignore[assignment]
+    for entry in defaults:
+        if not isinstance(entry, str):
+            raise ValueError(
+                f"config file {str(path)!r}: each `defaults` entry must be a string path, "
+                f"got {type(entry).__name__}: {entry!r}"
+            )
+        # Defaults paths resolve relative to the CWD — the project root every script is run from —
+        # so one config path convention holds across a repo, wherever the including file lives.
+        # (An absolute entry resolves to itself: Path("/abs") wins over the cwd join.)
+        entry_path = (Path.cwd() / entry).resolve()
+        merged = cast(DictConfig, OmegaConf.merge(merged, _compose(entry_path, (*visiting, path))))
+    return cast(DictConfig, OmegaConf.merge(merged, loaded))

slimconfig-0.1.0/src/slimconfig/structured.py

@@ -0,0 +1,168 @@
+# Typed, all-fields-required config loading — merge YAML onto a dataclass schema.
+#
+# A schema is a @dataclass whose every leaf defaults to omegaconf.MISSING, so a config must set
+# each field explicitly (nothing is silently filled in). load_config merges one or more specs (YAML
+# files and/or dotted key=value overrides) onto that schema and returns a fully populated instance.
+# Two rules, enforced at load time:
+#   * every leaf must end up set — an unset MISSING leaf raises (a nullable field that is "off" must
+#     still be present as null; an empty collection must be written out as []);
+#   * unknown keys are rejected (OmegaConf struct mode).
+# YAML files are read via slimconfig.config.load_mapping_yaml, so each may carry a top-level
+# `defaults: [<path>, ...]` list to compose shared configs (Hydra-style: listed files merge first,
+# the current file wins on top).
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import socket
+import subprocess
+import sys
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, cast
+
+from omegaconf import DictConfig, OmegaConf
+
+from .config import load_mapping_yaml
+
+# One config source: a YAML file path, a `dotted.key=value` override, or a ready-made mapping.
+type Spec = str | Mapping[str, Any] | DictConfig
+
+
+# Dotted paths of every leaf field still unset (recurses into nested configs).
+def _missing_fields(cfg: DictConfig, prefix: str = "") -> list[str]:
+    missing: list[str] = []
+    for raw_key in cfg:
+        key = str(raw_key)
+        if OmegaConf.is_missing(cfg, key):
+            missing.append(prefix + key)
+            continue
+        value = cfg[key]
+        if OmegaConf.is_dict(value):  # recurse into nested configs only; lists are leaf values
+            missing.extend(_missing_fields(cast(DictConfig, value), prefix + key + "."))
+    return missing
+
+
+# Merge YAML files, dotted key=value overrides, and already-built mappings into one unstructured
+# config. A YAML file is loaded via load_mapping_yaml, so it may carry a top-level `defaults: [...]`
+# list to compose others; a mapping spec lets a caller merge values it computed itself (e.g. one cell
+# of a sweep matrix resolved at runtime) with the same precedence rule — later specs win.
+def merge_specs(specs: list[Spec]) -> DictConfig:
+    merged = OmegaConf.create()
+    for spec in specs:
+        if isinstance(spec, Mapping | DictConfig):
+            merged = OmegaConf.merge(merged, spec)
+        elif Path(spec).is_file():
+            merged = OmegaConf.merge(merged, load_mapping_yaml(spec))
+        elif "=" in spec:
+            merged = OmegaConf.merge(merged, OmegaConf.from_dotlist([spec]))
+        else:
+            raise FileNotFoundError(
+                f"config spec {spec!r} is neither a file nor a key=value override"
+            )
+    return cast(DictConfig, merged)
+
+
+# Merge `specs` (YAML files and/or dotted key=value overrides) onto `schema`, in order (list a file
+# before the overrides that should win over it). Returns a fully-populated schema instance. Raises
+# ValueError if any leaf is left unset, FileNotFoundError for a bad spec, and OmegaConf errors for
+# unknown keys / type mismatches.
+def load_config[T](schema: type[T], specs: list[Spec]) -> T:
+    merged = OmegaConf.merge(OmegaConf.structured(schema), merge_specs(specs))
+    missing = _missing_fields(cast(DictConfig, merged))
+    if missing:
+        raise ValueError(f"{schema.__name__} is missing required field(s): {', '.join(missing)}")
+    return cast(T, OmegaConf.to_object(merged))
+
+
+# Return top-level `key` from the merged specs (or None), without validation — lets a caller pick a
+# schema before strict structured loading (e.g. read `method` to choose which schema to load). Accepts
+# the same specs as load_config (YAML file paths and/or dotted key=value overrides), so it works with
+# the bare-file-path invocation entry points use. Unknown keys are tolerated (no struct check).
+def peek(args: list[Spec], key: str) -> Any:
+    return merge_specs(args).get(key)
+
+
+def _git(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", *args], capture_output=True, text=True, timeout=10, check=False)
+
+
+def _git_head() -> dict[str, Any]:
+    try:
+        commit = _git("rev-parse", "HEAD")
+        if commit.returncode:
+            return {}
+        return {
+            "git_commit": commit.stdout.strip(),
+            "git_dirty": bool(_git("status", "--porcelain").stdout.strip()),
+        }
+    except (OSError, subprocess.SubprocessError):
+        return {}
+
+
+# Turn whatever a caller has into the plain config mapping to snapshot: raw specs (the dispatch path —
+# because every field must be set explicitly, the merged YAML already IS the full config), a DictConfig,
+# or a dataclass instance a handler built at runtime (e.g. one cell of a sweep matrix).
+def _as_dictconfig(config: Any) -> DictConfig:
+    if isinstance(config, list):
+        return merge_specs(cast(list[Spec], config))
+    if isinstance(config, DictConfig):
+        return config
+    if dataclasses.is_dataclass(config) or isinstance(config, Mapping):
+        return cast(DictConfig, OmegaConf.structured(config))
+    raise TypeError(f"cannot snapshot config of type {type(config).__name__}")
+
+
+# Open the run's folder and record what produced it. Writes two files:
+#   config.yaml   — the fully-resolved config, re-runnable as-is (`python run.py <run_dir>/config.yaml`)
+#   run_meta.json — argv / cwd / git commit / start time / host
+# Everything the run produces goes in this same folder, so a result is never separated from its config.
+# The folder itself must be creatable (the run needs somewhere to write); the snapshot is best-effort —
+# provenance never aborts a run.
+def start_run(run_dir: str, config: Any) -> str:
+    os.makedirs(run_dir, exist_ok=True)
+    try:
+        # Render BOTH payloads before touching a file: re-running a run from its own snapshot
+        # (`python run.py <run_dir>/config.yaml`) passes the very file we are about to overwrite, and
+        # opening it "w" first would truncate it out from under the read.
+        snapshot = OmegaConf.to_yaml(_as_dictconfig(config), resolve=True)
+        meta = json.dumps({
+            "argv": sys.argv,
+            "cwd": os.getcwd(),
+            "started": datetime.now(UTC).isoformat(timespec="seconds"),
+            "host": socket.gethostname(),
+            **_git_head(),
+        }, indent=2, sort_keys=True)
+        with open(os.path.join(run_dir, "config.yaml"), "w", encoding="utf-8") as f:
+            f.write(snapshot)
+        with open(os.path.join(run_dir, "run_meta.json"), "w", encoding="utf-8") as f:
+            f.write(meta)
+    except (OSError, TypeError, ValueError) as e:
+        print(f"[slimconfig] could not snapshot the config into {run_dir} ({e})")
+    return run_dir
+
+
+# Run the handler the config's `mode` selects — the whole body of every entry point, so the mode
+# contract (and its error message) is written once. `modes` maps a mode name to either
+#   (schema, handler)  — load `schema` strictly, call handler(cfg); the usual case, or
+#   handler            — call handler(specs) and let it load its own config, for the modes whose schema
+#                        depends on another field (e.g. one schema per `method`).
+# Both branches get their `run_dir` opened and snapshotted first (see start_run), so no handler has to
+# remember to do it.
+def dispatch(modes: Mapping[str, Any], specs: list[Spec]) -> int:
+    mode = peek(specs, "mode")
+    if mode not in modes:
+        raise SystemExit(f"config must set `mode` to one of {', '.join(modes)} (got {mode!r})")
+    run_dir = peek(specs, "run_dir")
+    if not run_dir:
+        raise SystemExit("config must set `run_dir` — every run owns a folder holding its config and results")
+    start_run(run_dir, specs)
+
+    entry = modes[mode]
+    if isinstance(entry, tuple):
+        schema, handler = entry
+        return handler(load_config(schema, specs))
+    return entry(specs)

slimconfig-0.1.0/src/slimconfig.egg-info/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: slimconfig
+Version: 0.1.0
+Summary: YAML configs onto typed dataclass schemas — a lightweight Hydra stand-in
+Author: Zeyu Yang
+License: MIT
+Project-URL: Homepage, https://github.com/zeyuyang8/slimconfig
+Project-URL: Repository, https://github.com/zeyuyang8/slimconfig
+Keywords: config,yaml,omegaconf,dataclass,hydra
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: omegaconf<2.4,>=2.3
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# slimconfig
+
+YAML configs merged onto typed dataclass schemas — a lightweight Hydra stand-in in ~300 lines,
+built on [OmegaConf](https://omegaconf.readthedocs.io).
+
+Two rules, enforced at load time:
+
+* **Every field is required.** A schema's leaves all default to `MISSING`, so a config has to set
+  each one explicitly — a nullable field that is "off" is still written out as `null`, an empty
+  collection as `[]`. Nothing is silently inherited.
+* **Unknown keys are rejected.** A typo in a YAML key is an error, not a value that goes nowhere.
+
+Plus what a research/experiment runner actually needs: Hydra-style `defaults:` composition, a
+`mode` dispatcher, and a run folder that snapshots the exact config it ran with.
+
+## Install
+
+```bash
+pip install slimconfig
+```
+
+## Load a config
+
+```python
+# train.py
+import sys
+from dataclasses import dataclass, field
+from omegaconf import MISSING
+from slimconfig import load_config
+
+@dataclass
+class Optim:
+    lr: float = MISSING
+    warmup_steps: int = MISSING
+
+@dataclass
+class TrainConfig:
+    run_dir: str = MISSING
+    model: str = MISSING
+    optim: Optim = field(default_factory=Optim)
+    resume_from: str | None = MISSING   # "off" must still be spelled `null`
+
+cfg = load_config(TrainConfig, sys.argv[1:])   # -> a real TrainConfig instance
+print(cfg.optim.lr)
+```
+
+```yaml
+# configs/train.yaml
+run_dir: runs/${now:%Y%m%d-%H%M%S}
+model: llama-3-8b
+optim:
+  lr: 2.0e-4
+  warmup_steps: 100
+resume_from: null
+```
+
+```bash
+python train.py configs/train.yaml                 # a file
+python train.py configs/train.yaml optim.lr=1e-4   # ...plus dotted overrides, later wins
+```
+
+Leave `warmup_steps` out and the load fails with
+`TrainConfig is missing required field(s): optim.warmup_steps` — before anything runs.
+
+## Share configs with `defaults:`
+
+Any YAML may carry a top-level `defaults:` list of paths. Listed files merge first, in order, and
+the current file wins on top; composition is recursive, and cycles are caught.
+
+```yaml
+# configs/train_7b.yaml
+defaults: [configs/train.yaml, configs/optim/cosine.yaml]
+model: llama-3-7b
+```
+
+Paths resolve **relative to the current working directory** (the project root scripts are launched
+from), so one path convention holds wherever the including file lives. Absolute paths work too.
+
+## Interpolation resolvers
+
+On top of OmegaConf's own `${a.b}` interpolation, importing slimconfig registers:
+
+| Resolver | Meaning |
+| --- | --- |
+| `${now:%Y%m%d-%H%M%S}` | the load time, `strftime`-formatted — one consistent stamp per process |
+| `${from_yaml:configs/data.yaml,dataset.name}` | one value read out of *another* config, so a config can track a value another file owns without duplicating it |
+
+## Dispatch on `mode`
+
+For a single entry point that fans out to several jobs, `dispatch` reads `mode`, opens and
+snapshots `run_dir`, then calls the matching handler:
+
+```python
+# run.py
+import sys
+from slimconfig import dispatch
+
+MODES = {
+    "train": (TrainConfig, train),      # load TrainConfig strictly, call train(cfg)
+    "eval": (EvalConfig, evaluate),
+    "sweep": run_sweep,                 # bare handler: gets the raw specs, loads its own schema
+}
+raise SystemExit(dispatch(MODES, sys.argv[1:]))
+```
+
+`mode` and `run_dir` are ordinary config keys, so a schema loaded this way declares them itself
+(unknown keys are rejected).
+
+## Run folders
+
+`start_run(run_dir, config)` (called for you by `dispatch`) creates the folder and writes:
+
+* `config.yaml` — the fully-resolved config, re-runnable as-is: `python run.py <run_dir>/config.yaml`
+* `run_meta.json` — argv, cwd, git commit + dirty flag, start time, host
+
+Everything a run produces goes in that same folder, so a result is never separated from the config
+that made it. The snapshot is best-effort — provenance never aborts a run.
+
+## API
+
+| | |
+| --- | --- |
+| `load_config(schema, specs)` | merge specs onto a dataclass schema → a populated instance |
+| `merge_specs(specs)` | merge specs into one unvalidated `DictConfig` |
+| `peek(specs, key)` | read one top-level key before choosing a schema |
+| `dispatch(modes, specs)` | `mode` → handler, with the run folder opened and snapshotted |
+| `start_run(run_dir, config)` | create the run folder, write `config.yaml` + `run_meta.json` |
+| `load_mapping_yaml(path)` | one YAML → `DictConfig`, with `defaults:` composed |
+| `load_yaml(path)` | one YAML → `dict`, plain PyYAML, no composition |
+
+A *spec* is a YAML file path, a `dotted.key=value` string, or a ready-made mapping/`DictConfig` —
+so a caller can merge values it computed at runtime under the same "later wins" rule.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

slimconfig-0.1.0/src/slimconfig.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/slimconfig/__init__.py
+src/slimconfig/config.py
+src/slimconfig/py.typed
+src/slimconfig/structured.py
+src/slimconfig.egg-info/PKG-INFO
+src/slimconfig.egg-info/SOURCES.txt
+src/slimconfig.egg-info/dependency_links.txt
+src/slimconfig.egg-info/requires.txt
+src/slimconfig.egg-info/top_level.txt
+tests/test_config.py
+tests/test_structured.py

slimconfig-0.1.0/src/slimconfig.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

slimconfig-0.1.0/src/slimconfig.egg-info/requires.txt

@@ -0,0 +1,6 @@
+omegaconf<2.4,>=2.3
+pyyaml
+
+[dev]
+pytest
+ruff

slimconfig-0.1.0/src/slimconfig.egg-info/top_level.txt

@@ -0,0 +1 @@
+slimconfig

slimconfig-0.1.0/tests/test_config.py

@@ -0,0 +1,150 @@
+# The YAML layer: load_yaml / load_mapping_yaml, `defaults:` composition, and the resolvers.
+
+from __future__ import annotations
+
+import pytest
+from omegaconf import OmegaConf
+
+from slimconfig import load_mapping_yaml, load_yaml
+
+
+def write(path, text: str) -> str:
+    path.write_text(text, encoding="utf-8")
+    return str(path)
+
+
+def test_load_yaml_returns_plain_dict(tmp_path):
+    path = write(tmp_path / "a.yaml", "a: 1\nb: [1, 2]\n")
+    assert load_yaml(path) == {"a": 1, "b": [1, 2]}
+
+
+@pytest.mark.parametrize("body", ["- 1\n- 2\n", "42\n"])
+def test_load_yaml_rejects_non_mapping(tmp_path, body):
+    path = write(tmp_path / "a.yaml", body)
+    with pytest.raises(ValueError, match="did not parse to a mapping"):
+        load_yaml(path)
+
+
+def test_load_yaml_rejects_invalid_yaml(tmp_path):
+    path = write(tmp_path / "a.yaml", "a: [1,\n")
+    with pytest.raises(ValueError, match="not valid YAML"):
+        load_yaml(path)
+
+
+def test_load_mapping_yaml_without_defaults(tmp_path):
+    path = write(tmp_path / "a.yaml", "a: 1\nnested: {x: 2}\n")
+    cfg = load_mapping_yaml(path)
+    assert cfg.a == 1
+    assert cfg.nested.x == 2
+
+
+# (A bare string yaml is NOT in this list: OmegaConf parses `just a string` into the mapping
+# {"just a string": None}, so it never reaches the type check.)
+@pytest.mark.parametrize("body", ["- 1\n", "42\n"])
+def test_load_mapping_yaml_rejects_non_mapping(tmp_path, body):
+    path = write(tmp_path / "a.yaml", body)
+    with pytest.raises(ValueError, match="did not parse to a mapping"):
+        load_mapping_yaml(path)
+
+
+def test_load_mapping_yaml_missing_file_is_not_a_parse_error(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        load_mapping_yaml(str(tmp_path / "nope.yaml"))
+
+
+# ── `defaults:` composition ──────────────────────────────────────────────────
+
+
+def test_defaults_current_file_wins_and_merges_deeply(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    write(tmp_path / "base.yaml", "a: 1\nb: 2\nnested: {x: 1, y: 1}\n")
+    child = write(tmp_path / "child.yaml", "defaults: [base.yaml]\nb: 20\nnested: {y: 20}\n")
+    cfg = load_mapping_yaml(child)
+    assert cfg.a == 1  # inherited
+    assert cfg.b == 20  # overridden
+    assert (cfg.nested.x, cfg.nested.y) == (1, 20)  # deep merge, not replacement
+    assert "defaults" not in cfg
+
+
+def test_defaults_later_entry_wins_over_earlier(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    write(tmp_path / "one.yaml", "a: 1\nshared: from_one\n")
+    write(tmp_path / "two.yaml", "b: 2\nshared: from_two\n")
+    child = write(tmp_path / "child.yaml", "defaults: [one.yaml, two.yaml]\n")
+    cfg = load_mapping_yaml(child)
+    assert (cfg.a, cfg.b, cfg.shared) == (1, 2, "from_two")
+
+
+def test_defaults_compose_recursively(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    write(tmp_path / "grand.yaml", "a: 1\n")
+    write(tmp_path / "parent.yaml", "defaults: [grand.yaml]\nb: 2\n")
+    child = write(tmp_path / "child.yaml", "defaults: [parent.yaml]\nc: 3\n")
+    cfg = load_mapping_yaml(child)
+    assert (cfg.a, cfg.b, cfg.c) == (1, 2, 3)
+
+
+def test_defaults_resolve_against_cwd_not_the_including_file(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "configs").mkdir()
+    write(tmp_path / "configs" / "base.yaml", "a: 1\n")
+    # The `defaults` entry is written from the project root, even though the file that carries it
+    # sits one directory down next to base.yaml.
+    child = write(tmp_path / "configs" / "child.yaml", "defaults: [configs/base.yaml]\nb: 2\n")
+    cfg = load_mapping_yaml(child)
+    assert (cfg.a, cfg.b) == (1, 2)
+
+
+def test_defaults_cycle_is_detected(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    write(tmp_path / "a.yaml", "defaults: [b.yaml]\n")
+    write(tmp_path / "b.yaml", "defaults: [a.yaml]\n")
+    with pytest.raises(ValueError, match="`defaults` cycle detected"):
+        load_mapping_yaml(str(tmp_path / "a.yaml"))
+
+
+@pytest.mark.parametrize(
+    ("body", "match"),
+    [
+        ("defaults: base.yaml\n", "must be a list of yaml paths"),
+        ("defaults: [{a: 1}]\n", "must be a string path"),
+    ],
+)
+def test_defaults_shape_is_validated(tmp_path, monkeypatch, body, match):
+    monkeypatch.chdir(tmp_path)
+    write(tmp_path / "base.yaml", "a: 1\n")
+    path = write(tmp_path / "child.yaml", body)
+    with pytest.raises(ValueError, match=match):
+        load_mapping_yaml(path)
+
+
+# ── resolvers ────────────────────────────────────────────────────────────────
+
+
+def test_now_resolver_stamps_a_value(tmp_path):
+    path = write(tmp_path / "a.yaml", "run_dir: runs/${now:%Y}\n")
+    cfg = load_mapping_yaml(path)
+    assert cfg.run_dir.startswith("runs/2")
+    assert len(cfg.run_dir) == len("runs/YYYY")
+
+
+def test_now_resolver_is_one_consistent_stamp(tmp_path):
+    path = write(tmp_path / "a.yaml", "one: ${now:%Y%m%d-%H%M%S}\ntwo: ${now:%Y%m%d-%H%M%S}\n")
+    cfg = load_mapping_yaml(path)
+    assert cfg.one == cfg.two
+
+
+def test_from_yaml_resolver_reads_another_config(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    write(tmp_path / "data.yaml", "dataset:\n  name: wikitext\n")
+    path = write(tmp_path / "a.yaml", "tag: ${from_yaml:data.yaml,dataset.name}\n")
+    assert load_mapping_yaml(path).tag == "wikitext"
+
+
+def test_from_yaml_resolver_rejects_a_missing_key(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    write(tmp_path / "data.yaml", "dataset:\n  name: wikitext\n")
+    path = write(tmp_path / "a.yaml", "tag: ${from_yaml:data.yaml,dataset.nope}\n")
+    cfg = load_mapping_yaml(path)
+    with pytest.raises(Exception, match="has no key"):  # wrapped by omegaconf on access
+        _ = OmegaConf.to_container(cfg, resolve=True)

slimconfig-0.1.0/tests/test_structured.py

@@ -0,0 +1,198 @@
+# The typed layer: merge_specs / load_config / peek, plus start_run and dispatch.
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+import pytest
+from omegaconf import MISSING, OmegaConf
+
+from slimconfig import dispatch, load_config, merge_specs, peek, start_run
+
+
+@dataclass
+class Optim:
+    lr: float = MISSING
+    warmup_steps: int = MISSING
+
+
+@dataclass
+class TrainConfig:
+    run_dir: str = MISSING
+    model: str = MISSING
+    tags: list[str] = MISSING
+    resume_from: str | None = MISSING
+    optim: Optim = field(default_factory=Optim)
+
+
+FULL = """
+run_dir: runs/demo
+model: llama
+tags: []
+resume_from: null
+optim:
+  lr: 0.0002
+  warmup_steps: 100
+"""
+
+
+def write(path, text: str) -> str:
+    path.write_text(text, encoding="utf-8")
+    return str(path)
+
+
+# ── merge_specs ──────────────────────────────────────────────────────────────
+
+
+def test_merge_specs_later_spec_wins(tmp_path):
+    path = write(tmp_path / "a.yaml", "a: 1\nb: 2\n")
+    merged = merge_specs([path, "b=20", {"c": 30}])
+    assert (merged.a, merged.b, merged.c) == (1, 20, 30)
+
+
+def test_merge_specs_parses_dotted_overrides(tmp_path):
+    path = write(tmp_path / "a.yaml", FULL)
+    merged = merge_specs([path, "optim.lr=0.5"])
+    assert merged.optim.lr == 0.5
+    assert merged.optim.warmup_steps == 100  # untouched
+
+
+def test_merge_specs_rejects_a_spec_that_is_neither(tmp_path):
+    with pytest.raises(FileNotFoundError, match="neither a file nor a key=value override"):
+        merge_specs(["configs/typo.yaml"])
+
+
+# ── load_config ──────────────────────────────────────────────────────────────
+
+
+def test_load_config_returns_a_populated_instance(tmp_path):
+    cfg = load_config(TrainConfig, [write(tmp_path / "a.yaml", FULL)])
+    assert isinstance(cfg, TrainConfig)
+    assert isinstance(cfg.optim, Optim)
+    assert (cfg.model, cfg.tags, cfg.resume_from) == ("llama", [], None)
+    assert cfg.optim.lr == pytest.approx(2e-4)
+
+
+def test_load_config_overrides_win_over_the_file(tmp_path):
+    path = write(tmp_path / "a.yaml", FULL)
+    cfg = load_config(TrainConfig, [path, "model=qwen", "optim.warmup_steps=7"])
+    assert (cfg.model, cfg.optim.warmup_steps) == ("qwen", 7)
+
+
+def test_load_config_requires_every_leaf(tmp_path):
+    path = write(tmp_path / "a.yaml", "run_dir: runs/demo\nmodel: llama\ntags: []\n")
+    with pytest.raises(ValueError, match=r"missing required field\(s\): resume_from, optim.lr"):
+        load_config(TrainConfig, [path])
+
+
+def test_load_config_rejects_unknown_keys(tmp_path):
+    path = write(tmp_path / "a.yaml", FULL + "typo_key: 1\n")
+    with pytest.raises(Exception, match="typo_key"):
+        load_config(TrainConfig, [path])
+
+
+def test_load_config_rejects_a_wrongly_typed_value(tmp_path):
+    path = write(tmp_path / "a.yaml", FULL.replace("warmup_steps: 100", "warmup_steps: many"))
+    with pytest.raises(Exception, match="warmup_steps"):
+        load_config(TrainConfig, [path])
+
+
+def test_load_config_composes_defaults(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    write(tmp_path / "base.yaml", FULL)
+    child = write(tmp_path / "child.yaml", "defaults: [base.yaml]\nmodel: qwen\n")
+    cfg = load_config(TrainConfig, [child])
+    assert (cfg.model, cfg.optim.warmup_steps) == ("qwen", 100)
+
+
+# ── peek ─────────────────────────────────────────────────────────────────────
+
+
+def test_peek_reads_a_top_level_key_without_validation(tmp_path):
+    path = write(tmp_path / "a.yaml", "mode: train\nunknown_key: 1\n")
+    assert peek([path], "mode") == "train"
+    assert peek([path], "absent") is None
+    assert peek([path, "mode=eval"], "mode") == "eval"
+
+
+# ── start_run ────────────────────────────────────────────────────────────────
+
+
+def test_start_run_writes_a_resolved_snapshot_and_meta(tmp_path):
+    spec = write(tmp_path / "a.yaml", FULL)
+    run_dir = start_run(str(tmp_path / "runs" / "demo"), [spec])
+    snapshot = OmegaConf.load(f"{run_dir}/config.yaml")
+    assert snapshot.model == "llama"
+    meta = json.loads((tmp_path / "runs" / "demo" / "run_meta.json").read_text())
+    assert {"argv", "cwd", "started", "host"} <= meta.keys()
+
+
+def test_start_run_snapshot_is_rerunnable_in_place(tmp_path):
+    # Re-running a run from its own snapshot passes the very file start_run overwrites.
+    spec = write(tmp_path / "a.yaml", FULL)
+    run_dir = start_run(str(tmp_path / "run"), [spec])
+    snapshot = f"{run_dir}/config.yaml"
+    start_run(run_dir, [snapshot])
+    assert load_config(TrainConfig, [snapshot]).model == "llama"
+
+
+def test_start_run_accepts_a_dataclass_instance(tmp_path):
+    cfg = load_config(TrainConfig, [write(tmp_path / "a.yaml", FULL)])
+    run_dir = start_run(str(tmp_path / "run"), cfg)
+    assert OmegaConf.load(f"{run_dir}/config.yaml").optim.warmup_steps == 100
+
+
+def test_start_run_survives_an_unsnapshottable_config(tmp_path, capsys):
+    start_run(str(tmp_path / "run"), object())  # provenance never aborts a run
+    assert "could not snapshot" in capsys.readouterr().out
+    assert (tmp_path / "run").is_dir()
+
+
+# ── dispatch ─────────────────────────────────────────────────────────────────
+
+
+# A schema reached through dispatch declares `mode` itself — the key is part of the config, and
+# unknown keys are rejected.
+@dataclass
+class JobConfig:
+    mode: str = MISSING
+    run_dir: str = MISSING
+    model: str = MISSING
+
+
+def test_dispatch_loads_the_schema_for_a_tuple_entry(tmp_path):
+    seen = {}
+
+    def train(cfg: JobConfig) -> int:
+        seen["model"] = cfg.model
+        return 0
+
+    path = write(tmp_path / "a.yaml", f"mode: train\nrun_dir: {tmp_path / 'run'}\nmodel: llama\n")
+    assert dispatch({"train": (JobConfig, train)}, [path]) == 0
+    assert seen["model"] == "llama"
+    assert (tmp_path / "run" / "config.yaml").is_file()
+
+
+def test_dispatch_passes_raw_specs_to_a_bare_handler(tmp_path):
+    seen = {}
+
+    def sweep(specs) -> int:
+        seen["specs"] = specs
+        return 3
+
+    path = write(tmp_path / "a.yaml", f"mode: sweep\nrun_dir: {tmp_path / 'run'}\n")
+    assert dispatch({"sweep": sweep}, [path]) == 3
+    assert seen["specs"] == [path]
+
+
+def test_dispatch_rejects_an_unknown_mode(tmp_path):
+    path = write(tmp_path / "a.yaml", "mode: nope\nrun_dir: runs/x\n")
+    with pytest.raises(SystemExit, match="must set `mode` to one of train"):
+        dispatch({"train": (TrainConfig, lambda cfg: 0)}, [path])
+
+
+def test_dispatch_requires_a_run_dir(tmp_path):
+    path = write(tmp_path / "a.yaml", "mode: train\n")
+    with pytest.raises(SystemExit, match="must set `run_dir`"):
+        dispatch({"train": (TrainConfig, lambda cfg: 0)}, [path])