NeuronScope
ConceptStablesince v0.9.2

Serialization

The .nsz format — a zipped columnar container with a stable schema, self-describing headers, and a versioned reader contract.

Audience: Users producing or consuming artifactsRead: 7 minEdit on GitHub

Artifacts are the currency of NeuronScope. They are portable, self-describing, and cheap to inspect. The .nsz format is engineered specifically for recorded activations — narrow scope, hard guarantees.

Why a new format

  • Content-addressed. The header embeds every input fingerprint so a reader can validate provenance without executing user code.
  • Columnar. Per-layer activations are stored as contiguous blocks, so a partial read is O(layer) rather than O(artifact).
  • Zipped, not proprietary. The container is a normal zip file. A curious reader can crack it open with any zip tool and see the JSON header.

On-disk layout

·text
run.nsz
├── header.json           # fingerprints, schema version, index
├── plan.json             # frozen recording plan
├── env.json              # captured environment
├── observations/
│   ├── encoder.layer.0.output.f32
│   ├── encoder.layer.1.output.f32
│   └── ...
└── SIGNATURE             # BLAKE3 of the container

Compatibility

Reading and writing

io.py·
·python
import neuronscope as ns

art = ns.Artifact.open("run.nsz")
print(art.fingerprint, art.plan.layers)
tensor = art.tensor("encoder.layer.0.output")
Related