WeightLang

A programming language for building neural networks — and shipping their weights.

Install · Quick start · Language · Reuse · Packages · Docs · Limitations

You write a network in a .wgt file. weightc uses PyTorch to build it, initialise it, train it or import weights into it, and writes an artifact: a directory holding the weights plus everything needed to load and run them — architecture, input/output contract, versions, hashes, and where every tensor came from. Artifacts can be published as packages addressed by GitHub path, Go-style, and their weights reused by other programs.

WeightLang is meant to be written mostly by AI coding models, so the syntax is small, line-oriented and strict. It should still be easy for a person to review.

 xor.wgt ──weightc build──▶ build/xor_mlp/ ──weightc run──▶ {"prob": [[0.00003], [0.9999], ...]}
                              ├─ manifest.json        structure · I/O · provenance · hashes
                              ├─ weights.safetensors  float32 tensors, no pickle
                              └─ source.wgt           the exact source

Install

Linux / macOS

curl -fsSL https://github.com/WeightLang/WeightLang/releases/latest/download/install.sh | sh

Windows (PowerShell)

irm https://github.com/WeightLang/WeightLang/releases/latest/download/install.ps1 | iex

Both scripts download the weightlang wheel from the GitHub release, check its sha256 against the release's SHA256SUMS, and install it with uv tool if uv is available, otherwise into a private virtual environment (no sudo / admin needed). On Linux they install the CPU build of PyTorch by default (WEIGHTLANG_TORCH=default for PyPI's CUDA build). Pin a version with WEIGHTLANG_VERSION=v0.2.0. Read the scripts before piping them to a shell: install.sh, install.ps1.

# With uv, straight from the release wheel
uv tool install https://github.com/WeightLang/WeightLang/releases/download/v0.2.0/weightlang-0.2.0-py3-none-any.whl

# From PyPI
uv tool install weightlang        # or: pipx install weightlang
# CPU-only PyTorch on Linux (much smaller download):
uv tool install --index https://download.pytorch.org/whl/cpu weightlang

# From source, for development
git clone https://github.com/WeightLang/WeightLang && cd WeightLang
python -m venv .venv && .venv/bin/pip install -e '.[test]'

Requirements: Python ≥ 3.10, PyTorch ≥ 2.2, safetensors ≥ 0.4.

Quick start

weightc check   examples/xor.wgt               # parse and type-check, no build
weightc build   examples/xor.wgt -o build      # init → train → build/xor_mlp/
weightc run     build/xor_mlp --input '[[0,0],[0,1],[1,0],[1,1]]'
weightc inspect build/xor_mlp                  # I/O contract + where each tensor came from
weightc verify  build/xor_mlp                  # re-check hashes, shapes, loadability

built build/xor_mlp
  weights sha256 7969227a9c0e3528317e1cd22b8da766e5b1a7a705e0ba96078a86cde8296ba2
  tensors trained=4
  training loss 0.7066 -> 0.0001 on 4 rows (xor), train accuracy 1.00

From Python:

from weightlang import load_artifact

model = load_artifact("build/xor_mlp")      # verifies hashes and shapes
model.predict([[0, 1], [1, 1]])             # tensor([[0.9999], [0.0001]])
model.module                                # a plain torch.nn.Sequential

Artifacts can also be loaded with only torch + safetensors — see docs/artifact.md.

The language

wgt 0.2
use std/nn
use std/heads
model std_mlp
input x: f32[2]
output logits: f32[3]
layer body: nn.mlp(in=2, hidden=8, out=4)
layer head: heads.classifier(in=4, classes=3)
data train:
  [-2, 0] -> [0]
  [2, 0] -> [1]
  [0, 2] -> [2]
init seed=42
train data=train loss=cross_entropy optimizer=adam lr=0.03 epochs=200

• One statement per line, keyword first, key=value options. No expression language.
• Shapes are checked before anything runs; errors read xor.wgt:9: shape mismatch: ....
• Every tensor has an honest origin, recorded in the manifest:

A program without train still builds, but build, run, inspect and the Python loader all flag it, and importing an untrained tensor does not make it trained. Training and validation metrics are recorded separately when validate= is supplied.

Full reference: docs/language.md.

Standard library

use std/nn, use std/heads and use std/blocks provide MLPs, classification/regression heads and pre-norm residual blocks. They expand into named layers and contain no pretrained weights. Run weightc std to list signatures. See examples/residual.wgt and the std reference.

Reusing weights

Import a layer from another artifact, optionally pin its hash and freeze it:

init   seed=7
import hidden from "../build/xor_mlp" layer=hidden freeze
train  data=xnor loss=bce optimizer=adam lr=0.05 epochs=300

examples/xnor_reuse.wgt takes the trained hidden layer of xor_mlp, freezes it and trains only a new head for XNOR. The tests check that the imported tensors are bit-identical to the source and stayed frozen, that the source hash is recorded (and enforced with sha256=), and that mismatched layer sizes are rejected. This shows the reuse mechanism; with four training rows it does not show that reuse helps learning — a fresh network fits XNOR too.

Packages

Packages are identified by GitHub path, versions are Git tags, and weights are GitHub release assets — not files in Git history.

wgt.mod   require github.com/WeightLang/WeightLang/packages/gates v0.1.0
xnor.wgt  import hidden from "github.com/WeightLang/WeightLang/packages/gates/xor_mlp" layer=hidden freeze
wgt.sum   commit + sha256 of the index, manifest, weights and source — commit this file

weightc get   examples/remote_reuse                  # network: fetch, verify, write wgt.sum
weightc build examples/remote_reuse/xnor.wgt -o build # offline: cache checked against wgt.sum

weightc get resolves the tag to a commit, checks every asset's size and sha256 against the release's wgt.index.json, requires the shipped source.wgt to equal the file in the repository at that commit, and verifies the artifact. A later moved tag or replaced asset no longer matches wgt.sum and is an error.

Available packages:

• gates v0.2.0: six two-input gates, each correct on its complete truth table.
• iris v0.1.0: a small classifier with 29/30 held-out accuracy; data, license and limits.
• standard_reuse imports the new packages with a committed lock file.
• The example above remains pinned to gates v0.1.0 to exercise compatibility.

Publishing your own:

weightc publish path/to/pkg --version v0.1.0 -o dist   # prints the git tag + gh release commands

Design, lock-file format and known gaps: docs/packages.md.

Documentation

Development

.venv/bin/python -m pytest                                # no network
WEIGHTLANG_NETWORK_TESTS=1 .venv/bin/python -m pytest     # + fetch the real gates release
ruff check src tests && ruff format --check src tests

The suite covers parsing and line-numbered errors, a full XOR build, bit-exact outputs after save/reload, byte-stable rebuilds, tamper detection, loading with plain PyTorch, untrained labelling, weight reuse, and the package flow (publish, get, offline build, tampered assets, moved tags, mismatched source) against an in-memory fake of GitHub.

Release status

Limitations

• Small language: nested sequential and residual networks, one 1-D f32 input/output; no embedding, i64, convolutions, attention or general graphs.
• Imports copy whole layers or nested blocks, not tensor slices. Packages support direct requirements only, GitHub releases only, and trust-on-first-use hashes without signatures. Consumers use the publisher's prebuilt weights.
• Reproducibility: rebuilds are byte-identical on the same PyTorch version and CPU; across versions or hardware weights may differ, and the hashes will show it.
• Runtime: PyTorch only; no ONNX or other exports.
• Stability: 0.x — syntax and formats may change. The Windows installer has not been run on Windows yet.

License

MIT