ayna 0.1.0__py3-none-any.whl

ayna/__init__.py

@@ -0,0 +1,28 @@
+"""ayna -- know whether your inferred dynamics are real, before you interpret them.
+
+ayna checks the outputs of a fitted data-driven dynamics model (LFADS, a
+sequential autoencoder, a neural ODE, ...) for the three failure modes defined
+in the Computation-through-Dynamics Toolkit: underfitting, feature invention
+and dynamical misattribution. It runs on numpy, never trains anything, and
+says what it could not check.
+"""
+
+__version__ = "0.1.0"
+
+from .bundle import Bundle, BundleError, load_bundle  # noqa: E402
+from .report import Check, Finding, Report  # noqa: E402
+from .scan import Thresholds, scan  # noqa: E402
+from .select import select  # noqa: E402
+
+__all__ = [
+    "Bundle",
+    "BundleError",
+    "Check",
+    "Finding",
+    "Report",
+    "Thresholds",
+    "load_bundle",
+    "scan",
+    "select",
+    "__version__",
+]

ayna/adapters/__init__.py

@@ -0,0 +1 @@
+"""Exporters from training frameworks to ayna bundles. Imported lazily."""

ayna/adapters/ctd.py

@@ -0,0 +1,138 @@
+"""Export a Computation-through-Dynamics Toolkit run to an ayna bundle.
+
+Run this inside the CtD environment (torch, Lightning, ...). ayna itself never
+imports torch; this module only touches CtD objects through the getters the
+toolkit's own ``Comparison.compute_metrics`` uses, so it duck-types and can
+be tested without CtD installed.
+
+Assumptions, all taken from CtD's own comparison code:
+
+* ``get_model_outputs(phase)`` returns ``(rates, latents)``, rates in spikes/bin;
+* ``get_spiking(phase)`` returns all neurons, held-in first, held-out last;
+* the held-in count is the width of the spiking the model receives,
+  ``get_model_inputs(phase)[0]``;
+* the task-trained analysis returns trials in the same order as the
+  data-trained one for each phase.
+
+Status: written against CtD 1.0.2 source; not yet run on a live CtD install
+(the pretrained models are Git-LFS objects). Please report mismatches.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+from ..bundle import Bundle
+
+PHASES = ("train", "val")
+
+
+def _np(x):
+    if x is None:
+        return None
+    if hasattr(x, "detach"):
+        x = x.detach().cpu().numpy()
+    return np.asarray(x)
+
+
+def _get(obj, method, phase):
+    fn = getattr(obj, method, None)
+    if fn is None:
+        return None
+    try:
+        return _np(fn(phase=phase))
+    except (NotImplementedError, AttributeError, TypeError):
+        return None
+
+
+def from_ctd(dd, tt=None, name: Optional[str] = None, inputs_kind: Optional[str] = None,
+             model_type: Optional[str] = None) -> Bundle:
+    """Build a :class:`~ayna.bundle.Bundle` from CtD analysis objects.
+
+    ``dd`` is an ``Analysis_DD`` (SAE or LFADS); ``tt`` an optional
+    ``Analysis_TT`` supplying ground-truth latents and inputs.
+    """
+    model_type = model_type or getattr(dd, "model_type", "")
+    parts = {k: [] for k in ("spikes", "rates", "latents", "inputs", "true_rates",
+                             "true_latents", "true_inputs", "trial_lens")}
+    n_heldin = None
+    n_val = 0
+    if inputs_kind is None:
+        inputs_kind = "inferred" if model_type == "LFADS" and hasattr(dd, "get_inferred_inputs") else "supplied"
+
+    for phase in PHASES:
+        rates, latents = dd.get_model_outputs(phase=phase)
+        rates, latents = _np(rates), _np(latents)
+        spikes = _get(dd, "get_spiking", phase)
+        model_in = dd.get_model_inputs(phase=phase)
+        heldin_spikes, supplied = _np(model_in[0]), _np(model_in[1])
+        n_heldin = heldin_spikes.shape[-1]
+        if inputs_kind == "inferred":
+            inputs = _get(dd, "get_inferred_inputs", phase)
+        else:
+            inputs = supplied
+        parts["spikes"].append(spikes)
+        parts["rates"].append(rates)
+        parts["latents"].append(latents)
+        parts["inputs"].append(inputs)
+        parts["true_rates"].append(_get(dd, "get_true_rates", phase))
+        lens = _get(dd, "get_trial_lens", phase)
+        parts["trial_lens"].append(None if lens is None else lens.reshape(-1).astype(int))
+        if tt is not None:
+            parts["true_latents"].append(_get(tt, "get_latents", phase))
+            parts["true_inputs"].append(_get(tt, "get_inputs", phase))
+        if phase == "val":
+            n_val = rates.shape[0]
+
+    def cat(key):
+        items = parts[key]
+        if not items or any(i is None for i in items):
+            return None
+        return np.concatenate(items, axis=0)
+
+    spikes = cat("spikes")
+    N = spikes.shape[-1]
+    heldout = np.arange(N) >= n_heldin if n_heldin is not None and n_heldin < N else None
+    R = spikes.shape[0]
+    val = np.zeros(R, bool)
+    val[R - n_val:] = True
+    trial_lens = cat("trial_lens")
+    if trial_lens is not None and np.all(trial_lens >= spikes.shape[1]):
+        trial_lens = None
+    inputs = cat("inputs")
+    meta = {
+        "name": name or getattr(dd, "run_name", "ctd_run"),
+        "model": model_type or "unknown",
+        "source": "ctd",
+        "exporter": "ayna.adapters.ctd",
+    }
+    if inputs is not None:
+        meta["inputs_kind"] = inputs_kind
+    if tt is not None:
+        meta["tt_run"] = getattr(tt, "run_name", "")
+    return Bundle(spikes=spikes, rates=cat("rates"), latents=cat("latents"), heldout=heldout, val=val,
+                  trial_lens=trial_lens, inputs=inputs, true_rates=cat("true_rates"),
+                  true_latents=cat("true_latents"), true_inputs=cat("true_inputs"), meta=meta)
+
+
+def export_run(dd_dir: str, out_path: str, model_type: str, tt_dir: Optional[str] = None,
+               inputs_kind: Optional[str] = None) -> str:
+    """Load a saved CtD run from disk (needs CtD importable) and write a bundle."""
+    try:
+        from ctd.comparison.analysis.dd.dd import Analysis_DD
+        from ctd.comparison.analysis.tt.tt import Analysis_TT
+    except ImportError as exc:  # pragma: no cover - depends on the user's env
+        raise ImportError(
+            "export-ctd must run in an environment where the Computation-through-Dynamics "
+            "Toolkit is installed (`pip install -e .` in its repository)."
+        ) from exc
+    dd_dir = dd_dir.rstrip("/") + "/"
+    dd = Analysis_DD.create(run_name=dd_dir.rstrip("/").split("/")[-1], filepath=dd_dir, model_type=model_type)
+    tt = None
+    if tt_dir:
+        tt_dir = tt_dir.rstrip("/") + "/"
+        tt = Analysis_TT(run_name=tt_dir.rstrip("/").split("/")[-1], filepath=tt_dir)
+    bundle = from_ctd(dd, tt, inputs_kind=inputs_kind, model_type=model_type)
+    return str(bundle.save(out_path))

ayna/bundle.py

@@ -0,0 +1,249 @@
+"""The ayna bundle: everything a fitted dynamics model produced, as plain arrays.
+
+A bundle is one ``.npz`` file. ayna never imports the framework that trained
+the model; whoever trained it exports these arrays once, and every check runs
+on numpy from there.
+
+Shapes use R trials, T time bins, N neurons, D inferred latent dimensions and
+U input dimensions. Rates are expected counts **per bin**, the same unit as
+the spikes.
+
+Required
+    spikes        (R, T, N)  observed spike counts
+    rates         (R, T, N)  model-predicted rates (held-in and held-out neurons)
+    latents       (R, T, D)  model-inferred latent states
+
+Optional
+    heldout       (N,)  bool  neurons the model never saw as input (enables co-BPS)
+    val           (R,)  bool  validation trials (default: the last 20%)
+    trial_lens    (R,)  int   valid bins per trial, for padded data
+    inputs        (R, T, U)   external inputs; ``meta["inputs_kind"]`` says
+                              whether they were ``supplied`` to the model or
+                              ``inferred`` by it
+    true_latents  (R, T, Dt)  ground truth (synthetic data only) -- tier 2
+    true_rates    (R, T, N)
+    true_inputs   (R, T, Ut)
+    meta          JSON string: name, model, bin_ms, inputs_kind, labels, ...
+
+A ``dynamics`` callable ``f(z, u) -> z_next`` (arrays ``(M, D)``, ``(M, U)``)
+can be attached in Python; it cannot be stored in an ``.npz`` and unlocks the
+tier-1 probes.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+import numpy as np
+
+ARRAY_KEYS = (
+    "spikes",
+    "rates",
+    "latents",
+    "heldout",
+    "val",
+    "trial_lens",
+    "inputs",
+    "true_latents",
+    "true_rates",
+    "true_inputs",
+)
+
+RATE_FLOOR = 1e-9
+
+
+class BundleError(ValueError):
+    """The bundle cannot be checked as given."""
+
+
+@dataclass
+class Bundle:
+    spikes: np.ndarray
+    rates: np.ndarray
+    latents: np.ndarray
+    heldout: Optional[np.ndarray] = None
+    val: Optional[np.ndarray] = None
+    trial_lens: Optional[np.ndarray] = None
+    inputs: Optional[np.ndarray] = None
+    true_latents: Optional[np.ndarray] = None
+    true_rates: Optional[np.ndarray] = None
+    true_inputs: Optional[np.ndarray] = None
+    meta: dict = field(default_factory=dict)
+    dynamics: Optional[Callable[[np.ndarray, np.ndarray], np.ndarray]] = None
+    source: str = ""
+    notes: list = field(default_factory=list)
+
+    def __post_init__(self):
+        for key in ARRAY_KEYS:
+            value = getattr(self, key)
+            if value is not None:
+                setattr(self, key, np.asarray(value))
+        self._validate()
+
+    # ------------------------------------------------------------------ shape
+    @property
+    def n_trials(self) -> int:
+        return self.spikes.shape[0]
+
+    @property
+    def n_bins(self) -> int:
+        return self.spikes.shape[1]
+
+    @property
+    def n_neurons(self) -> int:
+        return self.spikes.shape[2]
+
+    @property
+    def n_latents(self) -> int:
+        return self.latents.shape[2]
+
+    @property
+    def inputs_kind(self) -> Optional[str]:
+        if self.inputs is None:
+            return None
+        return self.meta.get("inputs_kind", "inferred")
+
+    @property
+    def has_ground_truth(self) -> bool:
+        return self.true_latents is not None or self.true_rates is not None
+
+    @property
+    def name(self) -> str:
+        return self.meta.get("name") or Path(self.source).stem or "bundle"
+
+    # ------------------------------------------------------------- validation
+    def _validate(self):
+        for key in ("spikes", "rates", "latents"):
+            arr = getattr(self, key)
+            if arr is None:
+                raise BundleError(f"'{key}' is required")
+            if arr.ndim != 3:
+                raise BundleError(
+                    f"'{key}' must be (trials, bins, features); got shape {arr.shape}"
+                )
+        R, T, N = self.spikes.shape
+        if self.rates.shape != (R, T, N):
+            raise BundleError(
+                f"'rates' must match 'spikes' {self.spikes.shape}; got {self.rates.shape}"
+            )
+        for key in ("latents", "inputs", "true_latents", "true_inputs"):
+            arr = getattr(self, key)
+            if arr is None:
+                continue
+            if arr.ndim != 3 or arr.shape[:2] != (R, T):
+                raise BundleError(
+                    f"'{key}' must be ({R}, {T}, features); got {arr.shape}"
+                )
+        if self.true_rates is not None and self.true_rates.shape != (R, T, N):
+            raise BundleError(f"'true_rates' must be {(R, T, N)}; got {self.true_rates.shape}")
+
+        if np.any(self.spikes < 0):
+            raise BundleError("'spikes' contains negative counts")
+        if not np.all(np.isfinite(self.rates)):
+            raise BundleError("'rates' contains NaN or inf")
+        if np.any(self.rates <= 0):
+            n_bad = int(np.sum(self.rates <= 0))
+            self.rates = np.maximum(self.rates, RATE_FLOOR)
+            self.notes.append(
+                f"{n_bad} non-positive predicted rates were floored at {RATE_FLOOR:g}"
+            )
+        if not np.all(np.isfinite(self.latents)):
+            raise BundleError("'latents' contains NaN or inf")
+
+        if self.heldout is not None:
+            self.heldout = self.heldout.astype(bool).reshape(-1)
+            if self.heldout.shape != (N,):
+                raise BundleError(f"'heldout' must have {N} entries")
+            if self.heldout.all():
+                raise BundleError("every neuron is marked held-out")
+        if self.val is None:
+            n_val = max(1, int(round(0.2 * R)))
+            self.val = np.zeros(R, bool)
+            self.val[R - n_val:] = True
+            self.notes.append(f"no 'val' split given; used the last {n_val} of {R} trials")
+        else:
+            self.val = self.val.astype(bool).reshape(-1)
+            if self.val.shape != (R,):
+                raise BundleError(f"'val' must have {R} entries")
+        if self.val.all() or not self.val.any():
+            raise BundleError("'val' must mark some, but not all, trials")
+        if self.trial_lens is not None:
+            self.trial_lens = self.trial_lens.astype(int).reshape(-1)
+            if self.trial_lens.shape != (R,) or self.trial_lens.max() > T or self.trial_lens.min() < 1:
+                raise BundleError("'trial_lens' must be R integers in [1, T]")
+        kind = self.meta.get("inputs_kind")
+        if kind is not None and kind not in ("supplied", "inferred"):
+            raise BundleError("meta['inputs_kind'] must be 'supplied' or 'inferred'")
+
+    # ------------------------------------------------------------- selection
+    def trials(self, split: str) -> np.ndarray:
+        if split == "train":
+            return ~self.val
+        if split == "val":
+            return self.val.copy()
+        if split == "all":
+            return np.ones(self.n_trials, bool)
+        raise ValueError(split)
+
+    def bin_mask(self, split: str = "all") -> np.ndarray:
+        """(R, T) boolean mask of valid bins in the chosen trials."""
+        mask = np.zeros((self.n_trials, self.n_bins), bool)
+        mask[self.trials(split)] = True
+        if self.trial_lens is not None:
+            mask &= np.arange(self.n_bins)[None, :] < self.trial_lens[:, None]
+        return mask
+
+    def flat(self, key_or_array, split: str = "all", neurons=None) -> np.ndarray:
+        """Flatten (R, T, F) to (samples, F) over valid bins of a split."""
+        arr = getattr(self, key_or_array) if isinstance(key_or_array, str) else key_or_array
+        if arr is None:
+            return None
+        arr = arr[self.bin_mask(split)]
+        if neurons is not None:
+            arr = arr[:, neurons]
+        return arr
+
+    @property
+    def heldin(self) -> Optional[np.ndarray]:
+        return None if self.heldout is None else ~self.heldout
+
+    # ------------------------------------------------------------------- I/O
+    def save(self, path) -> Path:
+        path = Path(path)
+        payload = {k: getattr(self, k) for k in ARRAY_KEYS if getattr(self, k) is not None}
+        payload["meta"] = np.array(json.dumps(self.meta, sort_keys=True))
+        path.parent.mkdir(parents=True, exist_ok=True)
+        np.savez_compressed(path, **payload)
+        return path if path.suffix == ".npz" else path.with_suffix(path.suffix + ".npz")
+
+    def summary(self) -> str:
+        parts = [
+            f"{self.n_trials} trials x {self.n_bins} bins",
+            f"{self.n_neurons} neurons"
+            + (f" ({int(self.heldout.sum())} held-out)" if self.heldout is not None else ""),
+            f"{self.n_latents} latents",
+        ]
+        if self.inputs is not None:
+            parts.append(f"{self.inputs.shape[2]} {self.inputs_kind} inputs")
+        if self.has_ground_truth:
+            parts.append("ground truth")
+        if self.dynamics is not None:
+            parts.append("dynamics callable")
+        return ", ".join(parts)
+
+
+def load_bundle(path, dynamics=None) -> Bundle:
+    """Read a bundle written by :meth:`Bundle.save` or by any exporter."""
+    path = Path(path)
+    if not path.exists():
+        raise BundleError(f"no such file: {path}")
+    with np.load(path, allow_pickle=False) as data:
+        arrays = {k: data[k] for k in ARRAY_KEYS if k in data.files}
+        meta = json.loads(str(data["meta"])) if "meta" in data.files else {}
+    missing = [k for k in ("spikes", "rates", "latents") if k not in arrays]
+    if missing:
+        raise BundleError(f"{path.name} lacks required array(s): {', '.join(missing)}")
+    return Bundle(**arrays, meta=meta, dynamics=dynamics, source=str(path))

