veloxquant_mlx.dsa.ring_buffer module

Fixed-capacity circular buffer for streaming, FIFO-evicted token windows.

Implements RingBuffer, a generic O(1)-append circular buffer with negative indexing and oldest-first iteration, used wherever a component needs a bounded sliding window over recent elements (e.g. token or key/value history) that silently evicts the oldest entry once full rather than growing unbounded.

class veloxquant_mlx.dsa.ring_buffer.RingBuffer(capacity)

Bases: Generic[T]

Fixed-capacity circular buffer with O(1) append and index access.

When full, the oldest element is silently overwritten (FIFO eviction). Supports negative indexing (buf[-1] is the most recently appended item).

Internal layout:

_data: list of length _capacity, pre-filled with None. _head: index in _data of the oldest element. _size: number of currently live elements.

Parameters:

capacity (int) – Maximum number of elements the buffer can hold. Must be >= 1.

Raises:

ValueError – If capacity < 1.

append(item)

Append an item to the buffer.

If the buffer is full the oldest item is evicted and returned.

Parameters:

item (TypeVar(T)) – Element to append.

Return type:

Optional[TypeVar(T)]

Returns:

The evicted element if the buffer was full, otherwise None.

is_full()

Return True if the buffer is at capacity.

Return type:

bool

to_list()

Return all elements as a plain list (oldest first).

Return type:

list[TypeVar(T)]

Returns:

List of length len(self).

to_stacked()

Stack all stored MLX arrays along axis 0.

Only valid when T = mx.array. Uses mx.stack for efficiency.

Return type:

array

Returns:

Single MLX array of shape (size, *element_shape).

Raises:

RuntimeError – If the buffer is empty.