topologies 0.0.1__py3-none-any.whl

topologies/.training-generated-manifest.json

@@ -0,0 +1,35 @@
+{
+  "files": {
+    "catalog/losses/adversarial-hinge.json": "286c60f4abe259ecbc966997c5ea69cfafeb2b0a7ab3cde755375fa7aa6bfdc5",
+    "catalog/losses/binary-cross-entropy-logits.json": "911c44ce2e2c851e4ea94714e17db4ea7b588186160863a8d2c4b7ca0434e41f",
+    "catalog/losses/bpr.json": "6bb7c9bee56ed46e76279f2ff15e24bba23d5ca6f51759b3fa40e96d438922d5",
+    "catalog/losses/cross-entropy.json": "efd29b1d566b528b1c2bd643a5958704f47a742a4f8328283807115ad82729e7",
+    "catalog/losses/ctc.json": "a9fafaa022979a8c5a11f5c70b88b51f83b707478900db0efe0af6e5fa59df02",
+    "catalog/losses/density-nll.json": "8efb9698b515178761c8a97e5114e1b8426cb4adf35f12c5c4a3ada3e156ffae",
+    "catalog/losses/dice.json": "74ed9d2a316587a9391e722394f0841cf9e6c6e74b2dcd10e240f5e0df4e8515",
+    "catalog/losses/gaussian-kl.json": "e6b890155cbd9841f9e322a8162a748ddab9ac82ce7307892f9922a33ffdc762",
+    "catalog/losses/gaussian-nll.json": "738fe652a7bc7a05a4bf349711b80eb0ddfbab6f15ef37ac786b583eec2a757d",
+    "catalog/losses/generalized-iou.json": "58738fa365ef9c4b3ccce23ec6792ee22759dfdfd19a71c8b0138d67d99e65e6",
+    "catalog/losses/huber.json": "c7483686354fbf8585dd058c4e9c4fdc0e34945acfc2e7e1654a7766ea19803b",
+    "catalog/losses/info-nce.json": "0192a354405365f7e72a3ce0a2144a8d8d9ff0c990b6d8d2765272bd1becd0cc",
+    "catalog/losses/mean-absolute-error.json": "63d67ec7939833c2b14a980a0c2877b6744d280fb9832360212a48a7c8ee71be",
+    "catalog/losses/mean-squared-error.json": "0ee304df66459af43ece23089c52ca4db06e2b5c38ad821b88edfe76b40174de",
+    "catalog/losses/multi-resolution-stft.json": "40152f8fae18a70bdba318d72f73f8825b8fed4eb3b3aabb6b3cd29943bea051",
+    "catalog/losses/pinball.json": "634d8e419bb589f3dc88c6ac298f34661399dff72ba358b0eb00fe346dc04ba1",
+    "catalog/losses/si-sdr.json": "0e5aae6fc3b456ef0e9fd7344063af0649cfff074ee7a5497b310cddce8b9b56",
+    "catalog/losses/sigmoid-focal.json": "3bbcbdffbef6b8f0273a41deed2eb3464090bdd3d2cb892288f6d2b727636010",
+    "catalog/losses/smooth-l1.json": "1ff330df021b22bde778e4eb368808ca362a33756699bea80b5adf90bb069a19",
+    "catalog/losses/softmax-focal.json": "99c537a068de5dd6ee895c95904a7bd4577280c3f4ff66850f55393c43a20d82",
+    "catalog/losses/triplet-margin.json": "f50ab04a959fbfa56aec7d67e696bce1c6105fcb514cb0c81f0cfe6d96c15ea5",
+    "catalog/optimizers/adagrad.json": "eb69076643a5972c978f66de9c8b823a4611a3491249d29f2232169adc5b8cce",
+    "catalog/optimizers/adam.json": "e420f39369b3b177d750def83fa01da346243c644f31a238f38f772b5e5402ef",
+    "catalog/optimizers/adamw.json": "babae746f4bc25d204f6f1681e85ed9c552ddb3d982ec129d85eb8ffb7fe69bb",
+    "catalog/optimizers/rmsprop.json": "77289f20d17474864a7673f9e95d0199ee5580b194d66b4acaa69ab9dc7072b0",
+    "catalog/optimizers/sgd.json": "a3b871e622acaf3254656649a04cec267e3c329936822f063c6aadf85132baf8",
+    "implementations/optimizers/core.py": "4ceb0d8a8d647fd4990fee685fe979566f0385431bfb15d5e65b46e58e6735d2",
+    "implementations/training/core.py": "878f03ad0677bb8cd1b993861f72dcf5bfa14853743a5b355353c1d1f8162f9b",
+    "losses/catalog.json": "2900b0eb1a4a5b2c7a9c1885a24df206eed6929005470d69aab561a4442f449f",
+    "optimizers/catalog.json": "94cb3aed39e274bbc8912c07e5d72189fdc801eca8b5ebe19b8ce4d1d9fc21a6"
+  },
+  "schema_version": 1
+}

