Crate nuvec_io 

Reading and writing arrays: safetensors (MLX’s checkpoint format) and NumPy’s .npy, any tree of arrays by path (save, load_into), the IDX format (MNIST) and a minimal json parser for model files. Files whose tensors are aligned (files nuvec writes are) are memory-mapped without a copy; others, such as mlx-community checkpoints with unpadded headers, are read once at load, in parallel, without being mapped.

Stability: no promise when this crate is depended on directly; depend on nuvec, whose re-exports are semver-tracked.

Status: pre-alpha.

Modules

json

A minimal JSON parser (RFC 8259) for safetensors headers and model files (configs, tokenizers), so that no serialization framework is needed.

Structs

Footprint

What loading safetensors checkpoints holds in the GPU allocator, in bytes (see safetensors_footprint). Compare with nuvec_gpu::MemoryStats’s mapped, active and peak_with_mapped.

SafeTensors

The tensors and metadata of a safetensors file.

SaveHandle

A background safetensors write (save_safetensors_async). SaveHandle::wait returns its result; dropping the handle waits for the write to finish.

Constants

VERSION

The version of this crate.

Functions

load_into

Reads a file written by save into tree by path, strictly: every leaf must be in the file with its shape, and nothing else (loaded dtypes are kept). On any problem the error lists every one and tree is unchanged.

load_npy

Loads a .npy file as a view of the memory-mapped file.

load_safetensors

Loads a safetensors file. The tensors are views of the memory-mapped file or, if they are not aligned to their element sizes (MLX writes headers without padding), of one buffer they are read into with parallel positioned reads (the file is then not mapped).

load_safetensors_filtered

load_safetensors, returning only the tensors whose names keep accepts. In files that are read rather than mapped (misaligned ones, as MLX writes them), the others are not read at all: loading a language model from a multimodal checkpoint, say, skips the vision weights.

parse_idx

Parses an IDX file’s bytes. Element types map to uint8, int8, int16, int32, float32 and float64.

read_idx

Reads an (uncompressed) IDX file.

safetensors_footprint

What loading a safetensors file, or every *.safetensors file of a directory, will hold, from their headers only (ordinary reads; nothing is mapped, copied or wired): the bytes kept mapped, the bytes copied, and the transient peak of the load.

save

Writes the leaves of tree as a safetensors file, each named by its path (MLX’s tree_flatten names), evaluating them.

save_npy

Saves a (evaluating it) as a C-order .npy file (version 1). bfloat16 has no NumPy type and is rejected.

save_safetensors

Saves tensors (evaluating them) and metadata as a safetensors file, written to path.tmp and renamed into place.

save_safetensors_async

save_safetensors in the background, for snapshots taken while work continues (a KV cache or recurrent state copied with copy, say): the arrays are submitted for evaluation (nuvec_core::async_eval) and returned at once with a handle; a background thread waits for them and writes path.tmp, renamed into place on success. The file is byte-identical to save_safetensors’s. The handle holds the arrays until the write is done, so an in-place update of one of them copies instead of writing into memory being saved.