weightlang 0.1.0__py3-none-any.whl

weightlang/__init__.py

@@ -0,0 +1,17 @@
+"""WeightLang prototype: compile .wgt network descriptions into runnable PyTorch artifacts."""
+
+__version__ = "0.1.0"
+
+from .artifact import Artifact, UntrainedWeightsWarning, load_artifact  # noqa: E402
+from .syntax import Program, WgtError, parse, parse_file  # noqa: E402
+
+__all__ = [
+    "Artifact",
+    "Program",
+    "UntrainedWeightsWarning",
+    "WgtError",
+    "__version__",
+    "load_artifact",
+    "parse",
+    "parse_file",
+]

weightlang/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

weightlang/artifact.py

@@ -0,0 +1,216 @@
+"""Artifact format: manifest.json + weights.safetensors + source.wgt.
+
+Loading never unpickles anything: tensors come from safetensors and the network
+is rebuilt from the declarative layer list in the manifest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import struct
+import sys
+import warnings
+from collections import OrderedDict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Sequence
+
+import torch
+from safetensors.torch import load_file
+from torch import nn
+
+from .syntax import WgtError
+
+ARTIFACT_FORMAT = "weightlang.artifact"
+ARTIFACT_FORMAT_VERSION = 1
+MANIFEST_FILE = "manifest.json"
+WEIGHTS_FILE = "weights.safetensors"
+SOURCE_FILE = "source.wgt"
+
+# Tensor origins recorded per tensor in the manifest.
+ORIGIN_RANDOM = "random-init"
+ORIGIN_TRAINED = "trained"
+ORIGIN_IMPORTED = "imported"
+ORIGIN_IMPORTED_TRAINED = "imported+trained"
+ORIGINS = {ORIGIN_RANDOM, ORIGIN_TRAINED, ORIGIN_IMPORTED, ORIGIN_IMPORTED_TRAINED}
+
+
+class UntrainedWeightsWarning(UserWarning):
+    """Raised when an artifact contains tensors that were only randomly initialised."""
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def write_safetensors(path: Path, tensors: dict[str, torch.Tensor], metadata: dict[str, str]) -> None:
+    """Write float32 tensors in the safetensors format with a byte-stable layout.
+
+    ``safetensors.torch.save_file`` does not guarantee header key order, so the
+    same tensors can produce different bytes (and hashes). Content addressing
+    needs identical bytes, so tensors and header keys are written sorted.
+    The result is read back with the official safetensors loader.
+    """
+
+    if sys.byteorder != "little":
+        raise WgtError("writing safetensors on big-endian hosts is not supported")
+    header: dict[str, Any] = {"__metadata__": dict(sorted(metadata.items()))}
+    blobs: list[bytes] = []
+    offset = 0
+    for name in sorted(tensors):
+        t = tensors[name].detach().to("cpu").contiguous()
+        if t.dtype != torch.float32:
+            raise WgtError(f"tensor {name} must be float32, got {t.dtype}")
+        # clone() gives a storage holding exactly this tensor; no numpy needed (torch does not depend on it)
+        data = bytes(t.clone().untyped_storage())
+        header[name] = {"dtype": "F32", "shape": list(t.shape), "data_offsets": [offset, offset + len(data)]}
+        blobs.append(data)
+        offset += len(data)
+    raw = json.dumps(header, separators=(",", ":"), sort_keys=False).encode()
+    raw += b" " * (-len(raw) % 8)
+    with path.open("wb") as fh:
+        fh.write(struct.pack("<Q", len(raw)))
+        fh.write(raw)
+        for blob in blobs:
+            fh.write(blob)
+
+
+def build_module(layers: Sequence[dict[str, Any]]) -> nn.Sequential:
+    """Build the PyTorch module for a declarative layer list."""
+
+    modules: OrderedDict[str, nn.Module] = OrderedDict()
+    for layer in layers:
+        op = layer["op"]
+        if op == "linear":
+            modules[layer["name"]] = nn.Linear(layer["args"]["in"], layer["args"]["out"])
+        elif op == "relu":
+            modules[layer["name"]] = nn.ReLU()
+        elif op == "tanh":
+            modules[layer["name"]] = nn.Tanh()
+        elif op == "sigmoid":
+            modules[layer["name"]] = nn.Sigmoid()
+        else:
+            raise WgtError(f"unknown layer operation {op!r} in artifact")
+    return nn.Sequential(modules)
+
+
+@dataclass
+class Artifact:
+    path: Path
+    manifest: dict[str, Any]
+    module: nn.Sequential
+
+    @property
+    def name(self) -> str:
+        return self.manifest["model"]
+
+    @property
+    def untrained_tensors(self) -> list[str]:
+        """Tensors whose values were never trained anywhere upstream."""
+
+        result = []
+        for name, meta in self.manifest["weights"]["tensors"].items():
+            if meta["origin"] == ORIGIN_RANDOM or (
+                meta["origin"] == ORIGIN_IMPORTED and meta.get("upstream_origin") == ORIGIN_RANDOM
+            ):
+                result.append(name)
+        return result
+
+    def predict(self, x: torch.Tensor | Sequence[Sequence[float]] | Sequence[float]) -> torch.Tensor:
+        """Run inference. Accepts one feature vector or a batch ``[N, features]``."""
+
+        spec = self.manifest["interface"]["input"]
+        tensor = torch.as_tensor(x, dtype=torch.float32)
+        single = tensor.dim() == 1
+        if single:
+            tensor = tensor.unsqueeze(0)
+        if tensor.dim() != 2 or list(tensor.shape[1:]) != spec["shape"]:
+            raise WgtError(
+                f"input {spec['name']!r} expects shape [N, {spec['shape'][0]}] or [{spec['shape'][0]}], "
+                f"got {list(tensor.shape)}"
+            )
+        with torch.no_grad():
+            out = self.module(tensor)
+        return out[0] if single else out
+
+
+def _check(cond: bool, message: str, path: Path) -> None:
+    if not cond:
+        raise WgtError(message, None, str(path))
+
+
+def load_artifact(path: str | Path, *, warn_untrained: bool = True) -> Artifact:
+    """Load and verify an artifact directory.
+
+    Verifies the format version, sha256 of the weights and source files, and
+    that every tensor matches the declared architecture.
+    """
+
+    root = Path(path)
+    manifest_path = root / MANIFEST_FILE
+    _check(manifest_path.is_file(), f"not a WeightLang artifact (missing {MANIFEST_FILE})", root)
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise WgtError(f"invalid manifest JSON: {exc}", None, str(manifest_path)) from None
+
+    _check(manifest.get("format") == ARTIFACT_FORMAT, "manifest format is not weightlang.artifact", manifest_path)
+    _check(
+        manifest.get("format_version") == ARTIFACT_FORMAT_VERSION,
+        f"unsupported artifact format_version {manifest.get('format_version')!r}; "
+        f"this loader reads version {ARTIFACT_FORMAT_VERSION}",
+        manifest_path,
+    )
+
+    weights_meta = manifest["weights"]
+    weights_path = root / weights_meta["file"]
+    _check(weights_path.is_file(), f"missing weights file {weights_meta['file']}", root)
+    actual = sha256_file(weights_path)
+    _check(
+        actual == weights_meta["sha256"],
+        f"weights sha256 mismatch: manifest {weights_meta['sha256']}, file {actual}",
+        weights_path,
+    )
+    source_meta = manifest["source"]
+    source_path = root / source_meta["file"]
+    _check(source_path.is_file(), f"missing source file {source_meta['file']}", root)
+    _check(sha256_file(source_path) == source_meta["sha256"], "source sha256 mismatch", source_path)
+
+    module = build_module(manifest["layers"])
+    expected = module.state_dict()
+    tensors = load_file(str(weights_path))
+    _check(
+        set(tensors) == set(expected),
+        f"tensor names {sorted(tensors)} do not match architecture {sorted(expected)}",
+        weights_path,
+    )
+    _check(set(weights_meta["tensors"]) == set(expected), "manifest tensor table does not match architecture", root)
+    for name, value in tensors.items():
+        _check(
+            tuple(value.shape) == tuple(expected[name].shape),
+            f"tensor {name} has shape {list(value.shape)}, expected {list(expected[name].shape)}",
+            weights_path,
+        )
+        _check(value.dtype == torch.float32, f"tensor {name} must be float32, got {value.dtype}", weights_path)
+        _check(weights_meta["tensors"][name]["origin"] in ORIGINS, f"tensor {name} has unknown origin", root)
+    module.load_state_dict(tensors, strict=True)
+    module.eval()
+
+    artifact = Artifact(root, manifest, module)
+    if warn_untrained and artifact.untrained_tensors:
+        warnings.warn(
+            f"artifact {artifact.name!r} contains randomly initialised, untrained tensors "
+            f"({', '.join(artifact.untrained_tensors)}); its outputs are not meaningful",
+            UntrainedWeightsWarning,
+            stacklevel=2,
+        )
+    return artifact

weightlang/cli.py

@@ -0,0 +1,179 @@
+"""weightc command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import warnings
+
+from . import __version__
+from .artifact import UntrainedWeightsWarning, load_artifact
+from .syntax import WgtError, parse_file
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    program = parse_file(args.source)
+    params = sum(
+        layer.args["in"] * layer.args["out"] + layer.args["out"] for layer in program.layers if layer.op == "linear"
+    )
+    weights = "trained" if program.train else "random-init only (untrained)"
+    if program.imports:
+        weights += f", {len(program.imports)} imported layer(s)"
+    print(f"ok: model {program.model}, {len(program.layers)} layers, {params} parameters, weights: {weights}")
+    return 0
+
+
+def _cmd_build(args: argparse.Namespace) -> int:
+    from .compiler import compile_file  # imports torch training code lazily
+
+    result = compile_file(args.source, args.out)
+    m = result.manifest
+    print(f"built {result.path}")
+    print(f"  weights sha256 {m['weights']['sha256']}")
+    origins: dict[str, int] = {}
+    for meta in m["weights"]["tensors"].values():
+        origins[meta["origin"]] = origins.get(meta["origin"], 0) + 1
+    print("  tensors " + ", ".join(f"{k}={v}" for k, v in sorted(origins.items())))
+    if m["training"]:
+        t = m["training"]
+        line = f"  training loss {t['initial_loss']:.4f} -> {t['final_loss']:.4f} on {t['rows']} rows ({t['data']})"
+        if "train_accuracy" in t:
+            line += f", train accuracy {t['train_accuracy']:.2f}"
+        print(line)
+    else:
+        print("  WARNING: no train statement; weights are random and outputs are not meaningful")
+    return 0
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always", UntrainedWeightsWarning)
+        artifact = load_artifact(args.artifact)
+    for w in caught:
+        print(f"warning: {w.message}", file=sys.stderr)
+    try:
+        data = json.loads(args.input)
+    except json.JSONDecodeError as exc:
+        raise WgtError(f"--input is not valid JSON: {exc}") from None
+    out = artifact.predict(data)
+    name = artifact.manifest["interface"]["output"]["name"]
+    print(json.dumps({name: out.tolist()}))
+    return 0
+
+
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    artifact = load_artifact(args.artifact, warn_untrained=False)
+    m = artifact.manifest
+    if args.json:
+        print(json.dumps(m, indent=2))
+        return 0
+    io = m["interface"]
+    print(
+        f"model {m['model']}  (format v{m['format_version']}, wgt {m['language_version']}, weightc {m['compiler']['version']})"
+    )
+    print(f"input  {io['input']['name']}: f32{io['input']['shape']}")
+    print(f"output {io['output']['name']}: f32{io['output']['shape']}")
+    print("layers " + " -> ".join(layer["name"] + ":" + layer["op"] for layer in m["layers"]))
+    print("tensors:")
+    for name, meta in m["weights"]["tensors"].items():
+        extra = f" (upstream: {meta['upstream_origin']})" if "upstream_origin" in meta else ""
+        print(f"  {name:<16} {str(meta['shape']):<10} {meta['origin']}{extra}")
+    for imp in m["imports"]:
+        print(
+            f"import {imp['layer']} <- {imp['source_model']}.{imp['source_layer']} "
+            f"sha256={imp['source_weights_sha256'][:12]}… frozen={imp['frozen']}"
+        )
+    if artifact.untrained_tensors:
+        print("WARNING: untrained tensors: " + ", ".join(artifact.untrained_tensors))
+    return 0
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    artifact = load_artifact(args.artifact, warn_untrained=False)
+    print(f"ok: {artifact.path} (weights sha256 {artifact.manifest['weights']['sha256']})")
+    if artifact.untrained_tensors:
+        print("note: contains untrained tensors: " + ", ".join(artifact.untrained_tensors))
+    return 0
+
+
+def _cmd_get(args: argparse.Namespace) -> int:
+    from pathlib import Path
+
+    from .packages import SUM_FILE, get
+
+    fetched = get(Path(args.dir))
+    for item in fetched:
+        print(f"fetched and verified {item}")
+    print(f"wrote {Path(args.dir) / SUM_FILE}" if fetched else "no requirements")
+    return 0
+
+
+def _cmd_publish(args: argparse.Namespace) -> int:
+    from pathlib import Path
+
+    from .packages import MOD_FILE, ModulePath, build_package, check_version, git_publish_checks, parse_mod
+
+    pkg = Path(args.package)
+    check_version(args.version)
+    module = ModulePath.parse(parse_mod(pkg / MOD_FILE).module)
+    commit = git_publish_checks(pkg, module)
+    index = build_package(pkg, args.version, commit, Path(args.out), allow_untrained=args.allow_untrained)
+    tag = module.tag(args.version)
+    print(f"built release assets for {module.path}@{args.version} from commit {commit}")
+    print(f"  index {index}")
+    print("publish with (the commit must already be pushed):")
+    print(f"  git tag {tag} {commit} && git push origin {tag}")
+    print(f"  gh release create {tag} -R {module.owner}/{module.repo} --verify-tag {args.out}/*")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="weightc", description="WeightLang compiler (prototype)")
+    parser.add_argument("--version", action="version", version=f"weightc {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("check", help="parse and type-check a .wgt file without building")
+    p.add_argument("source")
+    p.set_defaults(func=_cmd_check)
+
+    p = sub.add_parser("build", help="compile a .wgt file into an artifact directory")
+    p.add_argument("source")
+    p.add_argument("-o", "--out", default="build", help="output directory (default: build)")
+    p.set_defaults(func=_cmd_build)
+
+    p = sub.add_parser("run", help="run inference with an artifact")
+    p.add_argument("artifact")
+    p.add_argument("--input", required=True, help='JSON vector or batch, e.g. "[[0, 1], [1, 1]]"')
+    p.set_defaults(func=_cmd_run)
+
+    p = sub.add_parser("inspect", help="show an artifact's interface and weight provenance")
+    p.add_argument("artifact")
+    p.add_argument("--json", action="store_true", help="print the raw manifest")
+    p.set_defaults(func=_cmd_inspect)
+
+    p = sub.add_parser("verify", help="check artifact hashes, tensor shapes and loadability")
+    p.add_argument("artifact")
+    p.set_defaults(func=_cmd_verify)
+
+    p = sub.add_parser("get", help="download, verify and lock the requirements in wgt.mod")
+    p.add_argument("dir", nargs="?", default=".", help="directory containing wgt.mod (default: .)")
+    p.set_defaults(func=_cmd_get)
+
+    p = sub.add_parser("publish", help="build a package's release assets and wgt.index.json")
+    p.add_argument("package", help="package directory containing wgt.mod")
+    p.add_argument("--version", required=True, help="semantic version tag, e.g. v0.1.0")
+    p.add_argument("-o", "--out", default="dist", help="empty output directory (default: dist)")
+    p.add_argument("--allow-untrained", action="store_true", help="allow artifacts with untrained tensors")
+    p.set_defaults(func=_cmd_publish)
+
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except WgtError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

weightlang/compiler.py

@@ -0,0 +1,243 @@
+"""weightc compiler: .wgt program -> PyTorch weights -> artifact directory."""
+
+from __future__ import annotations
+
+import json
+import platform
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import torch
+from torch import nn
+
+from . import __version__
+from .artifact import (
+    ARTIFACT_FORMAT,
+    ARTIFACT_FORMAT_VERSION,
+    MANIFEST_FILE,
+    ORIGIN_IMPORTED,
+    ORIGIN_IMPORTED_TRAINED,
+    ORIGIN_RANDOM,
+    ORIGIN_TRAINED,
+    SOURCE_FILE,
+    WEIGHTS_FILE,
+    build_module,
+    load_artifact,
+    sha256_bytes,
+    sha256_file,
+    write_safetensors,
+)
+from .packages import is_module_import, resolve_module_import
+from .syntax import Program, WgtError, parse_file
+
+
+@dataclass
+class BuildResult:
+    path: Path
+    manifest: dict[str, Any]
+    module: nn.Sequential
+
+
+def _layer_dicts(program: Program) -> list[dict[str, Any]]:
+    return [{"name": layer.name, "op": layer.op, "args": dict(layer.args)} for layer in program.layers]
+
+
+def _dataset_tensors(program: Program, name: str) -> tuple[torch.Tensor, torch.Tensor, str]:
+    ds = program.datasets[name]
+    canonical = json.dumps({"inputs": ds.inputs, "targets": ds.targets}, sort_keys=True, separators=(",", ":"))
+    return (
+        torch.tensor(ds.inputs, dtype=torch.float32),
+        torch.tensor(ds.targets, dtype=torch.float32),
+        sha256_bytes(canonical.encode()),
+    )
+
+
+def _apply_imports(program: Program, module: nn.Sequential, base: Path) -> tuple[list[dict], dict[str, str]]:
+    """Copy imported tensors into ``module``. Returns import records and upstream origins."""
+
+    records: list[dict[str, Any]] = []
+    upstream: dict[str, str] = {}
+    for imp in program.imports:
+        package: dict[str, str] | None = None
+        try:
+            if is_module_import(imp.source):
+                resolved = resolve_module_import(imp.source, Path(program.path or "."))
+                src_path = resolved.path
+                package = {"module": resolved.module, "version": resolved.version, "commit": resolved.commit}
+            else:
+                src_path = (base / imp.source).resolve()
+            src = load_artifact(src_path, warn_untrained=False)
+        except WgtError as exc:
+            raise WgtError(f"cannot import {imp.target!r}: {exc}", imp.line, program.path) from None
+        weights_sha = src.manifest["weights"]["sha256"]
+        if imp.sha256 is not None and imp.sha256 != weights_sha:
+            raise WgtError(
+                f"import pin mismatch for {imp.target!r}: expected sha256={imp.sha256}, artifact has {weights_sha}",
+                imp.line,
+                program.path,
+            )
+        src_layer = next((layer for layer in src.manifest["layers"] if layer["name"] == imp.source_layer), None)
+        if src_layer is None or src_layer["op"] != "linear":
+            raise WgtError(
+                f"artifact {src.name!r} has no linear layer named {imp.source_layer!r}", imp.line, program.path
+            )
+        dst_layer = program.layer(imp.target)
+        assert dst_layer is not None
+        if src_layer["args"] != dst_layer.args:
+            raise WgtError(
+                f"incompatible import: {src.name}.{imp.source_layer} is linear(in={src_layer['args']['in']}, "
+                f"out={src_layer['args']['out']}) but {imp.target} is linear(in={dst_layer.args['in']}, "
+                f"out={dst_layer.args['out']})",
+                imp.line,
+                program.path,
+            )
+        src_state = src.module.state_dict()
+        dst_module = getattr(module, imp.target)
+        with torch.no_grad():
+            for pname in ("weight", "bias"):
+                getattr(dst_module, pname).copy_(src_state[f"{imp.source_layer}.{pname}"])
+                src_origin = src.manifest["weights"]["tensors"][f"{imp.source_layer}.{pname}"]
+                upstream[f"{imp.target}.{pname}"] = src_origin.get("upstream_origin", src_origin["origin"])
+        if imp.freeze:
+            for param in dst_module.parameters():
+                param.requires_grad_(False)
+        records.append(
+            {
+                "layer": imp.target,
+                "source": imp.source,
+                "source_model": src.name,
+                "source_layer": imp.source_layer,
+                "source_weights_sha256": weights_sha,
+                "source_manifest_sha256": sha256_file(src_path / MANIFEST_FILE),
+                "package": package,
+                "pinned": imp.sha256 is not None,
+                "frozen": imp.freeze,
+            }
+        )
+    return records, upstream
+
+
+def _train(program: Program, module: nn.Sequential) -> dict[str, Any]:
+    assert program.train is not None
+    spec = program.train
+    x, y, data_sha = _dataset_tensors(program, spec.data)
+    if spec.loss == "bce":
+        if program.layers[-1].op != "sigmoid":
+            raise WgtError("loss=bce requires the last layer to be sigmoid", spec.line, program.path)
+        if not torch.all((y == 0) | (y == 1)):
+            raise WgtError("loss=bce requires targets of 0 or 1", spec.line, program.path)
+        loss_fn: nn.Module = nn.BCELoss()
+    else:
+        loss_fn = nn.MSELoss()
+    params = [p for p in module.parameters() if p.requires_grad]
+    if spec.optimizer == "adam":
+        opt: torch.optim.Optimizer = torch.optim.Adam(params, lr=spec.lr)
+    else:
+        opt = torch.optim.SGD(params, lr=spec.lr)
+
+    module.train()
+    with torch.no_grad():
+        initial_loss = float(loss_fn(module(x), y))
+    for _ in range(spec.epochs):  # full-batch gradient descent: deterministic for a fixed seed
+        opt.zero_grad()
+        loss = loss_fn(module(x), y)
+        loss.backward()
+        opt.step()
+    module.eval()
+    with torch.no_grad():
+        pred = module(x)
+        final_loss = float(loss_fn(pred, y))
+    record: dict[str, Any] = {
+        "data": spec.data,
+        "data_sha256": data_sha,
+        "rows": int(x.shape[0]),
+        "loss": spec.loss,
+        "optimizer": spec.optimizer,
+        "lr": spec.lr,
+        "epochs": spec.epochs,
+        "batch": "full",
+        "initial_loss": initial_loss,
+        "final_loss": final_loss,
+        "note": "metrics are measured on the training data only; they say nothing about generalisation",
+    }
+    if spec.loss == "bce":
+        record["train_accuracy"] = float(((pred >= 0.5).float() == y).float().mean())
+    return record
+
+
+def compile_program(program: Program, out_dir: str | Path) -> BuildResult:
+    """Build ``program`` and write its artifact to ``out_dir/<model>``."""
+
+    if program.path is None:
+        raise WgtError("compile_program needs a program parsed from a file")
+    source_path = Path(program.path)
+    base = source_path.parent
+    layers = _layer_dicts(program)
+
+    # Initialisation uses a private RNG stream so builds do not disturb caller state.
+    with torch.random.fork_rng(devices=[]):
+        torch.manual_seed(program.seed)
+        module = build_module(layers)
+        import_records, upstream = _apply_imports(program, module, base)
+        training = _train(program, module) if program.train is not None else None
+
+    imported = {r["layer"] for r in import_records}
+    frozen = {r["layer"] for r in import_records if r["frozen"]}
+    tensors_meta: dict[str, dict[str, Any]] = {}
+    for name, value in module.state_dict().items():
+        layer_name = name.split(".", 1)[0]
+        trained = training is not None and layer_name not in frozen
+        if layer_name in imported:
+            origin = ORIGIN_IMPORTED_TRAINED if trained else ORIGIN_IMPORTED
+        else:
+            origin = ORIGIN_TRAINED if trained else ORIGIN_RANDOM
+        meta: dict[str, Any] = {"shape": list(value.shape), "dtype": "f32", "origin": origin}
+        if layer_name in imported:
+            meta["upstream_origin"] = upstream[name]
+        tensors_meta[name] = meta
+
+    out_root = Path(out_dir)
+    dest = out_root / program.model
+    if dest.exists() and not (dest / MANIFEST_FILE).is_file():
+        raise WgtError(f"refusing to overwrite {dest}: it exists and is not a WeightLang artifact")
+    tmp = out_root / f".{program.model}.tmp"
+    if tmp.exists():
+        shutil.rmtree(tmp)
+    tmp.mkdir(parents=True)
+    try:
+        write_safetensors(tmp / WEIGHTS_FILE, module.state_dict(), {"format": ARTIFACT_FORMAT, "model": program.model})
+        shutil.copyfile(source_path, tmp / SOURCE_FILE)
+        manifest: dict[str, Any] = {
+            "format": ARTIFACT_FORMAT,
+            "format_version": ARTIFACT_FORMAT_VERSION,
+            "language_version": program.version,
+            "model": program.model,
+            "compiler": {"name": "weightc", "version": __version__},
+            "built_with": {"torch": torch.__version__, "python": platform.python_version()},
+            "source": {"file": SOURCE_FILE, "sha256": sha256_file(tmp / SOURCE_FILE)},
+            "interface": {
+                "input": {"name": program.input.name, "dtype": "f32", "shape": list(program.input.shape)},
+                "output": {"name": program.output.name, "dtype": "f32", "shape": list(program.output.shape)},
+                "batch": "optional leading dimension: [features] or [N, features]",
+            },
+            "layers": layers,
+            "init": {"seed": program.seed, "method": "PyTorch default nn.Linear initialisation"},
+            "imports": import_records,
+            "training": training,
+            "weights": {"file": WEIGHTS_FILE, "sha256": sha256_file(tmp / WEIGHTS_FILE), "tensors": tensors_meta},
+        }
+        (tmp / MANIFEST_FILE).write_text(json.dumps(manifest, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+        if dest.exists():
+            shutil.rmtree(dest)
+        tmp.rename(dest)
+    except BaseException:
+        shutil.rmtree(tmp, ignore_errors=True)
+        raise
+    module.eval()
+    return BuildResult(dest, manifest, module)
+
+
+def compile_file(source: str | Path, out_dir: str | Path) -> BuildResult:
+    return compile_program(parse_file(source), out_dir)