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.

TensorInfo

A tensor of a safetensors header (safetensors_tensors).

Constants

VERSION

The version of this crate.

Functions

align_safetensors

Writes a copy of the safetensors file src at dst in which every tensor starts at a multiple of 256 bytes of the file (the fastest placement measured), with the same tensors, bit for bit, in the same order, and the same metadata. Gaps are filled with padding tensors that nuvec never loads, so dst is a valid safetensors file that nuvec maps without a copy. Tensors are streamed with positioned reads (no whole-file copy in memory); dst is written through a temporary file and a rename.

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_cached

load_safetensors_filtered through an aligned copy: an aligned file is loaded (mapped) as it is; a misaligned one (mlx-community checkpoints) is loaded from an aligned copy in cache_dir (align_safetensors), written on first use and rewritten when the source’s size or modification time changes, so later loads map it without a copy. If the copy cannot be written (no room, no permission), the file is read as usual.

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.

safetensors_footprint_filtered

What load_safetensors_filtered with keep will hold, as safetensors_footprint (a file, or every *.safetensors file of a directory): copied counts only the kept tensors of misaligned files, and only the kept tensors’ pages of aligned files.

safetensors_tensors

The tensors of a safetensors file, from its header alone (no tensor data is read or mapped), in file order.

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.