topologies/.training-materialized-manifest.json

@@ -0,0 +1,35 @@
+{
+  "files": {
+    "catalog/losses/adversarial-hinge.json": "286c60f4abe259ecbc966997c5ea69cfafeb2b0a7ab3cde755375fa7aa6bfdc5",
+    "catalog/losses/binary-cross-entropy-logits.json": "911c44ce2e2c851e4ea94714e17db4ea7b588186160863a8d2c4b7ca0434e41f",
+    "catalog/losses/bpr.json": "6bb7c9bee56ed46e76279f2ff15e24bba23d5ca6f51759b3fa40e96d438922d5",
+    "catalog/losses/cross-entropy.json": "efd29b1d566b528b1c2bd643a5958704f47a742a4f8328283807115ad82729e7",
+    "catalog/losses/ctc.json": "a9fafaa022979a8c5a11f5c70b88b51f83b707478900db0efe0af6e5fa59df02",
+    "catalog/losses/density-nll.json": "8efb9698b515178761c8a97e5114e1b8426cb4adf35f12c5c4a3ada3e156ffae",
+    "catalog/losses/dice.json": "74ed9d2a316587a9391e722394f0841cf9e6c6e74b2dcd10e240f5e0df4e8515",
+    "catalog/losses/gaussian-kl.json": "e6b890155cbd9841f9e322a8162a748ddab9ac82ce7307892f9922a33ffdc762",
+    "catalog/losses/gaussian-nll.json": "738fe652a7bc7a05a4bf349711b80eb0ddfbab6f15ef37ac786b583eec2a757d",
+    "catalog/losses/generalized-iou.json": "58738fa365ef9c4b3ccce23ec6792ee22759dfdfd19a71c8b0138d67d99e65e6",
+    "catalog/losses/huber.json": "c7483686354fbf8585dd058c4e9c4fdc0e34945acfc2e7e1654a7766ea19803b",
+    "catalog/losses/info-nce.json": "0192a354405365f7e72a3ce0a2144a8d8d9ff0c990b6d8d2765272bd1becd0cc",
+    "catalog/losses/mean-absolute-error.json": "63d67ec7939833c2b14a980a0c2877b6744d280fb9832360212a48a7c8ee71be",
+    "catalog/losses/mean-squared-error.json": "0ee304df66459af43ece23089c52ca4db06e2b5c38ad821b88edfe76b40174de",
+    "catalog/losses/multi-resolution-stft.json": "40152f8fae18a70bdba318d72f73f8825b8fed4eb3b3aabb6b3cd29943bea051",
+    "catalog/losses/pinball.json": "634d8e419bb589f3dc88c6ac298f34661399dff72ba358b0eb00fe346dc04ba1",
+    "catalog/losses/si-sdr.json": "0e5aae6fc3b456ef0e9fd7344063af0649cfff074ee7a5497b310cddce8b9b56",
+    "catalog/losses/sigmoid-focal.json": "3bbcbdffbef6b8f0273a41deed2eb3464090bdd3d2cb892288f6d2b727636010",
+    "catalog/losses/smooth-l1.json": "1ff330df021b22bde778e4eb368808ca362a33756699bea80b5adf90bb069a19",
+    "catalog/losses/softmax-focal.json": "99c537a068de5dd6ee895c95904a7bd4577280c3f4ff66850f55393c43a20d82",
+    "catalog/losses/triplet-margin.json": "f50ab04a959fbfa56aec7d67e696bce1c6105fcb514cb0c81f0cfe6d96c15ea5",
+    "catalog/optimizers/adagrad.json": "eb69076643a5972c978f66de9c8b823a4611a3491249d29f2232169adc5b8cce",
+    "catalog/optimizers/adam.json": "e420f39369b3b177d750def83fa01da346243c644f31a238f38f772b5e5402ef",
+    "catalog/optimizers/adamw.json": "babae746f4bc25d204f6f1681e85ed9c552ddb3d982ec129d85eb8ffb7fe69bb",
+    "catalog/optimizers/rmsprop.json": "77289f20d17474864a7673f9e95d0199ee5580b194d66b4acaa69ab9dc7072b0",
+    "catalog/optimizers/sgd.json": "a3b871e622acaf3254656649a04cec267e3c329936822f063c6aadf85132baf8",
+    "implementations/optimizers/core.py": "4ceb0d8a8d647fd4990fee685fe979566f0385431bfb15d5e65b46e58e6735d2",
+    "implementations/training/core.py": "878f03ad0677bb8cd1b993861f72dcf5bfa14853743a5b355353c1d1f8162f9b",
+    "losses/catalog.json": "2900b0eb1a4a5b2c7a9c1885a24df206eed6929005470d69aab561a4442f449f",
+    "optimizers/catalog.json": "94cb3aed39e274bbc8912c07e5d72189fdc801eca8b5ebe19b8ce4d1d9fc21a6"
+  },
+  "schema_version": 1
+}

