namz (Python)

Lossless codec for NeuralAmpModeler .nam files.

A .nam is JSON whose bulk is one or more flat "weights" arrays written as ~20-character decimal strings — which the NAM engine loads into float32 anyway. .namz stores each weight as a 4-byte float32 instead: ≈5.5× smaller, bit-exact to what the engine computes, and deterministic (no compression → byte-identical across runs, platforms, and languages). A small readable header exposes tone/gear/device metadata without decoding the weights.

This package is a native Python port of the C++ reference and is byte-for-byte compatible with it and with every other port — it is validated against the shared conformance vectors (the cross-language TCK).

Install

pip install namz

Requires Python ≥ 3.9 and NumPy.

Library

import namz

nam = b'{"architecture":"WaveNet","weights":[0.5,-0.5,0.25]}'

blob = namz.pack(nam)                 # -> .namz bytes
assert namz.is_namz(blob)
assert namz.unpack(blob) == nam       # lossless to float32

# Stamp a readable metadata header (typed: "true"/"false" -> bool, digits -> int, else string;
# a leading zero keeps it a string, so an identifier such as "0012345" survives intact):
opts = namz.PackOptions(metadata={"tone_type": "hi-gain", "boost": "true", "device": "tube:1,pnp:1"})
blob = namz.pack(nam, opts)
namz.read_meta(blob)   # {'tone_type': 'hi-gain', 'boost': 'true', 'device': 'tube:1,pnp:1'} — no weight decode

API

unpack is total: for any input bytes it returns bytes (empty on failure) and never raises.

CLI

namz encode in.nam out.namz [--no-shuffle] [--set key=value ...]
namz decode in.namz out.nam
namz map    in.namz [--json]        # print the metadata header (no weight decode)
namz verify in.nam                  # pack->unpack round-trip check + ratio

(Also available as python -m namz.)

Guarantees

• Lossless to float32 — unpack(pack(x)) is bit-exact at any nesting depth, including -0.0, subnormals, and FLT_MAX.
• Deterministic — pack(x) is byte-identical across runs and platforms; the codec is idempotent.
• Robust — every malformed input (bad magic, unknown version/codec/dtype, truncation, trailing junk, a lying metaLen/numArrays, an over-cap body) is rejected cleanly.

Byte-match note

The skeleton is minified JSON with keys sorted ascending, matching the reference (nlohmann). It is validated byte-for-byte against the reference over the whole NAM domain (a large differential fuzz — config integers, simple decimals, non-ASCII, control chars, nesting). The weight payload itself is always exact float32, never text. Two documented edges, both outside the NAM domain:

• Non-finite weights (NaN/±Inf) are out of contract and are rejected, exactly as the reference rejects them.
• An integer literal outside [int64_min, uint64_max] in a non-weight field is coerced to a double, as nlohmann does; this is byte-exact for double-representable magnitudes (e.g. 2**64). For extreme 23+-digit integers nlohmann's own parser rounds imprecisely and may differ by one ULP — such values never occur in NAM config.

Development

pip install -e ".[test]"
pytest                      # runs the shared conformance vectors + property fuzz + adversarial suite

Versioned independently of the C++ reference; tracks wire format version 2.

License

MIT — see LICENSE. © 2026 Oleh Tsymaienko <oleh@darwinscat.com> & Alisa Lafoks <alisa@darwinscat.com> (Darwin's Cat).