worldgap 0.1.0__py3-none-any.whl

worldgap/__init__.py

@@ -0,0 +1,25 @@
+"""worldgap — reusable world-model-based domain-gap quantification.
+
+Ground truth for this package's design: docs/TECHNICAL_SPEC.md.
+"""
+
+from .analyzer import GapAnalyzer, GapResult
+from .config import EncoderConfig, GapConfig, TrainingConfig, WorldModelConfig
+from .data.index import RolloutIndex
+from .data.rollout import Rollout
+from .report import ReportEntry, generate_report
+
+__all__ = [
+    "GapAnalyzer",
+    "GapResult",
+    "GapConfig",
+    "EncoderConfig",
+    "WorldModelConfig",
+    "TrainingConfig",
+    "Rollout",
+    "RolloutIndex",
+    "ReportEntry",
+    "generate_report",
+]
+
+__version__ = "0.1.0"

worldgap/analyzer.py

@@ -0,0 +1,212 @@
+"""Top-level GapAnalyzer API, per TECHNICAL_SPEC.md Section 9.1.
+
+This is the one class both V1 (perception) and V2 (actuation) go through — only
+`config.modality` changes which encoder gets built. `tests/test_modality_swap.py`
+is the concrete, runnable test of the reusability claim in spec Section 3: if
+that test ever requires touching this file to pass for a new modality, the
+architecture has a hidden assumption that needs fixing here, not around it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+import torch
+from torch.utils.data import DataLoader, Dataset
+
+from .config import GapConfig
+from .data.rollout import Rollout
+from .metrics.frechet import FrechetResult, frechet_distance
+from .metrics.mmd import MMDResult, mmd_squared
+from .models.encoders.actuator_encoder import ActuatorEncoder
+from .models.encoders.landmark_encoder import LandmarkEncoder
+from .models.world_model import WorldModel
+
+
+@dataclass
+class GapResult:
+    """Per spec 9.1. `n_source`/`n_target`/`confidence` are exposed as
+    top-level read-only properties (proxying `frechet`) so callers can write
+    `result.confidence` as the spec's own API example shows, without this
+    class duplicating storage for values `FrechetResult` already owns.
+    """
+
+    frechet: FrechetResult
+    mmd: MMDResult
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def n_source(self) -> int:
+        return self.frechet.n_source
+
+    @property
+    def n_target(self) -> int:
+        return self.frechet.n_target
+
+    @property
+    def confidence(self) -> str:
+        return self.frechet.confidence
+
+
+class _WindowDataset(Dataset):
+    """Slices one (context, future) window from the start of each rollout.
+
+    Known simplification, documented rather than hidden: rollouts shorter than
+    context_frames + predict_frames are skipped and counted in `.skipped`, and
+    only one window per rollout is taken (no sliding-window augmentation yet).
+    Both are reasonable v0.1 choices, not silent bugs — surfaced to the caller
+    via GapAnalyzer.fit()'s returned dict.
+    """
+
+    def __init__(self, rollouts: list[Rollout], context_frames: int, predict_frames: int):
+        self.windows: list[tuple] = []
+        self.skipped = 0
+        total_len = context_frames + predict_frames
+        for r in rollouts:
+            if r.states.shape[0] < total_len:
+                self.skipped += 1
+                continue
+            self.windows.append(
+                (
+                    r.states[:context_frames],
+                    r.presence_mask[:context_frames],
+                    r.states[context_frames:total_len],
+                    r.presence_mask[context_frames:total_len],
+                )
+            )
+
+    def __len__(self) -> int:
+        return len(self.windows)
+
+    def __getitem__(self, idx: int):
+        ctx_x, ctx_m, fut_x, fut_m = self.windows[idx]
+        return (
+            torch.as_tensor(ctx_x, dtype=torch.float32),
+            torch.as_tensor(ctx_m, dtype=torch.float32),
+            torch.as_tensor(fut_x, dtype=torch.float32),
+            torch.as_tensor(fut_m, dtype=torch.float32),
+        )
+
+
+class GapAnalyzer:
+    def __init__(self, config: GapConfig):
+        self.config = config
+        self.model = WorldModel(encoder_factory=self._build_encoder, config=config.world_model)
+        self.optimizer = torch.optim.AdamW(
+            list(self.model.context_encoder.parameters()) + list(self.model.predictor.parameters()),
+            lr=config.training.lr,
+            weight_decay=config.training.weight_decay,
+        )
+        self._fitted = False
+
+    def _build_encoder(self) -> torch.nn.Module:
+        if self.config.modality == "perception":
+            return LandmarkEncoder(input_dim=self.config.state_dim, config=self.config.encoder)
+        if self.config.modality == "actuation":
+            return ActuatorEncoder(input_dim=self.config.state_dim, config=self.config.encoder)
+        raise ValueError(f"unknown modality: {self.config.modality!r}")  # pragma: no cover — GapConfig already validates this
+
+    def fit(self, rollouts: list[Rollout]) -> dict:
+        torch.manual_seed(self.config.training.seed)
+        wm_cfg = self.config.world_model
+        dataset = _WindowDataset(rollouts, wm_cfg.context_frames, wm_cfg.predict_frames)
+        if len(dataset) == 0:
+            raise ValueError(
+                "no rollouts long enough for the configured context+predict window "
+                f"({wm_cfg.context_frames + wm_cfg.predict_frames} frames); "
+                f"{dataset.skipped} rollouts were too short and 0 were usable."
+            )
+        loader = DataLoader(
+            dataset, batch_size=min(self.config.training.batch_size, len(dataset)), shuffle=True
+        )
+
+        losses: list[float] = []
+        for _epoch in range(self.config.training.max_epochs):
+            for ctx_x, ctx_m, fut_x, fut_m in loader:
+                loss, diag = self.model(ctx_x, ctx_m, fut_x, fut_m)
+                self.optimizer.zero_grad()
+                loss.backward()
+                self.optimizer.step()
+                self.model.update_target_encoder()
+                self.model.collapse_safeguard.record(diag["latent_variance"])
+                losses.append(loss.item())
+
+        self._fitted = True
+        return {
+            "final_loss": losses[-1] if losses else float("nan"),
+            "n_steps": len(losses),
+            "n_skipped_rollouts": dataset.skipped,
+            "collapsed": self.model.collapse_safeguard.has_collapsed(),
+        }
+
+    def _rollouts_to_summary_latents(self, rollouts: list[Rollout]) -> np.ndarray:
+        self.model.eval()
+        summaries = []
+        with torch.no_grad():
+            for r in rollouts:
+                x = torch.as_tensor(r.states, dtype=torch.float32).unsqueeze(0)
+                m = torch.as_tensor(r.presence_mask, dtype=torch.float32).unsqueeze(0)
+                summary = self.model.encode_rollout_summary(x, m)
+                summaries.append(summary.squeeze(0).numpy())
+        return np.stack(summaries)
+
+    def compute_gap(
+        self, source_rollouts: list[Rollout], target_rollouts: list[Rollout]
+    ) -> GapResult:
+        if not self._fitted:
+            raise RuntimeError(
+                "call fit() before compute_gap() — otherwise the world model has "
+                "random, untrained weights and any gap number is meaningless"
+            )
+        source_latents = self._rollouts_to_summary_latents(source_rollouts)
+        target_latents = self._rollouts_to_summary_latents(target_rollouts)
+
+        fd = frechet_distance(source_latents, target_latents)
+        mmd = mmd_squared(source_latents, target_latents)
+
+        warnings: list[str] = []
+        if fd.confidence == "low":
+            warnings.append(
+                f"low sample-size confidence (n_source={fd.n_source}, n_target={fd.n_target}, "
+                f"latent_dim={fd.latent_dim}) — see spec Section 7.3"
+            )
+        return GapResult(frechet=fd, mmd=mmd, warnings=warnings)
+
+    # -- Persistence -----------------------------------------------------
+    #
+    # Spec 9.2's CLI splits `train` and `analyze` into separate commands, which
+    # only makes sense if a fitted GapAnalyzer can be written to disk by one
+    # process and reloaded by another. Neither the CLI example nor the rest of
+    # Section 9 spells out a checkpoint format, so this is a documented
+    # implementation decision, not a literal spec requirement: a single
+    # torch.save() of the model/optimizer state plus the GapConfig needed to
+    # reconstruct this object, since GapConfig (Pydantic) is picklable.
+
+    def save_checkpoint(self, path: str | Path) -> None:
+        """Writes model + optimizer state and the config to a single file."""
+        torch.save(
+            {
+                "model_state_dict": self.model.state_dict(),
+                "optimizer_state_dict": self.optimizer.state_dict(),
+                "config": self.config,
+                "fitted": self._fitted,
+            },
+            path,
+        )
+
+    @classmethod
+    def load_checkpoint(cls, path: str | Path) -> "GapAnalyzer":
+        """Reconstructs a GapAnalyzer from a checkpoint written by
+        `save_checkpoint`. Loads with `weights_only=False` since the
+        checkpoint intentionally carries a GapConfig object, not just
+        tensors — only load checkpoints you trust, same as any pickle-backed
+        format.
+        """
+        checkpoint = torch.load(path, weights_only=False, map_location="cpu")
+        analyzer = cls(checkpoint["config"])
+        analyzer.model.load_state_dict(checkpoint["model_state_dict"])
+        analyzer.optimizer.load_state_dict(checkpoint["optimizer_state_dict"])
+        analyzer._fitted = checkpoint["fitted"]
+        return analyzer

worldgap/cli.py

@@ -0,0 +1,268 @@
+"""CLI entry point, per TECHNICAL_SPEC.md Section 9.2.
+
+    worldgap train    --modality perception --data-dir ./data/processed --config ...
+    worldgap analyze  --source ... --target ... --modality ... --output report.html
+    worldgap validate --gap-scores results.csv --ground-truth degradation.csv
+
+v0.2 status: all three subcommands are wired end-to-end against local rollout
+stores (see `_load_rollout_store` below) -- no network/Kaggle/GPU access is
+needed to run this against your own .npz + index.db data. What's still out of
+scope here: producing that data in the first place from HaGRID/EgoHands raw
+frames (blocked on MediaPipe + real downloads, see data/loaders/hagrid.py).
+
+**Documented decision** (spec 5.3's diagram shows one repo-wide `data/`
+root with a single `index.db` shared across both modalities' `processed/`
+subdirectories). This CLI instead treats each of `--data-dir`/`--source`/
+`--target` as an independent, self-contained rollout store:
+
+    {dir}/
+      index.db
+      perception/{rollout_id}.npz
+      actuation/{rollout_id}.npz
+
+This is what lets `analyze` compare two independently-produced stores (e.g.
+one directory for "clean" rollouts, another for "perturbed" ones) without
+requiring them to share one index -- the shared-index diagram in 5.3 remains
+the right layout for the primary download+preprocess script's own output, but
+`--source`/`--target` need to be comparable regardless of where each came
+from. The spec's inline CLI example (`--data-dir ./data/processed/perception`)
+has been corrected in docs/TECHNICAL_SPEC.md to `--data-dir ./data/processed`
+to match: `--data-dir` is the store root, not a modality-specific subdirectory
+(modality is still selected via `--modality`, filtering within that store).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .analyzer import GapAnalyzer
+from .config import GapConfig
+from .data.index import RolloutIndex
+from .report import ReportEntry, generate_report
+from .validation.harness import ConditionResult, ValidationHarness
+
+
+def _condition_key(condition: dict) -> tuple:
+    return tuple(sorted(condition.items()))
+
+
+def _load_rollout_store(store_dir: Path, modality: str, index_db: Path | None) -> list:
+    """Loads every rollout for `modality` out of a self-contained store
+    directory (see module docstring). Fails with an actionable message rather
+    than a bare empty list or a raw sqlite/OS error -- an empty rollout store
+    is almost always a setup mistake, not a valid input.
+    """
+    db_path = index_db if index_db is not None else store_dir / "index.db"
+    if not db_path.exists():
+        raise FileNotFoundError(
+            f"no index.db found at {db_path} -- a rollout store needs both "
+            f"'{{store}}/index.db' and '{{store}}/{{modality}}/*.npz' "
+            "(save rollouts with Rollout.save() + RolloutIndex.add(), see "
+            "tests/test_index.py for the exact pattern)"
+        )
+    with RolloutIndex(db_path) as index:
+        rollouts = index.load_all(store_dir, modality=modality)
+    if not rollouts:
+        raise ValueError(
+            f"index at {db_path} has no rollouts for modality={modality!r} -- "
+            "double check --modality matches what was indexed, and that this "
+            "isn't an empty/placeholder store"
+        )
+    return rollouts
+
+
+def _load_config(config_path: str | None, modality: str) -> GapConfig:
+    if config_path is None:
+        return GapConfig(modality=modality)
+    return GapConfig.from_yaml(config_path, modality=modality)
+
+
+def _default_checkpoint_path(data_dir: Path, modality: str) -> Path:
+    return data_dir / f"checkpoint_{modality}.pt"
+
+
+def _cmd_train(args: argparse.Namespace) -> int:
+    config = _load_config(args.config, args.modality)
+    rollouts = _load_rollout_store(args.data_dir, args.modality, args.index_db)
+    print(f"[worldgap train] loaded {len(rollouts)} {args.modality} rollouts from {args.data_dir}", file=sys.stderr)
+
+    analyzer = GapAnalyzer(config)
+    fit_report = analyzer.fit(rollouts)
+
+    checkpoint_path = args.checkpoint or _default_checkpoint_path(args.data_dir, args.modality)
+    analyzer.save_checkpoint(checkpoint_path)
+
+    print(
+        f"[worldgap train] done: final_loss={fit_report['final_loss']:.4f} "
+        f"n_steps={fit_report['n_steps']} n_skipped_rollouts={fit_report['n_skipped_rollouts']} "
+        f"checkpoint={checkpoint_path}",
+        file=sys.stderr,
+    )
+    if fit_report["collapsed"]:
+        print(
+            "[worldgap train] WARNING: collapse safeguard flagged sustained low latent "
+            "variance during training (spec 6.3/12.7) -- gap scores from this checkpoint "
+            "are likely meaningless (a collapsed encoder maps everything to ~the same "
+            "point, which trivially minimizes distance regardless of real domain gap). "
+            "Do not trust downstream results without addressing this first.",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+def _cmd_analyze(args: argparse.Namespace) -> int:
+    source_rollouts = _load_rollout_store(args.source, args.modality, args.source_index_db)
+    target_rollouts = _load_rollout_store(args.target, args.modality, args.target_index_db)
+    print(
+        f"[worldgap analyze] source={len(source_rollouts)} rollouts from {args.source}, "
+        f"target={len(target_rollouts)} rollouts from {args.target}",
+        file=sys.stderr,
+    )
+
+    if args.checkpoint is not None:
+        print(f"[worldgap analyze] loading trained model from {args.checkpoint}", file=sys.stderr)
+        analyzer = GapAnalyzer.load_checkpoint(args.checkpoint)
+    else:
+        print(
+            "[worldgap analyze] NOTE: no --checkpoint given -- fitting a fresh world model "
+            "on source+target combined as self-supervised pretraining (a documented fallback, "
+            "not a spec requirement: the CLI's own usage example doesn't show an explicit "
+            "checkpoint flag for `analyze`). Pass --checkpoint from a prior `worldgap train` "
+            "run for a properly-trained model instead.",
+            file=sys.stderr,
+        )
+        config = _load_config(args.config, args.modality)
+        analyzer = GapAnalyzer(config)
+        analyzer.fit(source_rollouts + target_rollouts)
+
+    result = analyzer.compute_gap(source_rollouts, target_rollouts)
+    for w in result.warnings:
+        print(f"[worldgap analyze] WARNING: {w}", file=sys.stderr)
+
+    entry = ReportEntry(condition_label=f"{args.source.name}_vs_{args.target.name}", result=result)
+    out_path = generate_report([entry], args.output)
+    print(
+        f"[worldgap analyze] frechet={result.frechet.distance:.4f} mmd={result.mmd.mmd_squared:.4f} "
+        f"confidence={result.confidence} report={out_path}",
+        file=sys.stderr,
+    )
+    return 0
+
+
+def _load_condition_value_csv(path: Path, value_col: str) -> tuple[list[tuple[dict, float]], list[str]]:
+    import pandas as pd
+
+    df = pd.read_csv(path)
+    if value_col not in df.columns:
+        raise ValueError(f"{path}: missing required column {value_col!r} (found {list(df.columns)})")
+    condition_cols = [c for c in df.columns if c != value_col]
+    if not condition_cols:
+        raise ValueError(f"{path}: no condition columns found besides {value_col!r}")
+    rows = [
+        ({c: row[c] for c in condition_cols}, float(row[value_col])) for _, row in df.iterrows()
+    ]
+    return rows, condition_cols
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    gap_rows, gap_cond_cols = _load_condition_value_csv(args.gap_scores, "gap_score")
+    truth_rows, truth_cond_cols = _load_condition_value_csv(args.ground_truth, "ground_truth_degradation")
+
+    if set(gap_cond_cols) != set(truth_cond_cols):
+        raise ValueError(
+            f"condition columns don't match between {args.gap_scores} ({gap_cond_cols}) and "
+            f"{args.ground_truth} ({truth_cond_cols}) -- both files must key on the same "
+            "condition columns to be joined"
+        )
+
+    print(
+        "[worldgap validate] NOTE: this command validates that gap-scores and ground-truth "
+        "cover the same condition set; it treats the gap-scores file's conditions as the "
+        "registered set. The actual anti-cherry-picking discipline spec 8.3 requires -- "
+        "deciding the condition list BEFORE running experiments -- has to happen upstream, "
+        "at data-collection time; this CLI can't retroactively enforce that.",
+        file=sys.stderr,
+    )
+
+    truth_by_key = {_condition_key(c): v for c, v in truth_rows}
+    conditions = [c for c, _ in gap_rows]
+
+    harness = ValidationHarness(min_conditions=args.min_conditions)
+    harness.pre_register_conditions(conditions)
+
+    condition_results = []
+    missing = []
+    for condition, gap_score in gap_rows:
+        key = _condition_key(condition)
+        if key not in truth_by_key:
+            missing.append(condition)
+            continue
+        condition_results.append(
+            ConditionResult(condition=condition, gap_score=gap_score, ground_truth_degradation=truth_by_key[key])
+        )
+    if missing:
+        raise ValueError(
+            f"{len(missing)} condition(s) in {args.gap_scores} have no matching row in "
+            f"{args.ground_truth}: {missing[:5]}{'...' if len(missing) > 5 else ''}"
+        )
+
+    report = harness.run(condition_results)
+    s = report.spearman
+    print(
+        f"[worldgap validate] Spearman rho={s.rho:.3f} "
+        f"(95% CI [{s.ci_low:.3f}, {s.ci_high:.3f}], n_bootstrap={s.n_bootstrap}) "
+        f"across n_conditions={report.n_conditions}",
+        file=sys.stderr,
+    )
+    if s.ci_low <= 0.0 <= s.ci_high:
+        print(
+            "[worldgap validate] NOTE: the confidence interval includes zero -- this is a "
+            "legitimate, reportable outcome per spec Section 16 ('validation correlation may "
+            "simply be weak'), not a failure to hide.",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="worldgap")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    train_p = subparsers.add_parser("train", help="Train the world model on a set of rollouts")
+    train_p.add_argument("--modality", required=True, choices=["perception", "actuation"])
+    train_p.add_argument("--data-dir", required=True, type=Path)
+    train_p.add_argument("--config", default=None)
+    train_p.add_argument("--index-db", type=Path, default=None, help="Default: <data-dir>/index.db")
+    train_p.add_argument("--checkpoint", type=Path, default=None, help="Default: <data-dir>/checkpoint_<modality>.pt")
+    train_p.set_defaults(func=_cmd_train)
+
+    analyze_p = subparsers.add_parser("analyze", help="Compute a gap score between two rollout sets")
+    analyze_p.add_argument("--source", required=True, type=Path)
+    analyze_p.add_argument("--target", required=True, type=Path)
+    analyze_p.add_argument("--modality", required=True, choices=["perception", "actuation"])
+    analyze_p.add_argument("--output", default="report.html")
+    analyze_p.add_argument("--checkpoint", type=Path, default=None, help="From a prior `worldgap train` run")
+    analyze_p.add_argument("--config", default=None, help="Only used if --checkpoint is omitted")
+    analyze_p.add_argument("--source-index-db", type=Path, default=None, help="Default: <source>/index.db")
+    analyze_p.add_argument("--target-index-db", type=Path, default=None, help="Default: <target>/index.db")
+    analyze_p.set_defaults(func=_cmd_analyze)
+
+    validate_p = subparsers.add_parser("validate", help="Run the validation harness")
+    validate_p.add_argument("--gap-scores", required=True, type=Path)
+    validate_p.add_argument("--ground-truth", required=True, type=Path)
+    validate_p.add_argument("--min-conditions", type=int, default=10)
+    validate_p.set_defaults(func=_cmd_validate)
+
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (FileNotFoundError, ValueError, RuntimeError, KeyError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

worldgap/config.py

@@ -0,0 +1,100 @@
+"""Configuration schemas for WorldGap, per TECHNICAL_SPEC.md Section 6/9.
+
+All experiment configuration MUST go through these Pydantic models rather than
+loose dicts or CLI-only flags, so that a config file is a complete, versioned
+record of exactly what produced a given result (spec Section 12.18,
+reproducibility requirements).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, Field, model_validator
+
+Modality = Literal["perception", "actuation"]
+
+
+class EncoderConfig(BaseModel):
+    """Per spec 6.1 / 6.2. Defaults are starting points to validate empirically,
+    not fixed requirements (spec explicitly flags hidden-dim/layer counts as tunable).
+    """
+
+    d_model: int = 256
+    n_layers: int = 4
+    n_heads: int = 4
+    dim_feedforward: int = 1024
+    dropout: float = 0.1
+
+    @model_validator(mode="after")
+    def _check_heads_divide_dmodel(self) -> "EncoderConfig":
+        if self.d_model % self.n_heads != 0:
+            raise ValueError(
+                f"d_model ({self.d_model}) must be divisible by n_heads ({self.n_heads})"
+            )
+        return self
+
+
+class WorldModelConfig(BaseModel):
+    """Per spec 6.3. The JEPA-style core: context encoder + EMA target encoder + predictor."""
+
+    context_frames: int = 16
+    predict_frames: int = 8
+    ema_decay: float = 0.996
+    summary_dim: int = 64  # MUST stay small — see spec 7.3, sample-size-vs-dim tradeoff
+    collapse_variance_threshold: float = 1e-4
+    collapse_patience_checks: int = 3
+
+
+class TrainingConfig(BaseModel):
+    """Per spec 6.4."""
+
+    lr: float = 3e-4
+    weight_decay: float = 0.01
+    batch_size: int = 64
+    max_epochs: int = 100
+    seed: int = 0
+
+
+class GapConfig(BaseModel):
+    """Top-level config passed to GapAnalyzer. One of these fully specifies a run."""
+
+    modality: Modality
+    state_dim: int = Field(
+        default=258,
+        description=(
+            "Per-frame feature dimension. 258 for perception (33*4 pose + 21*3 + 21*3 hands, "
+            "spec 5.1.1). Set explicitly for actuation — depends on DOF count modeled."
+        ),
+    )
+    encoder: EncoderConfig = Field(default_factory=EncoderConfig)
+    world_model: WorldModelConfig = Field(default_factory=WorldModelConfig)
+    training: TrainingConfig = Field(default_factory=TrainingConfig)
+
+    @model_validator(mode="after")
+    def _check_actuation_dim(self) -> "GapConfig":
+        if self.modality == "actuation" and self.state_dim == 258:
+            raise ValueError(
+                "state_dim=258 is the perception default; set an explicit state_dim "
+                "for actuation (spec 5.1.1: 2-6 depending on DOF count modeled)."
+            )
+        return self
+
+    @classmethod
+    def from_yaml(cls, path: str | Path, modality: Modality) -> "GapConfig":
+        """Loads a config file like configs/v1_default.yaml, per spec 9.2's
+        `worldgap train --config configs/v1_default.yaml`. `modality` MUST come
+        from the CLI's `--modality` flag, not the file, per configs/v1_default.yaml's
+        own header comment -- one config file is meant to be reusable regardless
+        of which modality it's paired with at invocation time.
+        """
+        with open(path) as f:
+            raw = yaml.safe_load(f) or {}
+        if "modality" in raw:
+            raise ValueError(
+                f"{path}: 'modality' MUST be set via the --modality CLI flag, not "
+                "in the config file (spec 9.2) -- remove it from the YAML."
+            )
+        return cls(modality=modality, **raw)