# `vllm_mlx.paged_cache`

Paged KV Cache Manager for vllm-mlx.

[View the complete module source at #L1-L1197](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1-L1197).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: vllm_mlx.paged_cache
    options:
      members:
        - logger
        - BlockHash
        - compute_block_hash
        - CacheBlock
        - KVCacheBlock
        - FreeKVCacheBlockQueue
        - BlockHashToBlockMap
        - BlockTable
        - CacheStats
        - PagedCacheManager
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-vllm_mlx.paged_cache.compute_block_hash" markdown="1">
<summary><code>vllm_mlx.paged_cache.compute_block_hash</code> · function</summary>

```python
vllm_mlx.paged_cache.compute_block_hash(parent_hash: Optional[BlockHash], token_ids: List[int], extra_keys: Optional[Tuple[Any, ...]] = None) -> BlockHash
```

Compute hash for a block based on its content and parent block.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `parent_hash` | `Optional[BlockHash]` | `yes` | `none` | Hash of the previous block, or None for first block |
| `token_ids` | `List[int]` | `yes` | `none` | Token IDs in this block |
| `extra_keys` | `Optional[Tuple[Any, ...]]` | `no` | `None` | Additional keys (e.g., LoRA, multimodal) |

**Returns**

- Type: `BlockHash`
- Direct return expressions: `BlockHash(hasher.digest())`

**Exceptions and behavior**

Function `compute_block_hash` calls `hashlib.sha256`, `hasher.update`, `bytes`, `str`; returns `BlockHash(hasher.digest())`.
No direct `raise` statement appears in this definition.

[View source #L40-L75](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L40-L75).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.CacheBlock" markdown="1">
<summary><code>vllm_mlx.paged_cache.CacheBlock</code> · class</summary>

```python
vllm_mlx.paged_cache.CacheBlock(block_id: int, ref_count: int = 0, block_hash: Optional[BlockHash] = None, prev_free_block: Optional['CacheBlock'] = None, next_free_block: Optional['CacheBlock'] = None, is_null: bool = False, cache_data: Optional[List[Tuple[Any, Any]]] = None, token_count: int = 0, hash_value: Optional[str] = None, last_access: float = field(default_factory=time.time))
```

KV cache block metadata following vLLM's design.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_id` | `int` | `yes` | `none` | Required constructor field. |
| `ref_count` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `block_hash` | `Optional[BlockHash]` | `no` | `None` | Optional constructor field; defaults to `None`. |
| `prev_free_block` | `Optional['CacheBlock']` | `no` | `None` | Optional constructor field; defaults to `None`. |
| `next_free_block` | `Optional['CacheBlock']` | `no` | `None` | Optional constructor field; defaults to `None`. |
| `is_null` | `bool` | `no` | `False` | Optional constructor field; defaults to `False`. |
| `cache_data` | `Optional[List[Tuple[Any, Any]]]` | `no` | `None` | Optional constructor field; defaults to `None`. |
| `token_count` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `hash_value` | `Optional[str]` | `no` | `None` | Optional constructor field; defaults to `None`. |
| `last_access` | `float` | `no` | `field(default_factory=time.time)` | Optional constructor field; defaults to `field(default_factory=time.time)`. |

**Returns**

- Constructs: `vllm_mlx.paged_cache.CacheBlock`

**Exceptions and behavior**

Class `CacheBlock` declares 5 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L84-L146](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L84-L146).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.CacheBlock.is_full" markdown="1">
<summary><code>vllm_mlx.paged_cache.CacheBlock.is_full</code> · method</summary>

```python
vllm_mlx.paged_cache.CacheBlock.is_full(block_size: int) -> bool
```

Check if block is at capacity.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_size` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `bool`
- Direct return expressions: `self.token_count >= block_size`

**Exceptions and behavior**

Method `CacheBlock.is_full` returns `self.token_count >= block_size`.
No direct `raise` statement appears in this definition.

[View source #L123-L125](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L123-L125).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.CacheBlock.is_shared" markdown="1">
<summary><code>vllm_mlx.paged_cache.CacheBlock.is_shared</code> · method</summary>

```python
vllm_mlx.paged_cache.CacheBlock.is_shared() -> bool
```

Check if block is shared (ref_count > 1).

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `bool`
- Direct return expressions: `self.ref_count > 1`

**Exceptions and behavior**

Method `CacheBlock.is_shared` returns `self.ref_count > 1`.
No direct `raise` statement appears in this definition.

[View source #L127-L129](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L127-L129).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.CacheBlock.reset_hash" markdown="1">
<summary><code>vllm_mlx.paged_cache.CacheBlock.reset_hash</code> · method</summary>

```python
vllm_mlx.paged_cache.CacheBlock.reset_hash() -> None
```

Reset block hash when evicted from cache.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `CacheBlock.reset_hash` updates `self.block_hash`, `self.hash_value`.
No direct `raise` statement appears in this definition.

[View source #L131-L134](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L131-L134).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.CacheBlock.touch" markdown="1">
<summary><code>vllm_mlx.paged_cache.CacheBlock.touch</code> · method</summary>

```python
vllm_mlx.paged_cache.CacheBlock.touch() -> None
```

Update last access time.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `CacheBlock.touch` updates `self.last_access`; calls `time.time`.
No direct `raise` statement appears in this definition.

[View source #L136-L138](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L136-L138).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.CacheBlock.__repr__" markdown="1">
<summary><code>vllm_mlx.paged_cache.CacheBlock.__repr__</code> · method</summary>

```python
vllm_mlx.paged_cache.CacheBlock.__repr__() -> str
```

Method `CacheBlock.__repr__` returns `f'CacheBlock(id={self.block_id}, ref={self.ref_count}, tokens={self.token_count}, prev={prev_id}, next={next_id})'`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `str`
- Direct return expressions: `f'CacheBlock(id={self.block_id}, ref={self.ref_count}, tokens={self.token_count}, prev={prev_id}, next={next_id})'`

**Exceptions and behavior**

Method `CacheBlock.__repr__` returns `f'CacheBlock(id={self.block_id}, ref={self.ref_count}, tokens={self.token_count}, prev={prev_id}, next={next_id})'`.
No direct `raise` statement appears in this definition.

[View source #L140-L146](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L140-L146).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue" markdown="1">
<summary><code>vllm_mlx.paged_cache.FreeKVCacheBlockQueue</code> · class</summary>

```python
vllm_mlx.paged_cache.FreeKVCacheBlockQueue(blocks: List[CacheBlock])
```

Doubly linked list of free blocks following vLLM's design.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `blocks` | `List[CacheBlock]` | `yes` | `none` | List of all CacheBlock objects |

**Returns**

- Constructs: `vllm_mlx.paged_cache.FreeKVCacheBlockQueue`

**Exceptions and behavior**

Class `FreeKVCacheBlockQueue` declares 7 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L158-L337](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L158-L337).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.__init__" markdown="1">
<summary><code>vllm_mlx.paged_cache.FreeKVCacheBlockQueue.__init__</code> · method</summary>

```python
vllm_mlx.paged_cache.FreeKVCacheBlockQueue.__init__(blocks: List[CacheBlock]) -> None
```

Initialize queue with all blocks as free.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `blocks` | `List[CacheBlock]` | `yes` | `none` | List of all CacheBlock objects |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `FreeKVCacheBlockQueue.__init__` updates `self.num_free_blocks`, `self.fake_head`, `self.fake_tail`, `self.fake_head.next_free_block`; calls `len`, `range`, `CacheBlock`.
No direct `raise` statement appears in this definition.

[View source #L174-L201](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L174-L201).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.popleft" markdown="1">
<summary><code>vllm_mlx.paged_cache.FreeKVCacheBlockQueue.popleft</code> · method</summary>

```python
vllm_mlx.paged_cache.FreeKVCacheBlockQueue.popleft() -> CacheBlock
```

Pop and return the first (LRU) free block.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `CacheBlock`
- Direct return expressions: `block`

**Exceptions and behavior**

Method `FreeKVCacheBlockQueue.popleft` updates `self.fake_head.next_free_block`, `self.num_free_blocks`; calls `ValueError`; can raise `ValueError`; returns `block`.
Directly raised exceptions: `ValueError`.

[View source #L203-L225](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L203-L225).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.popleft_n" markdown="1">
<summary><code>vllm_mlx.paged_cache.FreeKVCacheBlockQueue.popleft_n</code> · method</summary>

```python
vllm_mlx.paged_cache.FreeKVCacheBlockQueue.popleft_n(n: int) -> List[CacheBlock]
```

Pop n blocks from the front.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `n` | `int` | `yes` | `none` | Number of blocks to allocate |

**Returns**

- Type: `List[CacheBlock]`
- Direct return expressions: `[]`; `result`

**Exceptions and behavior**

Method `FreeKVCacheBlockQueue.popleft_n` updates `self.fake_head.next_free_block`, `self.num_free_blocks`; calls `range`, `result.append`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L227-L265](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L227-L265).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.remove" markdown="1">
<summary><code>vllm_mlx.paged_cache.FreeKVCacheBlockQueue.remove</code> · method</summary>

```python
vllm_mlx.paged_cache.FreeKVCacheBlockQueue.remove(block: CacheBlock) -> None
```

Remove a block from the middle of the queue.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block` | `CacheBlock` | `yes` | `none` | Block to remove |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `FreeKVCacheBlockQueue.remove` updates `self.num_free_blocks`; calls `RuntimeError`; can raise `RuntimeError`.
Directly raised exceptions: `RuntimeError`.

[View source #L267-L288](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L267-L288).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.append" markdown="1">
<summary><code>vllm_mlx.paged_cache.FreeKVCacheBlockQueue.append</code> · method</summary>

```python
vllm_mlx.paged_cache.FreeKVCacheBlockQueue.append(block: CacheBlock) -> None
```

Append a block to the end (MRU position).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block` | `CacheBlock` | `yes` | `none` | Block to append |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `FreeKVCacheBlockQueue.append` updates `self.fake_tail.prev_free_block`, `self.num_free_blocks`.
No direct `raise` statement appears in this definition.

[View source #L290-L305](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L290-L305).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.append_n" markdown="1">
<summary><code>vllm_mlx.paged_cache.FreeKVCacheBlockQueue.append_n</code> · method</summary>

```python
vllm_mlx.paged_cache.FreeKVCacheBlockQueue.append_n(blocks: List[CacheBlock]) -> None
```

Append multiple blocks to the end.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `blocks` | `List[CacheBlock]` | `yes` | `none` | Blocks to append (in order) |

**Returns**

- Type: `None`
- Direct return expressions: `None`

**Exceptions and behavior**

Method `FreeKVCacheBlockQueue.append_n` updates `self.fake_tail.prev_free_block`, `self.num_free_blocks`; calls `len`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L307-L328](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L307-L328).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.get_all_free_blocks" markdown="1">
<summary><code>vllm_mlx.paged_cache.FreeKVCacheBlockQueue.get_all_free_blocks</code> · method</summary>

```python
vllm_mlx.paged_cache.FreeKVCacheBlockQueue.get_all_free_blocks() -> List[CacheBlock]
```

Get all free blocks (for testing).

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `List[CacheBlock]`
- Direct return expressions: `result`

**Exceptions and behavior**

Method `FreeKVCacheBlockQueue.get_all_free_blocks` calls `result.append`; returns `result`.
No direct `raise` statement appears in this definition.

[View source #L330-L337](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L330-L337).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockHashToBlockMap" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockHashToBlockMap</code> · class</summary>

```python
vllm_mlx.paged_cache.BlockHashToBlockMap()
```

Cache mapping block hashes to blocks for prefix caching.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Constructs: `vllm_mlx.paged_cache.BlockHashToBlockMap`

**Exceptions and behavior**

Class `BlockHashToBlockMap` declares 6 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L345-L407](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L345-L407).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockHashToBlockMap.__init__" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockHashToBlockMap.__init__</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockHashToBlockMap.__init__() -> None
```

Method `BlockHashToBlockMap.__init__` updates `self._cache`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `BlockHashToBlockMap.__init__` updates `self._cache`.
No direct `raise` statement appears in this definition.

[View source #L353-L354](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L353-L354).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockHashToBlockMap.get_block" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockHashToBlockMap.get_block</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockHashToBlockMap.get_block(block_hash: BlockHash) -> Optional[CacheBlock]
```

Get any block with the given hash.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_hash` | `BlockHash` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Optional[CacheBlock]`
- Direct return expressions: `None`; `blocks`; `next(iter(blocks.values()))`

**Exceptions and behavior**

Method `BlockHashToBlockMap.get_block` calls `self._cache.get`, `isinstance`, `next`, `iter`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L356-L365](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L356-L365).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockHashToBlockMap.insert" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockHashToBlockMap.insert</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockHashToBlockMap.insert(block_hash: BlockHash, block: CacheBlock) -> None
```

Insert a block into the cache.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_hash` | `BlockHash` | `yes` | `none` | Required positional or keyword input. |
| `block` | `CacheBlock` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `BlockHashToBlockMap.insert` calls `self._cache.get`, `isinstance`.
No direct `raise` statement appears in this definition.

[View source #L367-L378](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L367-L378).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockHashToBlockMap.pop" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockHashToBlockMap.pop</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockHashToBlockMap.pop(block_hash: BlockHash, block_id: int) -> Optional[CacheBlock]
```

Remove and return a specific block from the cache.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_hash` | `BlockHash` | `yes` | `none` | Required positional or keyword input. |
| `block_id` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Optional[CacheBlock]`
- Direct return expressions: `None`; `blocks`; `block`

**Exceptions and behavior**

Method `BlockHashToBlockMap.pop` calls `self._cache.pop`, `isinstance`, `blocks.pop`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L380-L399](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L380-L399).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockHashToBlockMap.__len__" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockHashToBlockMap.__len__</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockHashToBlockMap.__len__() -> int
```

Method `BlockHashToBlockMap.__len__` calls `len`; returns `len(self._cache)`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `len(self._cache)`

**Exceptions and behavior**

Method `BlockHashToBlockMap.__len__` calls `len`; returns `len(self._cache)`.
No direct `raise` statement appears in this definition.

[View source #L401-L402](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L401-L402).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockHashToBlockMap.clear" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockHashToBlockMap.clear</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockHashToBlockMap.clear() -> None
```

Remove every block-hash mapping without mutating the blocks.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `BlockHashToBlockMap.clear` calls `self._cache.clear`.
No direct `raise` statement appears in this definition.

[View source #L404-L407](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L404-L407).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockTable" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockTable</code> · class</summary>

```python
vllm_mlx.paged_cache.BlockTable(request_id: str, block_ids: List[int] = field(default_factory=list), num_tokens: int = 0)
```

Per-request block table mapping logical to physical blocks.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `request_id` | `str` | `yes` | `none` | Required constructor field. |
| `block_ids` | `List[int]` | `no` | `field(default_factory=list)` | Optional constructor field; defaults to `field(default_factory=list)`. |
| `num_tokens` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |

**Returns**

- Constructs: `vllm_mlx.paged_cache.BlockTable`

**Exceptions and behavior**

Class `BlockTable` declares 3 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L416-L447](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L416-L447).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockTable.add_block" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockTable.add_block</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockTable.add_block(block_id: int, num_tokens: int) -> None
```

Add a block to the table.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_id` | `int` | `yes` | `none` | Required positional or keyword input. |
| `num_tokens` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `BlockTable.add_block` updates `self.num_tokens`; calls `self.block_ids.append`.
No direct `raise` statement appears in this definition.

[View source #L433-L436](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L433-L436).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockTable.__len__" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockTable.__len__</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockTable.__len__() -> int
```

Method `BlockTable.__len__` calls `len`; returns `len(self.block_ids)`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `len(self.block_ids)`

**Exceptions and behavior**

Method `BlockTable.__len__` calls `len`; returns `len(self.block_ids)`.
No direct `raise` statement appears in this definition.

[View source #L438-L439](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L438-L439).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.BlockTable.copy" markdown="1">
<summary><code>vllm_mlx.paged_cache.BlockTable.copy</code> · method</summary>

```python
vllm_mlx.paged_cache.BlockTable.copy(new_request_id: str) -> 'BlockTable'
```

Create a copy with new request ID.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `new_request_id` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `'BlockTable'`
- Direct return expressions: `BlockTable(request_id=new_request_id, block_ids=self.block_ids.copy(), num_tokens=self.num_tokens)`

**Exceptions and behavior**

Method `BlockTable.copy` calls `BlockTable`, `self.block_ids.copy`; returns `BlockTable(request_id=new_request_id, block_ids=self.block_ids.copy(), num_tokens=self.num_tokens)`.
No direct `raise` statement appears in this definition.

[View source #L441-L447](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L441-L447).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.CacheStats" markdown="1">
<summary><code>vllm_mlx.paged_cache.CacheStats</code> · class</summary>

```python
vllm_mlx.paged_cache.CacheStats(total_blocks: int = 0, allocated_blocks: int = 0, free_blocks: int = 0, shared_blocks: int = 0, total_tokens_cached: int = 0, cache_hits: int = 0, cache_misses: int = 0, cow_copies: int = 0, evictions: int = 0)
```

Statistics for cache monitoring.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `total_blocks` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `allocated_blocks` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `free_blocks` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `shared_blocks` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `total_tokens_cached` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `cache_hits` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `cache_misses` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `cow_copies` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `evictions` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |

**Returns**

- Constructs: `vllm_mlx.paged_cache.CacheStats`

**Exceptions and behavior**

Class `CacheStats` declares 0 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L456-L467](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L456-L467).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager</code> · class</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager(block_size: int = 64, max_blocks: int = 1000, enable_caching: bool = True)
```

Paged KV cache manager following vLLM's BlockPool architecture.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_size` | `int` | `no` | `64` | Number of tokens per block (default: 64) |
| `max_blocks` | `int` | `no` | `1000` | Maximum number of blocks to allocate (default: 1000) |
| `enable_caching` | `bool` | `no` | `True` | Whether to enable prefix caching (default: True) |

**Returns**

- Constructs: `vllm_mlx.paged_cache.PagedCacheManager`

**Exceptions and behavior**

Class `PagedCacheManager` declares 34 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L475-L1197](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L475-L1197).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.__init__" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.__init__</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.__init__(block_size: int = 64, max_blocks: int = 1000, enable_caching: bool = True) -> not annotated
```

Method `PagedCacheManager.__init__` updates `self.block_size`, `self.max_blocks`, `self.enable_caching`, `self.blocks`; calls `CacheBlock`, `range`, `FreeKVCacheBlockQueue`, `BlockHashToBlockMap`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_size` | `int` | `no` | `64` | Optional positional or keyword input; defaults to `64`. |
| `max_blocks` | `int` | `no` | `1000` | Optional positional or keyword input; defaults to `1000`. |
| `enable_caching` | `bool` | `no` | `True` | Optional positional or keyword input; defaults to `True`. |

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Method `PagedCacheManager.__init__` updates `self.block_size`, `self.max_blocks`, `self.enable_caching`, `self.blocks`; calls `CacheBlock`, `range`, `FreeKVCacheBlockQueue`, `BlockHashToBlockMap`.
No direct `raise` statement appears in this definition.

[View source #L491-L540](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L491-L540).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.allocate_block" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.allocate_block</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.allocate_block() -> Optional[CacheBlock]
```

Allocate a new cache block.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `Optional[CacheBlock]`
- Direct return expressions: `None`; `block`

**Exceptions and behavior**

Method `PagedCacheManager.allocate_block` updates `self.stats.allocated_blocks`, `self.stats.free_blocks`; calls `logger.warning`, `self.free_block_queue.popleft`, `self._maybe_evict_cached_block`, `block.touch`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L546-L571](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L546-L571).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.get_new_blocks" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.get_new_blocks</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.get_new_blocks(num_blocks: int) -> List[CacheBlock]
```

Allocate multiple blocks at once (vLLM style).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `num_blocks` | `int` | `yes` | `none` | Number of blocks to allocate |

**Returns**

- Type: `List[CacheBlock]`
- Direct return expressions: `blocks`

**Exceptions and behavior**

Method `PagedCacheManager.get_new_blocks` updates `self.stats.allocated_blocks`, `self.stats.free_blocks`; calls `ValueError`, `self.free_block_queue.popleft_n`, `self._maybe_evict_cached_block`, `block.touch`; can raise `ValueError`; returns `blocks`.
Directly raised exceptions: `ValueError`.

[View source #L573-L606](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L573-L606).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager._maybe_evict_cached_block" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager._maybe_evict_cached_block</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager._maybe_evict_cached_block(block: CacheBlock) -> bool
```

Evict a block from the hash cache if present.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block` | `CacheBlock` | `yes` | `none` | Block to evict |

**Returns**

- Type: `bool`
- Direct return expressions: `False`; `True`

**Exceptions and behavior**

Method `PagedCacheManager._maybe_evict_cached_block` updates `self.stats.evictions`; calls `self.cached_block_hash_to_block.pop`, `block.reset_hash`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L608-L634](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L608-L634).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.free_block" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.free_block</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.free_block(block_id: int) -> bool
```

Free a cache block (decrements ref_count, frees if 0).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_id` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `bool`
- Direct return expressions: `False`; `True`

**Exceptions and behavior**

Method `PagedCacheManager.free_block` updates `self.stats.allocated_blocks`, `self.stats.free_blocks`, `self.stats.total_tokens_cached`; calls `logger.warning`, `self.free_block_queue.append`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L636-L667](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L636-L667).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.free_blocks" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.free_blocks</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.free_blocks(blocks: Iterable[CacheBlock]) -> None
```

Free multiple blocks (vLLM style).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `blocks` | `Iterable[CacheBlock]` | `yes` | `none` | Blocks to free (in eviction order) |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `PagedCacheManager.free_blocks` updates `self.stats.allocated_blocks`, `self.stats.free_blocks`, `self.stats.total_tokens_cached`; calls `list`, `to_free.append`, `self.free_block_queue.append_n`.
No direct `raise` statement appears in this definition.

[View source #L669-L696](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L669-L696).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.touch" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.touch</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.touch(blocks: Iterable[CacheBlock]) -> None
```

Touch blocks to prevent eviction (cache hit, vLLM style).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `blocks` | `Iterable[CacheBlock]` | `yes` | `none` | Blocks to touch |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `PagedCacheManager.touch` updates `self.stats.free_blocks`, `self.stats.allocated_blocks`; calls `self.free_block_queue.remove`, `block.touch`.
No direct `raise` statement appears in this definition.

[View source #L698-L720](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L698-L720).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.increment_ref" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.increment_ref</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.increment_ref(block_id: int) -> bool
```

Increment reference count for a block.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_id` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `bool`
- Direct return expressions: `False`; `True`

**Exceptions and behavior**

Method `PagedCacheManager.increment_ref` updates `self.stats.shared_blocks`; calls `block.touch`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L726-L739](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L726-L739).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.decrement_ref" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.decrement_ref</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.decrement_ref(block_id: int) -> bool
```

Decrement reference count (alias for free_block).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_id` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `bool`
- Direct return expressions: `self.free_block(block_id)`

**Exceptions and behavior**

Method `PagedCacheManager.decrement_ref` calls `self.free_block`; returns `self.free_block(block_id)`.
No direct `raise` statement appears in this definition.

[View source #L741-L743](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L741-L743).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.get_cached_block" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.get_cached_block</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.get_cached_block(block_hash: BlockHash) -> Optional[CacheBlock]
```

Get a cached block by its hash (vLLM style).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block_hash` | `BlockHash` | `yes` | `none` | Content hash of the block |

**Returns**

- Type: `Optional[CacheBlock]`
- Direct return expressions: `None`; `block`

**Exceptions and behavior**

Method `PagedCacheManager.get_cached_block` updates `self.stats.cache_hits`, `self.stats.cache_misses`; calls `self.cached_block_hash_to_block.get_block`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L749-L768](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L749-L768).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.cache_full_blocks" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.cache_full_blocks</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.cache_full_blocks(blocks: List[CacheBlock], token_ids: List[int], num_cached_blocks: int, num_full_blocks: int) -> None
```

Cache full blocks for prefix caching (vLLM style).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `blocks` | `List[CacheBlock]` | `yes` | `none` | All blocks for the request |
| `token_ids` | `List[int]` | `yes` | `none` | All token IDs for the request |
| `num_cached_blocks` | `int` | `yes` | `none` | Number of blocks already cached |
| `num_full_blocks` | `int` | `yes` | `none` | Number of full blocks to cache |

**Returns**

- Type: `None`
- Direct return expressions: `None`

**Exceptions and behavior**

Method `PagedCacheManager.cache_full_blocks` calls `range`, `compute_block_hash`, `len`, `self.cached_block_hash_to_block.insert`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L770-L824](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L770-L824).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.get_computed_blocks" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.get_computed_blocks</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.get_computed_blocks(token_ids: List[int]) -> Tuple[List[CacheBlock], int]
```

Find cached blocks for a token prefix (vLLM style).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `token_ids` | `List[int]` | `yes` | `none` | Token IDs to look up |

**Returns**

- Type: `Tuple[List[CacheBlock], int]`
- Direct return expressions: `([], 0)`; `(cached_blocks, num_cached_tokens)`

**Exceptions and behavior**

Method `PagedCacheManager.get_computed_blocks` updates `self.stats.cache_misses`, `self.stats.cache_hits`; calls `len`, `range`, `compute_block_hash`, `self.cached_block_hash_to_block.get_block`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L826-L868](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L826-L868).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.compute_block_hash" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.compute_block_hash</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.compute_block_hash(tokens: List[int]) -> str
```

Compute legacy string hash for a sequence of tokens.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `List[int]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `hashlib.sha256(token_bytes).hexdigest()[:16]`

**Exceptions and behavior**

Method `PagedCacheManager.compute_block_hash` calls `b''.join`, `t.to_bytes`, `hashlib.sha256(token_bytes).hexdigest`, `hashlib.sha256`; returns `hashlib.sha256(token_bytes).hexdigest()[:16]`.
No direct `raise` statement appears in this definition.

[View source #L875-L878](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L875-L878).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.find_cached_block" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.find_cached_block</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.find_cached_block(tokens: List[int]) -> Optional[CacheBlock]
```

Find a cached block matching the given tokens (legacy method).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `List[int]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Optional[CacheBlock]`
- Direct return expressions: `block`; `None`

**Exceptions and behavior**

Method `PagedCacheManager.find_cached_block` updates `self.stats.cache_hits`, `self.stats.cache_misses`; calls `self.compute_block_hash`, `block.touch`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L880-L896](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L880-L896).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.register_block_hash" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.register_block_hash</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.register_block_hash(block: CacheBlock, tokens: List[int]) -> None
```

Register a block's hash for deduplication (legacy method).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `block` | `CacheBlock` | `yes` | `none` | Required positional or keyword input. |
| `tokens` | `List[int]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `PagedCacheManager.register_block_hash` calls `self.compute_block_hash`.
No direct `raise` statement appears in this definition.

[View source #L898-L903](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L898-L903).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.create_block_table" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.create_block_table</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.create_block_table(request_id: str) -> BlockTable
```

Create a new block table for a request.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `request_id` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `BlockTable`
- Direct return expressions: `table`

**Exceptions and behavior**

Method `PagedCacheManager.create_block_table` calls `BlockTable`; returns `table`.
No direct `raise` statement appears in this definition.

[View source #L909-L914](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L909-L914).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.get_block_table" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.get_block_table</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.get_block_table(request_id: str) -> Optional[BlockTable]
```

Get block table for a request.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `request_id` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Optional[BlockTable]`
- Direct return expressions: `self.request_tables.get(request_id)`

**Exceptions and behavior**

Method `PagedCacheManager.get_block_table` calls `self.request_tables.get`; returns `self.request_tables.get(request_id)`.
No direct `raise` statement appears in this definition.

[View source #L916-L919](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L916-L919).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.get_or_create_block_table" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.get_or_create_block_table</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.get_or_create_block_table(request_id: str) -> BlockTable
```

Get or create block table for a request.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `request_id` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `BlockTable`
- Direct return expressions: `self.request_tables[request_id]`

**Exceptions and behavior**

Method `PagedCacheManager.get_or_create_block_table` calls `BlockTable`; returns `self.request_tables[request_id]`.
No direct `raise` statement appears in this definition.

[View source #L921-L926](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L921-L926).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.delete_block_table" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.delete_block_table</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.delete_block_table(request_id: str) -> None
```

Delete block table and free associated blocks.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `request_id` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `PagedCacheManager.delete_block_table` calls `self.request_tables.pop`, `self.free_block`.
No direct `raise` statement appears in this definition.

[View source #L928-L934](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L928-L934).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.add_block_to_table" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.add_block_to_table</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.add_block_to_table(table: BlockTable, block: CacheBlock, tokens_in_block: int) -> None
```

Add a block to a block table.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `table` | `BlockTable` | `yes` | `none` | Required positional or keyword input. |
| `block` | `CacheBlock` | `yes` | `none` | Required positional or keyword input. |
| `tokens_in_block` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `PagedCacheManager.add_block_to_table` updates `self.stats.total_tokens_cached`; calls `table.block_ids.append`.
No direct `raise` statement appears in this definition.

[View source #L936-L947](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L936-L947).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.find_shared_prefix" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.find_shared_prefix</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.find_shared_prefix(tokens: List[int]) -> Tuple[List[int], List[int]]
```

Find shared prefix blocks for a token sequence.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `List[int]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Tuple[List[int], List[int]]`
- Direct return expressions: `(shared_blocks, remaining_tokens)`

**Exceptions and behavior**

Method `PagedCacheManager.find_shared_prefix` calls `tokens.copy`, `len`, `self.find_cached_block`, `shared_blocks.append`; returns `(shared_blocks, remaining_tokens)`.
No direct `raise` statement appears in this definition.

[View source #L953-L974](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L953-L974).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.fork_block_table" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.fork_block_table</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.fork_block_table(source_table: BlockTable, new_request_id: str) -> BlockTable
```

Fork a block table for a new request (COW).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `source_table` | `BlockTable` | `yes` | `none` | Required positional or keyword input. |
| `new_request_id` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `BlockTable`
- Direct return expressions: `new_table`

**Exceptions and behavior**

Method `PagedCacheManager.fork_block_table` calls `source_table.copy`, `self.increment_ref`, `logger.debug`, `len`; returns `new_table`.
No direct `raise` statement appears in this definition.

[View source #L976-L997](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L976-L997).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.get_blocks_for_generation" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.get_blocks_for_generation</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.get_blocks_for_generation(table: BlockTable) -> Tuple[List[CacheBlock], bool]
```

Get blocks for generation, applying COW if needed.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `table` | `BlockTable` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Tuple[List[CacheBlock], bool]`
- Direct return expressions: `(blocks, was_copied)`

**Exceptions and behavior**

Method `PagedCacheManager.get_blocks_for_generation` updates `self.stats.cow_copies`; calls `enumerate`, `self.allocated_blocks.get`, `block.is_shared`, `self._cow_copy_block`; returns `(blocks, was_copied)`.
No direct `raise` statement appears in this definition.

[View source #L999-L1029](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L999-L1029).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager._cow_copy_block" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager._cow_copy_block</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager._cow_copy_block(source_block: CacheBlock) -> Optional[CacheBlock]
```

Create a copy of a block for COW.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `source_block` | `CacheBlock` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Optional[CacheBlock]`
- Direct return expressions: `None`; `new_block`

**Exceptions and behavior**

Method `PagedCacheManager._cow_copy_block` updates `self.stats.shared_blocks`; calls `self.allocate_block`, `logger.debug`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L1031-L1046](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1031-L1046).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.allocate_blocks_for_tokens" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.allocate_blocks_for_tokens</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.allocate_blocks_for_tokens(num_tokens: int) -> List[CacheBlock]
```

Allocate enough blocks to hold num_tokens.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `num_tokens` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `List[CacheBlock]`
- Direct return expressions: `self.get_new_blocks(num_blocks_needed)`

**Exceptions and behavior**

Method `PagedCacheManager.allocate_blocks_for_tokens` calls `self.get_new_blocks`; returns `self.get_new_blocks(num_blocks_needed)`.
No direct `raise` statement appears in this definition.

[View source #L1052-L1055](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1052-L1055).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.evict_lru_blocks" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.evict_lru_blocks</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.evict_lru_blocks(num_blocks: int) -> int
```

Evict least recently used blocks.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `num_blocks` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `int`
- Direct return expressions: `evicted`

**Exceptions and behavior**

Method `PagedCacheManager.evict_lru_blocks` calls `range`, `min`, `self.free_block_queue.popleft`, `self._maybe_evict_cached_block`; returns `evicted`.
No direct `raise` statement appears in this definition.

[View source #L1061-L1085](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1061-L1085).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.handle_memory_pressure" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.handle_memory_pressure</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.handle_memory_pressure(requested_blocks: int) -> bool
```

Handle memory pressure by evicting blocks.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `requested_blocks` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `bool`
- Direct return expressions: `True`; `self.free_block_queue.num_free_blocks >= requested_blocks`

**Exceptions and behavior**

Method `PagedCacheManager.handle_memory_pressure` calls `self.evict_lru_blocks`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L1087-L1096](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1087-L1096).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.free_blocks" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.free_blocks</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.free_blocks() -> int
```

Number of free blocks available.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `self.free_block_queue.num_free_blocks`

**Exceptions and behavior**

Method `PagedCacheManager.free_blocks` returns `self.free_block_queue.num_free_blocks`.
No direct `raise` statement appears in this definition.

[View source #L1103-L1105](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1103-L1105).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.usage" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.usage</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.usage() -> float
```

Cache usage ratio (0.0 to 1.0).

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `float`
- Direct return expressions: `0.0`; `1.0 - self.free_blocks / total`

**Exceptions and behavior**

Method `PagedCacheManager.usage` has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L1108-L1113](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1108-L1113).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.get_stats" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.get_stats</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.get_stats() -> CacheStats
```

Get current cache statistics.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `CacheStats`
- Direct return expressions: `self.stats`

**Exceptions and behavior**

Method `PagedCacheManager.get_stats` updates `self.stats.shared_blocks`, `self.stats.free_blocks`; calls `sum`, `self.allocated_blocks.values`; returns `self.stats`.
No direct `raise` statement appears in this definition.

[View source #L1115-L1122](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1115-L1122).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.get_memory_usage" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.get_memory_usage</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.get_memory_usage() -> Dict[str, Any]
```

Get memory usage information.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `Dict[str, Any]`
- Direct return expressions: `{'block_size': self.block_size, 'max_blocks': self.max_blocks, 'allocated_blocks': stats.allocated_blocks, 'free_blocks…`

**Exceptions and behavior**

Method `PagedCacheManager.get_memory_usage` calls `self.get_stats`; returns `{'block_size': self.block_size, 'max_blocks': self.max_blocks, 'allocated_blocks': stats.allocated_blocks, 'free_blocks…`.
No direct `raise` statement appears in this definition.

[View source #L1124-L1141](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1124-L1141).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.reset_stats" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.reset_stats</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.reset_stats() -> None
```

Reset statistics counters.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `PagedCacheManager.reset_stats` updates `self.stats.cache_hits`, `self.stats.cache_misses`, `self.stats.cow_copies`, `self.stats.evictions`.
No direct `raise` statement appears in this definition.

[View source #L1143-L1149](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1143-L1149).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.reset_prefix_cache" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.reset_prefix_cache</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.reset_prefix_cache() -> bool
```

Reset the prefix cache.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `bool`
- Direct return expressions: `False`; `True`

**Exceptions and behavior**

Method `PagedCacheManager.reset_prefix_cache` updates `self.stats.evictions`, `self.stats.cache_hits`, `self.stats.cache_misses`; calls `logger.warning`, `self.cached_block_hash_to_block.clear`, `self.hash_to_block.clear`, `block.reset_hash`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L1151-L1171](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1151-L1171).

</details>

<details class="api-contract" id="contract-vllm_mlx.paged_cache.PagedCacheManager.clear" markdown="1">
<summary><code>vllm_mlx.paged_cache.PagedCacheManager.clear</code> · method</summary>

```python
vllm_mlx.paged_cache.PagedCacheManager.clear() -> None
```

Clear all cached data.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `PagedCacheManager.clear` updates `self.blocks`, `self.free_block_queue`, `self.null_block`, `self.null_block.is_null`; calls `CacheBlock`, `range`, `FreeKVCacheBlockQueue`, `self.cached_block_hash_to_block.clear`.
No direct `raise` statement appears in this definition.

[View source #L1173-L1197](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1173-L1197).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`compute_block_hash`](#contract-vllm_mlx.paged_cache.compute_block_hash) | function | `compute_block_hash(parent_hash: Optional[BlockHash], token_ids: List[int], extra_keys: Optional[Tuple[Any, ...]] = None) -> BlockHash` | Compute hash for a block based on its content and parent block. | [#L40-L75](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L40-L75) |
| [`CacheBlock`](#contract-vllm_mlx.paged_cache.CacheBlock) | class | `CacheBlock(block_id: int, ref_count: int = 0, block_hash: Optional[BlockHash] = None, prev_free_block: Optional['CacheBlock'] = None, next_free_block: Optional['CacheBlock'] = None, is_null: bool = False, cache_data: Optional[List[Tuple[Any, Any]]] = None, token_count: int = 0, hash_value: Optional[str] = None, last_access: float = field(default_factory=time.time))` | KV cache block metadata following vLLM's design. | [#L84-L146](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L84-L146) |
| [`CacheBlock.is_full`](#contract-vllm_mlx.paged_cache.CacheBlock.is_full) | method | `CacheBlock.is_full(block_size: int) -> bool` | Check if block is at capacity. | [#L123-L125](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L123-L125) |
| [`CacheBlock.is_shared`](#contract-vllm_mlx.paged_cache.CacheBlock.is_shared) | method | `CacheBlock.is_shared() -> bool` | Check if block is shared (ref_count > 1). | [#L127-L129](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L127-L129) |
| [`CacheBlock.reset_hash`](#contract-vllm_mlx.paged_cache.CacheBlock.reset_hash) | method | `CacheBlock.reset_hash() -> None` | Reset block hash when evicted from cache. | [#L131-L134](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L131-L134) |
| [`CacheBlock.touch`](#contract-vllm_mlx.paged_cache.CacheBlock.touch) | method | `CacheBlock.touch() -> None` | Update last access time. | [#L136-L138](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L136-L138) |
| [`CacheBlock.__repr__`](#contract-vllm_mlx.paged_cache.CacheBlock.__repr__) | method | `CacheBlock.__repr__() -> str` | Method `CacheBlock.__repr__` returns `f'CacheBlock(id={self.block_id}, ref={self.ref_count}, tokens={self.token_count}, prev={prev_id}, next={next_id})'`. | [#L140-L146](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L140-L146) |
| [`FreeKVCacheBlockQueue`](#contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue) | class | `FreeKVCacheBlockQueue(blocks: List[CacheBlock])` | Doubly linked list of free blocks following vLLM's design. | [#L158-L337](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L158-L337) |
| [`FreeKVCacheBlockQueue.__init__`](#contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.__init__) | method | `FreeKVCacheBlockQueue.__init__(blocks: List[CacheBlock]) -> None` | Initialize queue with all blocks as free. | [#L174-L201](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L174-L201) |
| [`FreeKVCacheBlockQueue.popleft`](#contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.popleft) | method | `FreeKVCacheBlockQueue.popleft() -> CacheBlock` | Pop and return the first (LRU) free block. | [#L203-L225](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L203-L225) |
| [`FreeKVCacheBlockQueue.popleft_n`](#contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.popleft_n) | method | `FreeKVCacheBlockQueue.popleft_n(n: int) -> List[CacheBlock]` | Pop n blocks from the front. | [#L227-L265](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L227-L265) |
| [`FreeKVCacheBlockQueue.remove`](#contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.remove) | method | `FreeKVCacheBlockQueue.remove(block: CacheBlock) -> None` | Remove a block from the middle of the queue. | [#L267-L288](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L267-L288) |
| [`FreeKVCacheBlockQueue.append`](#contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.append) | method | `FreeKVCacheBlockQueue.append(block: CacheBlock) -> None` | Append a block to the end (MRU position). | [#L290-L305](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L290-L305) |
| [`FreeKVCacheBlockQueue.append_n`](#contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.append_n) | method | `FreeKVCacheBlockQueue.append_n(blocks: List[CacheBlock]) -> None` | Append multiple blocks to the end. | [#L307-L328](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L307-L328) |
| [`FreeKVCacheBlockQueue.get_all_free_blocks`](#contract-vllm_mlx.paged_cache.FreeKVCacheBlockQueue.get_all_free_blocks) | method | `FreeKVCacheBlockQueue.get_all_free_blocks() -> List[CacheBlock]` | Get all free blocks (for testing). | [#L330-L337](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L330-L337) |
| [`BlockHashToBlockMap`](#contract-vllm_mlx.paged_cache.BlockHashToBlockMap) | class | `BlockHashToBlockMap()` | Cache mapping block hashes to blocks for prefix caching. | [#L345-L407](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L345-L407) |
| [`BlockHashToBlockMap.__init__`](#contract-vllm_mlx.paged_cache.BlockHashToBlockMap.__init__) | method | `BlockHashToBlockMap.__init__() -> None` | Method `BlockHashToBlockMap.__init__` updates `self._cache`. | [#L353-L354](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L353-L354) |
| [`BlockHashToBlockMap.get_block`](#contract-vllm_mlx.paged_cache.BlockHashToBlockMap.get_block) | method | `BlockHashToBlockMap.get_block(block_hash: BlockHash) -> Optional[CacheBlock]` | Get any block with the given hash. | [#L356-L365](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L356-L365) |
| [`BlockHashToBlockMap.insert`](#contract-vllm_mlx.paged_cache.BlockHashToBlockMap.insert) | method | `BlockHashToBlockMap.insert(block_hash: BlockHash, block: CacheBlock) -> None` | Insert a block into the cache. | [#L367-L378](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L367-L378) |
| [`BlockHashToBlockMap.pop`](#contract-vllm_mlx.paged_cache.BlockHashToBlockMap.pop) | method | `BlockHashToBlockMap.pop(block_hash: BlockHash, block_id: int) -> Optional[CacheBlock]` | Remove and return a specific block from the cache. | [#L380-L399](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L380-L399) |
| [`BlockHashToBlockMap.__len__`](#contract-vllm_mlx.paged_cache.BlockHashToBlockMap.__len__) | method | `BlockHashToBlockMap.__len__() -> int` | Method `BlockHashToBlockMap.__len__` calls `len`; returns `len(self._cache)`. | [#L401-L402](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L401-L402) |
| [`BlockHashToBlockMap.clear`](#contract-vllm_mlx.paged_cache.BlockHashToBlockMap.clear) | method | `BlockHashToBlockMap.clear() -> None` | Remove every block-hash mapping without mutating the blocks. | [#L404-L407](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L404-L407) |
| [`BlockTable`](#contract-vllm_mlx.paged_cache.BlockTable) | class | `BlockTable(request_id: str, block_ids: List[int] = field(default_factory=list), num_tokens: int = 0)` | Per-request block table mapping logical to physical blocks. | [#L416-L447](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L416-L447) |
| [`BlockTable.add_block`](#contract-vllm_mlx.paged_cache.BlockTable.add_block) | method | `BlockTable.add_block(block_id: int, num_tokens: int) -> None` | Add a block to the table. | [#L433-L436](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L433-L436) |
| [`BlockTable.__len__`](#contract-vllm_mlx.paged_cache.BlockTable.__len__) | method | `BlockTable.__len__() -> int` | Method `BlockTable.__len__` calls `len`; returns `len(self.block_ids)`. | [#L438-L439](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L438-L439) |
| [`BlockTable.copy`](#contract-vllm_mlx.paged_cache.BlockTable.copy) | method | `BlockTable.copy(new_request_id: str) -> 'BlockTable'` | Create a copy with new request ID. | [#L441-L447](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L441-L447) |
| [`CacheStats`](#contract-vllm_mlx.paged_cache.CacheStats) | class | `CacheStats(total_blocks: int = 0, allocated_blocks: int = 0, free_blocks: int = 0, shared_blocks: int = 0, total_tokens_cached: int = 0, cache_hits: int = 0, cache_misses: int = 0, cow_copies: int = 0, evictions: int = 0)` | Statistics for cache monitoring. | [#L456-L467](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L456-L467) |
| [`PagedCacheManager`](#contract-vllm_mlx.paged_cache.PagedCacheManager) | class | `PagedCacheManager(block_size: int = 64, max_blocks: int = 1000, enable_caching: bool = True)` | Paged KV cache manager following vLLM's BlockPool architecture. | [#L475-L1197](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L475-L1197) |
| [`PagedCacheManager.__init__`](#contract-vllm_mlx.paged_cache.PagedCacheManager.__init__) | method | `PagedCacheManager.__init__(block_size: int = 64, max_blocks: int = 1000, enable_caching: bool = True) -> not annotated` | Method `PagedCacheManager.__init__` updates `self.block_size`, `self.max_blocks`, `self.enable_caching`, `self.blocks`; calls `CacheBlock`, `range`, `FreeKVCacheBlockQueue`, `BlockHashToBlockMap`. | [#L491-L540](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L491-L540) |
| [`PagedCacheManager.allocate_block`](#contract-vllm_mlx.paged_cache.PagedCacheManager.allocate_block) | method | `PagedCacheManager.allocate_block() -> Optional[CacheBlock]` | Allocate a new cache block. | [#L546-L571](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L546-L571) |
| [`PagedCacheManager.get_new_blocks`](#contract-vllm_mlx.paged_cache.PagedCacheManager.get_new_blocks) | method | `PagedCacheManager.get_new_blocks(num_blocks: int) -> List[CacheBlock]` | Allocate multiple blocks at once (vLLM style). | [#L573-L606](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L573-L606) |
| [`PagedCacheManager._maybe_evict_cached_block`](#contract-vllm_mlx.paged_cache.PagedCacheManager._maybe_evict_cached_block) | method | `PagedCacheManager._maybe_evict_cached_block(block: CacheBlock) -> bool` | Evict a block from the hash cache if present. | [#L608-L634](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L608-L634) |
| [`PagedCacheManager.free_block`](#contract-vllm_mlx.paged_cache.PagedCacheManager.free_block) | method | `PagedCacheManager.free_block(block_id: int) -> bool` | Free a cache block (decrements ref_count, frees if 0). | [#L636-L667](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L636-L667) |
| [`PagedCacheManager.free_blocks`](#contract-vllm_mlx.paged_cache.PagedCacheManager.free_blocks) | method | `PagedCacheManager.free_blocks(blocks: Iterable[CacheBlock]) -> None` | Free multiple blocks (vLLM style). | [#L669-L696](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L669-L696) |
| [`PagedCacheManager.touch`](#contract-vllm_mlx.paged_cache.PagedCacheManager.touch) | method | `PagedCacheManager.touch(blocks: Iterable[CacheBlock]) -> None` | Touch blocks to prevent eviction (cache hit, vLLM style). | [#L698-L720](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L698-L720) |
| [`PagedCacheManager.increment_ref`](#contract-vllm_mlx.paged_cache.PagedCacheManager.increment_ref) | method | `PagedCacheManager.increment_ref(block_id: int) -> bool` | Increment reference count for a block. | [#L726-L739](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L726-L739) |
| [`PagedCacheManager.decrement_ref`](#contract-vllm_mlx.paged_cache.PagedCacheManager.decrement_ref) | method | `PagedCacheManager.decrement_ref(block_id: int) -> bool` | Decrement reference count (alias for free_block). | [#L741-L743](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L741-L743) |
| [`PagedCacheManager.get_cached_block`](#contract-vllm_mlx.paged_cache.PagedCacheManager.get_cached_block) | method | `PagedCacheManager.get_cached_block(block_hash: BlockHash) -> Optional[CacheBlock]` | Get a cached block by its hash (vLLM style). | [#L749-L768](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L749-L768) |
| [`PagedCacheManager.cache_full_blocks`](#contract-vllm_mlx.paged_cache.PagedCacheManager.cache_full_blocks) | method | `PagedCacheManager.cache_full_blocks(blocks: List[CacheBlock], token_ids: List[int], num_cached_blocks: int, num_full_blocks: int) -> None` | Cache full blocks for prefix caching (vLLM style). | [#L770-L824](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L770-L824) |
| [`PagedCacheManager.get_computed_blocks`](#contract-vllm_mlx.paged_cache.PagedCacheManager.get_computed_blocks) | method | `PagedCacheManager.get_computed_blocks(token_ids: List[int]) -> Tuple[List[CacheBlock], int]` | Find cached blocks for a token prefix (vLLM style). | [#L826-L868](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L826-L868) |
| [`PagedCacheManager.compute_block_hash`](#contract-vllm_mlx.paged_cache.PagedCacheManager.compute_block_hash) | method | `PagedCacheManager.compute_block_hash(tokens: List[int]) -> str` | Compute legacy string hash for a sequence of tokens. | [#L875-L878](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L875-L878) |
| [`PagedCacheManager.find_cached_block`](#contract-vllm_mlx.paged_cache.PagedCacheManager.find_cached_block) | method | `PagedCacheManager.find_cached_block(tokens: List[int]) -> Optional[CacheBlock]` | Find a cached block matching the given tokens (legacy method). | [#L880-L896](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L880-L896) |
| [`PagedCacheManager.register_block_hash`](#contract-vllm_mlx.paged_cache.PagedCacheManager.register_block_hash) | method | `PagedCacheManager.register_block_hash(block: CacheBlock, tokens: List[int]) -> None` | Register a block's hash for deduplication (legacy method). | [#L898-L903](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L898-L903) |
| [`PagedCacheManager.create_block_table`](#contract-vllm_mlx.paged_cache.PagedCacheManager.create_block_table) | method | `PagedCacheManager.create_block_table(request_id: str) -> BlockTable` | Create a new block table for a request. | [#L909-L914](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L909-L914) |
| [`PagedCacheManager.get_block_table`](#contract-vllm_mlx.paged_cache.PagedCacheManager.get_block_table) | method | `PagedCacheManager.get_block_table(request_id: str) -> Optional[BlockTable]` | Get block table for a request. | [#L916-L919](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L916-L919) |
| [`PagedCacheManager.get_or_create_block_table`](#contract-vllm_mlx.paged_cache.PagedCacheManager.get_or_create_block_table) | method | `PagedCacheManager.get_or_create_block_table(request_id: str) -> BlockTable` | Get or create block table for a request. | [#L921-L926](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L921-L926) |
| [`PagedCacheManager.delete_block_table`](#contract-vllm_mlx.paged_cache.PagedCacheManager.delete_block_table) | method | `PagedCacheManager.delete_block_table(request_id: str) -> None` | Delete block table and free associated blocks. | [#L928-L934](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L928-L934) |
| [`PagedCacheManager.add_block_to_table`](#contract-vllm_mlx.paged_cache.PagedCacheManager.add_block_to_table) | method | `PagedCacheManager.add_block_to_table(table: BlockTable, block: CacheBlock, tokens_in_block: int) -> None` | Add a block to a block table. | [#L936-L947](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L936-L947) |
| [`PagedCacheManager.find_shared_prefix`](#contract-vllm_mlx.paged_cache.PagedCacheManager.find_shared_prefix) | method | `PagedCacheManager.find_shared_prefix(tokens: List[int]) -> Tuple[List[int], List[int]]` | Find shared prefix blocks for a token sequence. | [#L953-L974](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L953-L974) |
| [`PagedCacheManager.fork_block_table`](#contract-vllm_mlx.paged_cache.PagedCacheManager.fork_block_table) | method | `PagedCacheManager.fork_block_table(source_table: BlockTable, new_request_id: str) -> BlockTable` | Fork a block table for a new request (COW). | [#L976-L997](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L976-L997) |
| [`PagedCacheManager.get_blocks_for_generation`](#contract-vllm_mlx.paged_cache.PagedCacheManager.get_blocks_for_generation) | method | `PagedCacheManager.get_blocks_for_generation(table: BlockTable) -> Tuple[List[CacheBlock], bool]` | Get blocks for generation, applying COW if needed. | [#L999-L1029](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L999-L1029) |
| [`PagedCacheManager._cow_copy_block`](#contract-vllm_mlx.paged_cache.PagedCacheManager._cow_copy_block) | method | `PagedCacheManager._cow_copy_block(source_block: CacheBlock) -> Optional[CacheBlock]` | Create a copy of a block for COW. | [#L1031-L1046](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1031-L1046) |
| [`PagedCacheManager.allocate_blocks_for_tokens`](#contract-vllm_mlx.paged_cache.PagedCacheManager.allocate_blocks_for_tokens) | method | `PagedCacheManager.allocate_blocks_for_tokens(num_tokens: int) -> List[CacheBlock]` | Allocate enough blocks to hold num_tokens. | [#L1052-L1055](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1052-L1055) |
| [`PagedCacheManager.evict_lru_blocks`](#contract-vllm_mlx.paged_cache.PagedCacheManager.evict_lru_blocks) | method | `PagedCacheManager.evict_lru_blocks(num_blocks: int) -> int` | Evict least recently used blocks. | [#L1061-L1085](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1061-L1085) |
| [`PagedCacheManager.handle_memory_pressure`](#contract-vllm_mlx.paged_cache.PagedCacheManager.handle_memory_pressure) | method | `PagedCacheManager.handle_memory_pressure(requested_blocks: int) -> bool` | Handle memory pressure by evicting blocks. | [#L1087-L1096](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1087-L1096) |
| [`PagedCacheManager.free_blocks`](#contract-vllm_mlx.paged_cache.PagedCacheManager.free_blocks) | method | `PagedCacheManager.free_blocks() -> int` | Number of free blocks available. | [#L1103-L1105](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1103-L1105) |
| [`PagedCacheManager.usage`](#contract-vllm_mlx.paged_cache.PagedCacheManager.usage) | method | `PagedCacheManager.usage() -> float` | Cache usage ratio (0.0 to 1.0). | [#L1108-L1113](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1108-L1113) |
| [`PagedCacheManager.get_stats`](#contract-vllm_mlx.paged_cache.PagedCacheManager.get_stats) | method | `PagedCacheManager.get_stats() -> CacheStats` | Get current cache statistics. | [#L1115-L1122](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1115-L1122) |
| [`PagedCacheManager.get_memory_usage`](#contract-vllm_mlx.paged_cache.PagedCacheManager.get_memory_usage) | method | `PagedCacheManager.get_memory_usage() -> Dict[str, Any]` | Get memory usage information. | [#L1124-L1141](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1124-L1141) |
| [`PagedCacheManager.reset_stats`](#contract-vllm_mlx.paged_cache.PagedCacheManager.reset_stats) | method | `PagedCacheManager.reset_stats() -> None` | Reset statistics counters. | [#L1143-L1149](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1143-L1149) |
| [`PagedCacheManager.reset_prefix_cache`](#contract-vllm_mlx.paged_cache.PagedCacheManager.reset_prefix_cache) | method | `PagedCacheManager.reset_prefix_cache() -> bool` | Reset the prefix cache. | [#L1151-L1171](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1151-L1171) |
| [`PagedCacheManager.clear`](#contract-vllm_mlx.paged_cache.PagedCacheManager.clear) | method | `PagedCacheManager.clear() -> None` | Clear all cached data. | [#L1173-L1197](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/paged_cache.py#L1173-L1197) |