ayna/cli.py

@@ -0,0 +1,251 @@
+"""ayna command line.
+
+    ayna synth NAME [--faults underfit=0.5 feature_invention ...] [--sweep]
+    ayna scan BUNDLE [--out DIR] [--json] [--set name=value ...] [--daftar]
+    ayna select BUNDLE... | DIR [--out DIR] [--plot]
+    ayna validate [DIR] [--n 6] [--out DIR]
+    ayna info BUNDLE
+    ayna export-ctd DD_RUN_DIR OUT.npz --model-type SAE|LFADS [--tt TT_RUN_DIR]
+    ayna doctor
+
+``scan`` exits 1 when an error-level finding is raised from the model's
+outputs, so it can gate a pipeline or CI job.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def _bundles_from(paths):
+    from .bundle import load_bundle
+
+    files = []
+    for p in paths:
+        p = Path(p)
+        files += sorted(p.glob("*.npz")) if p.is_dir() else [p]
+    if not files:
+        raise SystemExit("no .npz bundles found")
+    return [load_bundle(f) for f in files]
+
+
+def _overrides(items):
+    out = {}
+    for item in items or []:
+        key, sep, value = item.partition("=")
+        if not sep:
+            raise SystemExit(f"--set expects name=value, got '{item}'")
+        out[key.strip()] = value
+    return out
+
+
+def cmd_synth(args):
+    from .synth import synth, synth_sweep
+
+    out = Path(args.out)
+    if args.sweep:
+        target = out / args.name
+        bundles = synth_sweep(n_trials=args.trials, n_neurons=args.neurons, truth_seed=args.seed)
+        for b in bundles:
+            b.save(target / f"{b.name}.npz")
+        print(f"wrote {len(bundles)} bundles (latent sizes 2-64, simulated) to {target}/")
+        return 0
+    b = synth(args.name, args.faults, latent_dim=args.latent_dim,
+              inputs_kind=None if args.inputs == "auto" else args.inputs,
+              n_trials=args.trials, n_neurons=args.neurons, seed=args.seed)
+    path = b.save(out / f"{args.name}.npz")
+    faults = b.meta["synth"]["faults"] or "none"
+    print(f"wrote {path}  ({b.summary()}; injected faults: {faults})")
+    print("note: a .npz cannot hold the dynamics callable, so tier-1 probes need the Python API")
+    return 0
+
+
+def cmd_scan(args):
+    from .bundle import load_bundle
+    from .scan import Thresholds, scan
+    from . import provenance
+
+    b = load_bundle(args.bundle)
+    th = Thresholds().update(_overrides(args.set))
+    if args.daftar and not provenance.available():
+        print("daftar is not installed; run `pip install \"ayna[provenance]\"`", file=sys.stderr)
+    with provenance.tracked("ayna scan", params={"bundle": str(args.bundle), **th.__dict__},
+                            inputs=[args.bundle] if args.daftar else []) if args.daftar else _null() as run:
+        report = scan(b, th, nonlinear_fallback=not args.no_nonlinear)
+        if args.out:
+            report.save(args.out)
+        if run is not None:
+            provenance.log_report(run, report, args.out)
+    if args.json:
+        from .report import _jsonable
+
+        print(json.dumps(report.to_dict(), indent=2, default=_jsonable))
+    else:
+        print(report.render_text(), end="")
+        if args.out:
+            print(f"\nreport written to {args.out}/report.{{txt,md,json}}")
+    return 1 if report.has_errors else 0
+
+
+class _null:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, *exc):
+        return False
+
+
+def cmd_select(args):
+    from .select import select
+
+    rep = select(_bundles_from(args.bundles))
+    print(rep.render_text(), end="")
+    if args.out:
+        rep.save(args.out)
+        if args.plot:
+            try:
+                rep.plot(Path(args.out) / "select.png")
+            except ImportError:
+                print("plot needs matplotlib: pip install \"ayna[plot]\"", file=sys.stderr)
+        print(f"\nwritten to {args.out}/")
+    return 0
+
+
+def cmd_validate(args):
+    from .scan import Thresholds
+    from .validate import validate_bundles, validate_synthetic
+
+    th = Thresholds().update(_overrides(args.set))
+
+    def progress(i, n, name):
+        print(f"\r  [{i}/{n}] {name:<40}", end="", file=sys.stderr, flush=True)
+
+    if args.bundles:
+        val = validate_bundles(_bundles_from(args.bundles), th, progress)
+        if not val.cases:
+            raise SystemExit("none of these bundles carries ground truth; nothing to validate against")
+    else:
+        val = validate_synthetic(args.n, args.seed, th, progress)
+    print("\r" + " " * 60 + "\r", end="", file=sys.stderr)
+    print(val.render_text(), end="")
+    if not args.bundles:
+        print("\ncaveat: these faults were injected by ayna's own simulator, so this measures whether the "
+              "detectors work as designed -- not whether they transfer to trained models or recordings.")
+    if args.out:
+        val.save(args.out)
+    return 0
+
+
+def cmd_info(args):
+    from .bundle import load_bundle
+
+    b = load_bundle(args.bundle)
+    print(f"{args.bundle}: {b.summary()}")
+    for k, v in sorted(b.meta.items()):
+        print(f"  {k}: {v}")
+    for n in b.notes:
+        print(f"  note: {n}")
+    return 0
+
+
+def cmd_export_ctd(args):
+    from .adapters.ctd import export_run
+
+    path = export_run(args.dd_dir, args.out, args.model_type, args.tt, args.inputs)
+    print(f"wrote {path}")
+    return 0
+
+
+def cmd_doctor(args):
+    import platform
+
+    print(f"ayna {__version__} on Python {platform.python_version()}")
+    for mod, why in (("numpy", "core"), ("scipy", "core"), ("sklearn", "core"),
+                     ("matplotlib", "extra [plot]: select --plot"),
+                     ("daftar", "extra [provenance]: scan --daftar"),
+                     ("ctd", "export-ctd (install the CtD repository itself)"),
+                     ("torch", "needed by CtD, never by ayna")):
+        try:
+            m = __import__(mod)
+            print(f"  ok       {mod:<11} {getattr(m, '__version__', '')}  ({why})")
+        except ImportError:
+            print(f"  missing  {mod:<11} ({why})")
+    return 0
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="ayna", description="Know whether your inferred dynamics are real, before you interpret them.")
+    p.add_argument("--version", action="version", version=f"ayna {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("synth", help="write a synthetic bundle with injected faults")
+    s.add_argument("name")
+    s.add_argument("--faults", nargs="*", default=[], metavar="FAULT[=SEVERITY]",
+                   help="underfit, feature_invention, misattribution, input_driven, nonlinear_readout")
+    s.add_argument("--sweep", action="store_true", help="write a simulated latent-size sweep instead")
+    s.add_argument("--latent-dim", type=int, default=8)
+    s.add_argument("--inputs", choices=["auto", "inferred", "supplied", "none"], default="auto")
+    s.add_argument("--trials", type=int, default=200)
+    s.add_argument("--neurons", type=int, default=60)
+    s.add_argument("--seed", type=int, default=0)
+    s.add_argument("--out", default="datasets")
+    s.set_defaults(fn=cmd_synth)
+
+    s = sub.add_parser("scan", help="diagnose one fitted model")
+    s.add_argument("bundle")
+    s.add_argument("--out", help="write report.{txt,md,json} here")
+    s.add_argument("--json", action="store_true")
+    s.add_argument("--set", nargs="*", metavar="NAME=VALUE", help="override thresholds")
+    s.add_argument("--no-nonlinear", action="store_true", help="skip the nonlinear cycle-consistency fallback")
+    s.add_argument("--daftar", action="store_true", help="record the scan with daftar")
+    s.set_defaults(fn=cmd_scan)
+
+    s = sub.add_parser("select", help="compare a sweep of models fitted to the same data")
+    s.add_argument("bundles", nargs="+")
+    s.add_argument("--out")
+    s.add_argument("--plot", action="store_true")
+    s.set_defaults(fn=cmd_select)
+
+    s = sub.add_parser("validate", help="check detectors against ground truth")
+    s.add_argument("bundles", nargs="*", help="bundles or directories with ground truth (default: synthetic corpus)")
+    s.add_argument("--n", type=int, default=6, help="synthetic cases per fault type")
+    s.add_argument("--seed", type=int, default=0)
+    s.add_argument("--set", nargs="*", metavar="NAME=VALUE")
+    s.add_argument("--out")
+    s.set_defaults(fn=cmd_validate)
+
+    s = sub.add_parser("info", help="describe a bundle")
+    s.add_argument("bundle")
+    s.set_defaults(fn=cmd_info)
+
+    s = sub.add_parser("export-ctd", help="export a CtD run to a bundle (run inside the CtD environment)")
+    s.add_argument("dd_dir")
+    s.add_argument("out")
+    s.add_argument("--model-type", required=True, choices=["SAE", "LFADS"])
+    s.add_argument("--tt", help="task-trained run directory, for ground truth")
+    s.add_argument("--inputs", choices=["supplied", "inferred"])
+    s.set_defaults(fn=cmd_export_ctd)
+
+    s = sub.add_parser("doctor", help="report versions and optional extras")
+    s.set_defaults(fn=cmd_doctor)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    from .bundle import BundleError
+
+    try:
+        return args.fn(args)
+    except BundleError as exc:
+        print(f"ayna: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())