Struct KvStreamEncoder 

pub struct KvStreamEncoder { /* private fields */ }

Incremental/streaming KV-cache encoder.

Construct with KvStreamEncoder::new, feed tokens one at a time with KvStreamEncoder::append_token, and finalize with KvStreamEncoder::finish to obtain a KvEncodedTensorV1.

The encoder accumulates a BLAKE3 source digest over all appended vectors using an incremental blake3::Hasher. Pages are buffered as pending (blocks + metadata) and materialized into KvEncodedPageV1 objects in finish() once the full source digest is available, ensuring that page digests match the batch super::codec::encode_kv_tensor path.

Implementations

impl KvStreamEncoder

pub fn new( shape: KvTensorShapeV1, layout: KvCacheLayoutV1, profile: KvCompressionProfileV1, ) -> Result<Self>

Create a new streaming encoder.

Validates the shape, layout, and profile, then builds a quantizer from the profile. The source digest accumulator is initialized with the domain tag and expected total element count so that incremental hashing produces the same result as super::receipt::kv_tensor_digest.

Currently requires batch = 1, layers = 1, kv_heads = 1.

pub fn append_token( &mut self, key_vector: &[f32], value_vector: &[f32], ) -> Result<AppendReceipt>

Append one token’s key and value vectors.

Both vectors must have length head_dim and contain only finite values. Only the vector matching shape.role is encoded into a block; the other is reported as "raw" in the receipt with zero compressed bytes (it is not stored in this encoder’s output).

When the current page reaches tokens_per_page blocks, the blocks are flushed to a pending page buffer (materialized in finish()).

pub fn finish(self) -> Result<KvEncodedTensorV1>

Finalize the stream and produce the encoded tensor.

Flushes any remaining blocks as the final page, computes the source digest, materializes all pending pages, and builds the compression receipt.

Returns an error if the number of appended tokens does not match shape.tokens.