Struct AprV2StreamingWriter 

pub struct AprV2StreamingWriter { /* private fields */ }

Streaming APR v2 writer — writes tensors to disk incrementally (realizar#136).

Unlike AprV2Writer which accumulates all tensor data in RAM, this writer streams tensor data to a temp file, keeping only the index entries (~KB) in memory. Peak RAM = largest single tensor.

Architecture

1. Tensor data written to temp file in insertion order, 64B aligned
2. Index entries (name, dtype, shape, offset, size) accumulated in Vec (~KB)
3. finalize() writes: header + metadata + index, then copies data from temp file

Index entries are sorted by name during finalize() (APR v2 contract). Data in the temp file stays in insertion order; index offsets point correctly.

Implementations

impl AprV2StreamingWriter

pub fn new(metadata: AprV2Metadata) -> Result<Self, V2FormatError>

Create a new streaming writer.

Errors

Returns error if the temp file cannot be created.

pub fn add_tensor( &mut self, name: impl Into<String>, dtype: TensorDType, shape: Vec<usize>, data: &[u8], ) -> Result<(), V2FormatError>

Add a tensor, writing its data to the temp file immediately.

Only the index entry (~100 bytes) is kept in memory. The data slice can be dropped after this call returns.

Errors

Returns error if writing to the temp file fails.

pub fn add_f32_tensor( &mut self, name: impl Into<String>, shape: Vec<usize>, data: &[f32], ) -> Result<(), V2FormatError>

Add f32 tensor (streaming).

Errors

Returns error if writing fails.

pub fn add_raw_f16_tensor( &mut self, name: impl Into<String>, shape: Vec<usize>, data: &[u8], is_bf16: bool, ) -> Result<(), V2FormatError>

Add raw BF16/F16 bytes directly (zero conversion, streaming).

Errors

Returns error if writing fails.

pub fn add_f16_tensor( &mut self, name: impl Into<String>, shape: Vec<usize>, data: &[f32], ) -> Result<(), V2FormatError>

Add f16 tensor (converts f32 → f16, streaming).

GH-478: Enables streaming quantization for sharded imports.

Errors

Returns error if writing fails.

pub fn add_q8_tensor( &mut self, name: impl Into<String>, shape: Vec<usize>, data: &[f32], ) -> Result<(), V2FormatError>

Add Q8 tensor (8-bit symmetric quantization, streaming).

GH-478: Enables streaming quantization for sharded imports. Format: [scale: f32 (4 bytes)] + [quantized: i8 × n]

Errors

Returns error if writing fails.

pub fn add_q4_tensor( &mut self, name: impl Into<String>, shape: Vec<usize>, data: &[f32], ) -> Result<(), V2FormatError>

Add Q4 tensor (4-bit symmetric quantization, block-wise, streaming).

GH-478: Enables streaming quantization for sharded imports. Format: For each block of 32 values: [block_scale: f16 (2 bytes)] + [packed nibbles: 16 bytes]

Errors

Returns error if writing fails.

pub fn add_q4k_raw_tensor( &mut self, name: impl Into<String>, shape: Vec<usize>, raw_data: &[u8], ) -> Result<(), V2FormatError>

Add raw Q4_K tensor (GGUF-compatible super-block format, streaming).

GH-478: Enables streaming quantization for sharded imports.

Errors

Returns error if writing fails.

pub fn tensor_count(&self) -> usize

Number of tensors added so far.

pub fn data_bytes_written(&self) -> u64

Total bytes of tensor data written to temp file.

pub fn finalize(self, output_path: &Path) -> Result<(), V2FormatError>

Finalize and write the complete APR v2 file.

Writes header + metadata + tensor index + tensor data (streamed from temp file). The temp file is consumed and deleted automatically.

Errors

Returns error if assembly or writing fails.