topologies/__init__.py

@@ -0,0 +1,89 @@
+"""topologies: a library of modern neural-network architectures on PyTorch.
+
+The most-used entry points are importable from the top level (loaded lazily):
+
+    from topologies import Trainer, build, data, generate, load_pretrained
+
+Subpackages: ``data`` (datasets/loaders), ``tokenizers``, ``nn`` (components
+and stacks), ``build`` (presets, parameter budgets, validation),
+``training`` (Trainer + recipes), ``models``/``layers`` (catalog),
+``generation``, ``inference``, ``metrics``, ``pretrained``, ``experiments``
+(``Experiment`` / ``experiment`` / ``compare``: comparisons over many trials),
+``synth`` (synthetic data generation, measured by training on it),
+``introspection`` (``introspect(model)``: what happens inside a network).
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from typing import Any
+
+__version__ = "0.0.1"
+
+# A library never configures output: applications attach handlers themselves.
+logging.getLogger("topologies").addHandler(logging.NullHandler())
+
+_LAZY: dict[str, tuple[str, str | None]] = {
+    "Registry": ("topologies.registry.api", "Registry"),
+    "Trainer": ("topologies.training", "Trainer"),
+    "analyze": ("topologies.analysis", "analyze"),
+    "analyze_training": ("topologies.analysis", "analyze_training"),
+    "analyze_inference": ("topologies.analysis", "analyze_inference"),
+    "analyze_hardware": ("topologies.analysis", "analyze_hardware"),
+    "TrainingError": ("topologies.training", "TrainingError"),
+    "build": ("topologies.build", None),  # callable package: build(...)
+    "ConfigError": ("topologies.build", "ConfigError"),
+    "generate": ("topologies.generation", "generate"),
+    "stream_generate": ("topologies.generation", "stream_generate"),
+    "load_pretrained": ("topologies.pretrained", "load_pretrained"),
+    "save_pretrained": ("topologies.pretrained", "save_pretrained"),
+    "train_tokenizer": ("topologies.tokenizers", "train_tokenizer"),
+    "load_tokenizer": ("topologies.tokenizers", "load_tokenizer"),
+    "predict": ("topologies.inference", "predict"),
+    "data": ("topologies.data", None),
+    "datasets": ("topologies.datasets", None),
+    "list_datasets": ("topologies.datasets", "list_datasets"),
+    "search_datasets": ("topologies.datasets", "search_datasets"),
+    "get_dataset": ("topologies.datasets", "get_dataset"),
+    "tokenizers": ("topologies.tokenizers", None),
+    "nn": ("topologies.nn", None),
+    "metrics": ("topologies.metrics", None),
+    "models": ("topologies.models", None),
+    "layers": ("topologies.layers", None),
+    "training": ("topologies.training", None),
+    "generation": ("topologies.generation", None),
+    "inference": ("topologies.inference", None),
+    "pretrained": ("topologies.pretrained", None),
+    "Experiment": ("topologies.experiments", "Experiment"),
+    "experiment": ("topologies.experiments", "experiment"),
+    "compare": ("topologies.experiments", "compare"),
+    "experiments": ("topologies.experiments", None),
+    "synth": ("topologies.synth", None),
+    "optimization": ("topologies.optimization", None),
+    "evaluation": ("topologies.evaluation", None),
+    "introspect": ("topologies.introspection.api", "introspect"),
+    "introspection": ("topologies.introspection", None),
+}
+
+__all__ = ["__version__", *_LAZY]  # noqa: PLE0604
+
+# Catalog packages are plain PyTorch; the framework adds list_*/get_* and lazy
+# class attributes to them from the outside.
+from topologies import _catalog
+
+_catalog.install()
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY.get(name)
+    if target is None:
+        raise AttributeError(f"module 'topologies' has no attribute {name!r}")
+    module = importlib.import_module(target[0])
+    value = module if target[1] is None else getattr(module, target[1])
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

topologies/_catalog.py

@@ -0,0 +1,293 @@
+"""Framework-side discovery of the catalog (``topologies.models`` / ``topologies.layers``).
+
+Catalog files are standalone PyTorch code: stdlib + ``torch`` only, no
+``topologies`` imports, plain ``nn.Module`` subclasses. They never know the
+framework exists; this module adapts them from the outside.
+
+A catalog class is any top-level class whose body sets
+``architecture_id = "..."`` (models) or ``component_id = "..."`` (layers).
+Inheritance plays no role. Files are parsed with ``ast`` (never imported), so
+``import topologies.models`` stays cheap; the class is imported on first use
+and its id attribute is checked against the parsed one.
+
+The registry (``registry/*.yaml``: ``id`` / ``module_path`` / ``class_name``)
+is cross-checked against the scan by ``registry_mismatches`` (CI and
+``topologies registry validate``). It is not read at runtime because the
+YAML files are not shipped in the wheel.
+
+``install()`` (called from ``topologies/__init__.py``) attaches the
+catalog API to the two packages: ``list_models`` / ``get_model``,
+``list_layers`` / ``get_layer`` and lazy class attributes such as
+``topologies.models.ResNetBackbone``.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+# kind -> (package, id attribute)
+KINDS: dict[str, tuple[str, str]] = {
+    "model": ("topologies.models", "architecture_id"),
+    "layer": ("topologies.layers", "component_id"),
+}
+
+@dataclass(frozen=True)
+class CatalogEntry:
+    name: str
+    id: str
+    module: str
+    is_demo: bool
+    kind: str = "model"
+
+    def load(self) -> type:
+        cls = getattr(importlib.import_module(self.module), self.name)
+        attr = KINDS[self.kind][1]
+        if getattr(cls, attr, None) != self.id:
+            raise ImportError(
+                f"{self.module}.{self.name}.{attr} is {getattr(cls, attr, None)!r}, "
+                f"expected {self.id!r}")
+        return cls
+
+
+def scan(package: str, directory: Path, kind: str) -> dict[str, CatalogEntry]:
+    """``class name -> entry`` for every catalog class defined in ``directory``."""
+    attribute = KINDS[kind][1]
+    out: dict[str, CatalogEntry] = {}
+    for path in sorted(directory.glob("*.py")):
+        if path.name.startswith("_"):
+            continue
+        text = path.read_text(encoding="utf-8")
+        for node in ast.parse(text, filename=str(path)).body:
+            if not isinstance(node, ast.ClassDef):
+                continue
+            values = {}
+            for assignment in node.body:
+                if isinstance(assignment, ast.Assign):
+                    targets = assignment.targets
+                elif isinstance(assignment, ast.AnnAssign):
+                    targets = [assignment.target]
+                else:
+                    continue
+                if isinstance(assignment.value, ast.Constant):
+                    for target in targets:
+                        if isinstance(target, ast.Name):
+                            values[target.id] = assignment.value.value
+            ident = values.get(attribute)
+            if not isinstance(ident, str):
+                continue
+            if node.name in out:
+                raise ValueError(f"duplicate catalog class {node.name!r}: {path}")
+            out[node.name] = CatalogEntry(
+                name=node.name, id=ident, module=f"{package}.{path.stem}",
+                is_demo=values.get("is_demo") is True, kind=kind,
+            )
+    return out
+
+
+_CACHE: dict[str, dict[str, CatalogEntry]] = {}
+
+
+def entries(kind: str) -> dict[str, CatalogEntry]:
+    """Cached scan of the ``kind`` package (``"model"`` or ``"layer"``)."""
+    if kind not in _CACHE:
+        package = KINDS[kind][0]
+        directory = Path(importlib.import_module(package).__path__[0])
+        _CACHE[kind] = scan(package, directory, kind)
+    return _CACHE[kind]
+
+
+def find(entries: dict[str, CatalogEntry], key: str, kind: str) -> CatalogEntry:
+    """Look up by class name, registry id, or module name (``llama_decoder``)."""
+    if key in entries:
+        return entries[key]
+    norm = key.strip().lower().replace("_", "-")
+    for e in entries.values():
+        if norm in (e.id, e.name.lower(), e.module.rsplit(".", 1)[-1].replace("_", "-")):
+            return e
+    import difflib
+
+    names = sorted({*entries, *(e.id for e in entries.values() if e.id)})
+    sug = difflib.get_close_matches(key, names, n=3)
+    hint = f" Did you mean {', '.join(map(repr, sug))}?" if sug else ""
+    raise KeyError(f"Unknown {kind} {key!r}.{hint} See list_{kind}s().")
+
+
+def list_entries(kind: str, *, include_demo: bool = True) -> list[dict[str, Any]]:
+    return [
+        {"name": e.name, "id": e.id, "module": e.module, "is_demo": e.is_demo}
+        for e in sorted(entries(kind).values(), key=lambda e: e.id or e.name)
+        if include_demo or not e.is_demo
+    ]
+
+
+def get(kind: str, key: str) -> type:
+    return find(entries(kind), key, kind).load()
+
+
+def catalog_id(obj: Any) -> tuple[str, str] | None:
+    """``(kind, id)`` if ``obj`` (class or instance) is the canonical catalog class."""
+    cls = obj if isinstance(obj, type) else type(obj)
+    for kind, (package, attr) in KINDS.items():
+        ident = cls.__dict__.get(attr)
+        if not isinstance(ident, str) or not cls.__module__.startswith(package + "."):
+            continue
+        entry = entries(kind).get(cls.__name__)
+        if entry is not None and entry.id == ident and entry.module == cls.__module__:
+            return kind, ident
+    return None
+
+
+FRAMEWORK_DECORATORS = frozenset({"presets", "register_presets", "budget_knobs",
+                                  "register_budget_knobs"})
+
+
+def standalone_violations(source: str, filename: str = "<catalog>") -> list[str]:
+    """Why ``source`` is not a standalone catalog file (empty = stdlib + torch only).
+
+    Flags imports outside the standard library and ``torch``, relative imports
+    and framework decorators (``@presets`` / ``@budget_knobs`` ...).
+    """
+    import ast
+    import sys
+
+    from topologies.validation.source_style import comment_and_docstring_violations
+
+    allowed = set(sys.stdlib_module_names) | {"torch", "__future__"}
+    out: list[str] = []
+    from topologies.validation.implementation import discarded_algorithm_classes
+
+    out.extend(f"{filename}: {name}.forward discards its algorithm by multiplying it by zero"
+               for name in discarded_algorithm_classes(source))
+    out.extend(f"{filename}:{problem}" for problem in
+               comment_and_docstring_violations(source, filename))
+    for node in ast.walk(ast.parse(source, filename)):
+        if isinstance(node, ast.Import):
+            mods = [(a.name, node.lineno) for a in node.names]
+        elif isinstance(node, ast.ImportFrom):
+            if node.level:
+                out.append(f"{filename}:{node.lineno}: relative import "
+                           f"'{'.' * node.level}{node.module or ''}'")
+                continue
+            mods = [(node.module or "", node.lineno)]
+        elif isinstance(node, (ast.ClassDef, ast.FunctionDef)):
+            for d in node.decorator_list:
+                target = d.func if isinstance(d, ast.Call) else d
+                name = target.attr if isinstance(target, ast.Attribute) else \
+                    getattr(target, "id", "")
+                if name in FRAMEWORK_DECORATORS:
+                    out.append(f"{filename}:{d.lineno}: framework decorator @{name}")
+            continue
+        else:
+            continue
+        for mod, line in mods:
+            if mod.split(".")[0] not in allowed:
+                out.append(f"{filename}:{line}: import of {mod!r} (stdlib + torch only)")
+    return out
+
+
+def registry_mismatches(index: Any) -> list[str]:
+    """Problems between registry records and the scanned catalog (empty = consistent).
+
+    ``index`` is a ``RegistryIndex`` (``Registry.load().index``).
+
+    Checks every registry record pointing into ``topologies.models`` /
+    ``topologies.layers``: the module imports, the class exists, is an
+    ``nn.Module``, and its ``architecture_id`` / ``component_id`` equals the
+    registry id; and every scanned catalog class has a registry record.
+    """
+    import torch.nn as nn
+
+    problems: list[str] = []
+    seen: dict[str, set[str]] = {k: set() for k in KINDS}
+    for rec in index.records:
+        mod = rec.module_path or ""
+        kind = next((k for k, (pkg, _) in KINDS.items() if mod.startswith(pkg + ".")), None)
+        if kind is None:
+            continue
+        attr = KINDS[kind][1]
+        try:
+            cls = getattr(importlib.import_module(mod), rec.class_name)
+        except Exception as e:  # noqa: BLE001
+            problems.append(f"{rec.id}: cannot import {mod}:{rec.class_name} ({e})")
+            continue
+        if not (isinstance(cls, type) and issubclass(cls, nn.Module)):
+            problems.append(f"{rec.id}: {mod}:{rec.class_name} is not an nn.Module subclass")
+        if getattr(cls, attr, None) != rec.id:
+            problems.append(f"{rec.id}: {rec.class_name}.{attr} is "
+                            f"{getattr(cls, attr, None)!r}, expected {rec.id!r}")
+        entry = entries(kind).get(rec.class_name)
+        if entry is None or entry.module != mod:
+            problems.append(f"{rec.id}: {mod}:{rec.class_name} not found by catalog discovery")
+        seen[kind].add(rec.class_name)
+    for kind in KINDS:
+        for name, e in entries(kind).items():
+            if name not in seen[kind]:
+                problems.append(f"{e.id}: {e.module}:{name} has no registry record")
+            path = Path(importlib.import_module(KINDS[kind][0]).__path__[0])
+            source = (path / f"{e.module.rsplit('.', 1)[1]}.py").read_text(encoding="utf-8")
+            problems += [f"{e.id}: {v}" for v in standalone_violations(source, e.module)]
+    return problems
+
+
+# ---------------------------------------------------------------- package API
+
+
+def _deprecated_base(name: str) -> Any:
+    warnings.warn(
+        f"{name} is deprecated: catalog classes subclass torch.nn.Module directly. "
+        "Use topologies.build.Configurable for automatic constructor recording.",
+        DeprecationWarning, stacklevel=3)
+    from topologies import _compat
+
+    return getattr(_compat, name)
+
+
+def _make_namespace(kind: str, module: Any) -> None:
+    plural = f"{kind}s"
+    compat = "TopologiesModel" if kind == "model" else "TopologiesLayer"
+
+    def list_fn(*, include_demo: bool = True) -> list[dict[str, Any]]:
+        return list_entries(kind, include_demo=include_demo)
+
+    def get_fn(key: str) -> type:
+        return get(kind, key)
+
+    list_fn.__name__ = list_fn.__qualname__ = f"list_{plural}"
+    list_fn.__doc__ = f'``[{{"name", "id", "module", "is_demo"}}, ...]`` for every catalog {kind}.'
+    get_fn.__name__ = get_fn.__qualname__ = f"get_{kind}"
+    get_fn.__doc__ = f"Catalog {kind} class by class name, registry id or module name."
+    for fn in (list_fn, get_fn):
+        fn.__module__ = module.__name__
+
+    def __getattr__(name: str) -> Any:
+        if name == "__all__":
+            return [f"get_{kind}", f"list_{plural}", *sorted(entries(kind))]
+        if name == compat:
+            return _deprecated_base(name)
+        entry = entries(kind).get(name)
+        if entry is None:
+            raise AttributeError(f"module {module.__name__!r} has no attribute {name!r}")
+        cls = entry.load()
+        setattr(module, name, cls)
+        return cls
+
+    def __dir__() -> list[str]:
+        return sorted(set(vars(module)) | set(__getattr__("__all__")))
+
+    setattr(module, f"list_{plural}", list_fn)
+    setattr(module, f"get_{kind}", get_fn)
+    module.__getattr__ = __getattr__
+    module.__dir__ = __dir__
+
+
+def install() -> None:
+    """Attach the catalog API to ``topologies.models`` and ``topologies.layers``."""
+    for kind, (package, _) in KINDS.items():
+        module = importlib.import_module(package)
+        if not hasattr(module, f"get_{kind}"):
+            _make_namespace(kind, module)

topologies/_compat.py

@@ -0,0 +1,27 @@
+"""Deprecated base classes kept for external code written against older releases.
+
+Catalog classes (``topologies.models`` / ``topologies.layers``) subclass
+``torch.nn.Module`` directly and never import ``topologies``; nothing in the
+framework requires these bases. Reach them as ``topologies.models.TopologiesModel``
+/ ``topologies.layers.TopologiesLayer`` (emits ``DeprecationWarning``).
+"""
+
+from __future__ import annotations
+
+import torch.nn as nn
+
+from topologies.build.config import Configurable
+
+
+class TopologiesModel(Configurable, nn.Module):
+    """Deprecated: subclass ``nn.Module`` (plus ``Configurable`` if wanted)."""
+
+    architecture_id: str = ""
+    is_demo: bool = False
+
+
+class TopologiesLayer(nn.Module):
+    """Deprecated: subclass ``nn.Module``."""
+
+    component_id: str = ""
+    is_demo: bool = False

topologies/_execution.py

@@ -0,0 +1,178 @@
+"""Shared explicit model-call, recursive transfer, and execution lifecycle helpers."""
+from __future__ import annotations
+
+import random
+import sys
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager, nullcontext
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import torch
+
+_TRANSFER_HANDLERS: dict[type, Any] = {}
+
+
+def register_transfer_handler(container_type: type, handler: Any) -> None:
+    """Register reconstruction handler ``handler(value, transfer_leaf)``."""
+    if not isinstance(container_type, type) or not callable(handler):
+        raise TypeError("container_type must be a type and handler callable")
+    if container_type in _TRANSFER_HANDLERS:
+        raise ValueError(f"Transfer handler already registered for {container_type!r}")
+    _TRANSFER_HANDLERS[container_type] = handler
+
+
+@dataclass
+class ModelCall:
+    """An unambiguous invocation; a raw tensor is represented as one positional arg."""
+
+    args: tuple[Any, ...] = ()
+    kwargs: dict[str, Any] = field(default_factory=dict)
+
+
+def transfer(value: Any, device: str | torch.device, *, non_blocking: bool = False,
+             _path: str = "input") -> Any:
+    """Recursively transfer tensor leaves; never silently leave failed tensors behind."""
+    if isinstance(value, torch.Tensor):
+        try:
+            return value.to(device, non_blocking=non_blocking)
+        except Exception as exc:
+            raise RuntimeError(f"Tensor transfer failed at {_path}: {exc}") from exc
+    for container_type, handler in _TRANSFER_HANDLERS.items():
+        if isinstance(value, container_type):
+            try:
+                return handler(value, lambda child, suffix="item": transfer(
+                    child, device, non_blocking=non_blocking, _path=f"{_path}.{suffix}"))
+            except Exception as exc:
+                raise RuntimeError(f"Container transfer failed at {_path}: {exc}") from exc
+    if isinstance(value, Mapping):
+        pairs = ((k, transfer(v, device, non_blocking=non_blocking, _path=f"{_path}.{k}"))
+                 for k, v in value.items())
+        try:
+            return type(value)(pairs)
+        except Exception as exc:
+            raise RuntimeError(f"Container reconstruction failed at {_path}: {exc}") from exc
+    if isinstance(value, tuple) and hasattr(value, "_fields"):
+        return type(value)(*(transfer(v, device, non_blocking=non_blocking,
+                                      _path=f"{_path}.{name}")
+                             for name, v in zip(value._fields, value)))
+    if isinstance(value, tuple):
+        return tuple(transfer(v, device, non_blocking=non_blocking, _path=f"{_path}[{i}]")
+                     for i, v in enumerate(value))
+    if isinstance(value, list):
+        return [transfer(v, device, non_blocking=non_blocking, _path=f"{_path}[{i}]")
+                for i, v in enumerate(value)]
+    return value
+
+
+@contextmanager
+def execution_rng(*, preserve_rng: bool = True, seed: int | None = None) -> Iterator[None]:
+    """Preserve framework/Python/loaded-NumPy RNG state and optionally seed a scoped execution.
+
+    NumPy is inspected only in ``sys.modules`` so this helper does not make an
+    optional dependency eager. Explicit seeds use NumPy-compatible uint32 range.
+    A supplied seed always restores the caller's streams, even when preservation
+    is otherwise disabled.
+    """
+    if seed is not None and (isinstance(seed, bool) or not isinstance(seed, int) or
+                             not 0 <= seed <= 0xFFFFFFFF):
+        raise ValueError("seed must be an integer in [0, 2**32 - 1]")
+    restore = preserve_rng or seed is not None
+    devices = list(range(torch.cuda.device_count())) if restore and torch.cuda.is_available() else []
+    rng_context = torch.random.fork_rng(devices=devices, enabled=restore)
+    python_state = random.getstate() if restore else None
+    numpy = sys.modules.get("numpy")
+    numpy_state = numpy.random.get_state() if restore and numpy is not None else None
+    try:
+        with rng_context:
+            if seed is not None:
+                torch.manual_seed(seed)
+                if torch.cuda.is_available():
+                    torch.cuda.manual_seed_all(seed)
+                random.seed(seed)
+                if numpy is not None:
+                    numpy.random.seed(seed)
+            yield
+    finally:
+        if python_state is not None:
+            random.setstate(python_state)
+        if numpy_state is not None:
+            numpy.random.set_state(numpy_state)
+
+
+GradMode = Literal["inference", "no_grad", "enable", "unchanged"]
+_GRAD_MODES: dict[str, Any] = {
+    "inference": torch.inference_mode,
+    "no_grad": torch.no_grad,
+    "enable": torch.enable_grad,
+    "unchanged": nullcontext,
+}
+
+
+@contextmanager
+def model_execution(model: Any, *, training: bool = False, inference: bool = True,
+                    preserve_rng: bool = True, seed: int | None = None,
+                    grad_mode: GradMode | None = None) -> Iterator[None]:
+    """Set mode and grad policy, restoring every submodule's mode even on exceptions.
+
+    ``grad_mode``: ``"inference"`` (``torch.inference_mode``; outputs can never
+    join autograd), ``"no_grad"`` (outputs stay usable as autograd inputs),
+    ``"enable"`` or ``"unchanged"`` (leave the caller's grad mode alone, e.g.
+    for generators that yield while suspended). Default: ``"inference"`` when
+    ``inference`` else ``"enable"``.
+    """
+    mode = grad_mode or ("inference" if inference else "enable")
+    if mode not in _GRAD_MODES:
+        raise ValueError(f"grad_mode must be one of {sorted(_GRAD_MODES)}, got {mode!r}")
+    modules = list(model.modules()) if callable(getattr(model, "modules", None)) else []
+    flags = [module.training for module in modules]
+    try:
+        with execution_rng(preserve_rng=preserve_rng, seed=seed):
+            if modules:
+                model.train(training)
+            with _GRAD_MODES[mode]():
+                yield
+    finally:
+        for module, flag in zip(modules, flags):
+            module.training = flag
+
+
+def _tensors_depth_first(value: Any) -> Iterator[torch.Tensor]:
+    if isinstance(value, torch.Tensor):
+        yield value
+    elif isinstance(value, Mapping):
+        for item in value.values():
+            yield from _tensors_depth_first(item)
+    elif isinstance(value, (tuple, list)):
+        for item in value:
+            yield from _tensors_depth_first(item)
+
+
+def primary_output(out: Any, *, prefer: str | None = "logits", floating: bool = False,
+                   strict: bool = True) -> Any:
+    """The primary tensor of a model output (one rule for every call site).
+
+    A tensor is returned as is. A mapping yields its ``prefer`` key when present
+    (``"logits"`` by default), otherwise its values in order; tuples/lists are
+    searched depth-first for the first tensor (the first floating-point tensor
+    when ``floating``). With ``strict=False`` an output without a matching
+    tensor is returned unchanged (sequences: their first element) instead of
+    raising ``TypeError``.
+    """
+    if isinstance(out, torch.Tensor):
+        return out
+    candidate = out
+    if isinstance(out, Mapping) and prefer is not None and prefer in out:
+        candidate = out[prefer]
+        if isinstance(candidate, torch.Tensor):
+            return candidate
+    for tensor in _tensors_depth_first(candidate):
+        if not floating or tensor.is_floating_point():
+            return tensor
+    if not strict:
+        if isinstance(out, (tuple, list)) and out:
+            return out[0]
+        return out
+    raise TypeError(f"Model returned {type(out).__name__} without a "
+                    f"{'floating-point ' if floating else ''}tensor output.")
+

topologies/_util/__init__.py

@@ -0,0 +1 @@
+"""Small shared internals (filesystem, JSON, suggestions, seeding). Not public API."""