# `vllm_mlx.ssd_cache`

SSD KV cache tiering for vllm-mlx.

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

## 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.ssd_cache
    options:
      members:
        - logger
        - _BYTES_PER_MB
        - _BYTES_PER_GB
        - _PREFIX_FILTER_TOKENS
        - SSDCacheConfig
        - SSDCacheStats
        - _tokens_to_blob
        - _blob_to_tokens
        - _tokens_hash
        - _prefix_hash
        - SSDIndex
        - SERIALIZER_SUPPORT_MATRIX
        - LayerSerializer
        - _mx_to_numpy_safe
        - KVCacheSerializer
        - ArraysCacheSerializer
        - get_serializer_for_layer
        - SSDCacheTier
      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.ssd_cache.SSDCacheConfig" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheConfig</code> · class</summary>

```python
vllm_mlx.ssd_cache.SSDCacheConfig(cache_dir: str | None = None, max_size_gb: float = 10.0, max_entries: int = 10000, file_permissions: int = 384, dir_permissions: int = 448, spill_queue_size: int = 64, retention_seconds: int | None = None)
```

Configuration for SSD cache tier.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `cache_dir` | `str \| None` | `no` | `None` | Optional constructor field; defaults to `None`. |
| `max_size_gb` | `float` | `no` | `10.0` | Optional constructor field; defaults to `10.0`. |
| `max_entries` | `int` | `no` | `10000` | Optional constructor field; defaults to `10000`. |
| `file_permissions` | `int` | `no` | `384` | Optional constructor field; defaults to `384`. |
| `dir_permissions` | `int` | `no` | `448` | Optional constructor field; defaults to `448`. |
| `spill_queue_size` | `int` | `no` | `64` | Optional constructor field; defaults to `64`. |
| `retention_seconds` | `int \| None` | `no` | `None` | Optional constructor field; defaults to `None`. |

**Returns**

- Constructs: `vllm_mlx.ssd_cache.SSDCacheConfig`

**Exceptions and behavior**

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

[View source #L43-L78](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L43-L78).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheConfig.__post_init__" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheConfig.__post_init__</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheConfig.__post_init__() -> None
```

Method `SSDCacheConfig.__post_init__` calls `ValueError`; can raise `ValueError`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDCacheConfig.__post_init__` calls `ValueError`; can raise `ValueError`.
Directly raised exceptions: `ValueError`.

[View source #L65-L73](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L65-L73).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheConfig.max_size_bytes" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheConfig.max_size_bytes</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheConfig.max_size_bytes() -> int
```

Maximum cache size in bytes.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `int(self.max_size_gb * _BYTES_PER_GB)`

**Exceptions and behavior**

Method `SSDCacheConfig.max_size_bytes` calls `int`; returns `int(self.max_size_gb * _BYTES_PER_GB)`.
No direct `raise` statement appears in this definition.

[View source #L76-L78](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L76-L78).

</details>

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

```python
vllm_mlx.ssd_cache.SSDCacheStats(spill_count: int = 0, spill_bytes: int = 0, ssd_hits: int = 0, ssd_misses: int = 0, reload_latency_sum: float = 0.0, reload_bytes: int = 0, promotion_failures: int = 0)
```

Statistics for SSD cache tier — exposed from day one.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `spill_count` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `spill_bytes` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `ssd_hits` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `ssd_misses` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `reload_latency_sum` | `float` | `no` | `0.0` | Optional constructor field; defaults to `0.0`. |
| `reload_bytes` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `promotion_failures` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |

**Returns**

- Constructs: `vllm_mlx.ssd_cache.SSDCacheStats`

**Exceptions and behavior**

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

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

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheStats.to_dict" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheStats.to_dict</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheStats.to_dict() -> dict
```

Return spill, lookup, reload, and promotion statistics.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict`
- Direct return expressions: `{'spill_count': self.spill_count, 'spill_bytes': self.spill_bytes, 'ssd_hits': self.ssd_hits, 'ssd_misses': self.ssd_mi…`

**Exceptions and behavior**

Method `SSDCacheStats.to_dict` calls `round`; returns `{'spill_count': self.spill_count, 'spill_bytes': self.spill_bytes, 'ssd_hits': self.ssd_hits, 'ssd_misses': self.ssd_mi…`.
No direct `raise` statement appears in this definition.

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

</details>

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

```python
vllm_mlx.ssd_cache._tokens_to_blob(tokens: tuple[int, ...]) -> bytes
```

Serialize token tuple to a compact binary blob for SQLite storage.

**Parameters**

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

**Returns**

- Type: `bytes`
- Direct return expressions: `arr.tobytes()`

**Exceptions and behavior**

Function `_tokens_to_blob` calls `_array.array`, `arr.tobytes`; returns `arr.tobytes()`.
No direct `raise` statement appears in this definition.

[View source #L126-L132](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L126-L132).

</details>

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

```python
vllm_mlx.ssd_cache._blob_to_tokens(blob: bytes) -> tuple[int, ...]
```

Deserialize binary blob back to token tuple.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `blob` | `bytes` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[int, ...]`
- Direct return expressions: `tuple(arr)`

**Exceptions and behavior**

Function `_blob_to_tokens` calls `_array.array`, `arr.frombytes`, `tuple`; returns `tuple(arr)`.
No direct `raise` statement appears in this definition.

[View source #L135-L139](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L135-L139).

</details>

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

```python
vllm_mlx.ssd_cache._tokens_hash(tokens: tuple[int, ...]) -> str
```

Compute SHA-256 hex digest of a token sequence for use as primary key.

**Parameters**

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

**Returns**

- Type: `str`
- Direct return expressions: `hashlib.sha256(_tokens_to_blob(tokens)).hexdigest()`

**Exceptions and behavior**

Function `_tokens_hash` calls `hashlib.sha256(_tokens_to_blob(tokens)).hexdigest`, `hashlib.sha256`, `_tokens_to_blob`; returns `hashlib.sha256(_tokens_to_blob(tokens)).hexdigest()`.
No direct `raise` statement appears in this definition.

[View source #L142-L144](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L142-L144).

</details>

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

```python
vllm_mlx.ssd_cache._prefix_hash(tokens: tuple[int, ...]) -> str
```

Hash the bounded token prefix used to prefilter prefix lookups.

**Parameters**

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

**Returns**

- Type: `str`
- Direct return expressions: `_tokens_hash(tokens[:_PREFIX_FILTER_TOKENS])`

**Exceptions and behavior**

Function `_prefix_hash` calls `_tokens_hash`; returns `_tokens_hash(tokens[:_PREFIX_FILTER_TOKENS])`.
No direct `raise` statement appears in this definition.

[View source #L147-L149](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L147-L149).

</details>

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

```python
vllm_mlx.ssd_cache.SSDIndex(cache_dir: str)
```

SQLite-backed index for SSD cache entries.

**Parameters**

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

**Returns**

- Constructs: `vllm_mlx.ssd_cache.SSDIndex`

**Exceptions and behavior**

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

[View source #L152-L405](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L152-L405).

</details>

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

```python
vllm_mlx.ssd_cache.SSDIndex.__init__(cache_dir: str) -> None
```

Method `SSDIndex.__init__` updates `self._cache_dir`, `self._db_lock`, `self._conn`, `self._conn.row_factory`; calls `threading.Lock`, `os.path.join`, `sqlite3.connect`, `self._conn.execute`.

**Parameters**

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

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDIndex.__init__` updates `self._cache_dir`, `self._db_lock`, `self._conn`, `self._conn.row_factory`; calls `threading.Lock`, `os.path.join`, `sqlite3.connect`, `self._conn.execute`.
No direct `raise` statement appears in this definition.

[View source #L165-L173](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L165-L173).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex._create_tables" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex._create_tables</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex._create_tables() -> None
```

Method `SSDIndex._create_tables` calls `self._conn.executescript`, `self._ensure_column`, `self._conn.execute`, `cur.fetchone`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDIndex._create_tables` calls `self._conn.executescript`, `self._ensure_column`, `self._conn.execute`, `cur.fetchone`.
No direct `raise` statement appears in this definition.

[View source #L175-L213](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L175-L213).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex._ensure_column" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex._ensure_column</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex._ensure_column(table: str, column: str, definition: str) -> None
```

Method `SSDIndex._ensure_column` calls `self._conn.execute`, `cur.fetchall`.

**Parameters**

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

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDIndex._ensure_column` calls `self._conn.execute`, `cur.fetchall`.
No direct `raise` statement appears in this definition.

[View source #L215-L218](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L215-L218).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex._backfill_prefix_hashes" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex._backfill_prefix_hashes</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex._backfill_prefix_hashes() -> None
```

Method `SSDIndex._backfill_prefix_hashes` calls `self._conn.execute`, `cur.fetchall`, `_blob_to_tokens`, `_prefix_hash`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDIndex._backfill_prefix_hashes` calls `self._conn.execute`, `cur.fetchall`, `_blob_to_tokens`, `_prefix_hash`.
No direct `raise` statement appears in this definition.

[View source #L220-L230](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L220-L230).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.insert_entry" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.insert_entry</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.insert_entry(tokens_key: tuple[int, ...], file_path: str, memory_bytes: int, num_tokens: int) -> None
```

Insert or replace a cache entry in the index.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens_key` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |
| `file_path` | `str` | `yes` | `none` | Required positional or keyword input. |
| `memory_bytes` | `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 `SSDIndex.insert_entry` calls `time.time`, `_tokens_hash`, `_prefix_hash`, `_tokens_to_blob`.
No direct `raise` statement appears in this definition.

[View source #L232-L263](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L232-L263).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.lookup_exact" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.lookup_exact</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.lookup_exact(tokens_key: tuple[int, ...]) -> dict | None
```

Look up an exact token sequence.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens_key` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict | None`
- Direct return expressions: `None`; `{'file_path': row['file_path'], 'memory_bytes': row['memory_bytes'], 'num_tokens': row['num_tokens']}`

**Exceptions and behavior**

Method `SSDIndex.lookup_exact` calls `_tokens_hash`, `self._conn.execute`, `cur.fetchone`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.lookup_prefix" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.lookup_prefix</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.lookup_prefix(query_tokens: tuple[int, ...]) -> list[dict]
```

Find entries whose token sequence is a prefix of query_tokens.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query_tokens` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `list[dict]`
- Direct return expressions: `[]`; `results`

**Exceptions and behavior**

Method `SSDIndex.lookup_prefix` calls `len`, `_tokens_to_blob`, `_tokens_hash`, `range`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L282-L324](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L282-L324).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.delete_entry" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.delete_entry</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.delete_entry(tokens_key: tuple[int, ...]) -> None
```

Delete an entry by token sequence.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens_key` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDIndex.delete_entry` calls `_tokens_hash`, `self._conn.execute`, `self._conn.commit`.
No direct `raise` statement appears in this definition.

[View source #L326-L333](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L326-L333).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.get_lru" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.get_lru</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.get_lru(limit: int = 10) -> list[dict]
```

Get the least recently used entries, ordered oldest first.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `limit` | `int` | `no` | `10` | Optional positional or keyword input; defaults to `10`. |

**Returns**

- Type: `list[dict]`
- Direct return expressions: `results`

**Exceptions and behavior**

Method `SSDIndex.get_lru` calls `self._conn.execute`, `cur.fetchall`, `results.append`; returns `results`.
No direct `raise` statement appears in this definition.

[View source #L335-L355](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L335-L355).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.get_total_bytes" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.get_total_bytes</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.get_total_bytes() -> int
```

Get total memory_bytes across all entries.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `cur.fetchone()[0]`

**Exceptions and behavior**

Method `SSDIndex.get_total_bytes` calls `self._conn.execute`, `cur.fetchone`; returns `cur.fetchone()[0]`.
No direct `raise` statement appears in this definition.

[View source #L357-L363](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L357-L363).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.get_entry_count" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.get_entry_count</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.get_entry_count() -> int
```

Get number of entries in the index.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `cur.fetchone()[0]`

**Exceptions and behavior**

Method `SSDIndex.get_entry_count` calls `self._conn.execute`, `cur.fetchone`; returns `cur.fetchone()[0]`.
No direct `raise` statement appears in this definition.

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

</details>

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

```python
vllm_mlx.ssd_cache.SSDIndex.touch(tokens_key: tuple[int, ...]) -> None
```

Update accessed_at timestamp for an entry (marks as recently used).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens_key` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDIndex.touch` calls `_tokens_hash`, `self._conn.execute`, `time.time`, `self._conn.commit`.
No direct `raise` statement appears in this definition.

[View source #L371-L379](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L371-L379).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.all_entries" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.all_entries</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.all_entries() -> list[dict]
```

Return all entries (for startup reconciliation).

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `list[dict]`
- Direct return expressions: `results`

**Exceptions and behavior**

Method `SSDIndex.all_entries` calls `self._conn.execute`, `cur.fetchall`, `results.append`; returns `results`.
No direct `raise` statement appears in this definition.

[View source #L381-L400](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L381-L400).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDIndex.close" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDIndex.close</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDIndex.close() -> None
```

Close the SQLite connection.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDIndex.close` calls `self._conn.close`.
No direct `raise` statement appears in this definition.

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

</details>

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

```python
vllm_mlx.ssd_cache.LayerSerializer()
```

Interface for per-layer cache serialization.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Constructs: `vllm_mlx.ssd_cache.LayerSerializer`

**Exceptions and behavior**

Class `LayerSerializer` derives from `ABC` and declares 3 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L419-L446](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L419-L446).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.LayerSerializer.snapshot_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.LayerSerializer.snapshot_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.LayerSerializer.snapshot_layer(layer: Any) -> dict[str, Any]
```

Producer-thread CPU snapshot of an MLX-backed cache layer.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `layer` | `Any` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict[str, Any]`

**Exceptions and behavior**

Method `LayerSerializer.snapshot_layer` contains no state mutation, call, raise, return, await, or yield.
No direct `raise` statement appears in this definition.

[View source #L429-L431](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L429-L431).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.LayerSerializer.serialize_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.LayerSerializer.serialize_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.LayerSerializer.serialize_layer(snapshot: dict[str, Any], layer_idx: int, file_path: str) -> dict[str, Any]
```

Writer-thread: persist a snapshot to safetensors at file_path.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `snapshot` | `dict[str, Any]` | `yes` | `none` | Required positional or keyword input. |
| `layer_idx` | `int` | `yes` | `none` | Required positional or keyword input. |
| `file_path` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict[str, Any]`

**Exceptions and behavior**

Method `LayerSerializer.serialize_layer` contains no state mutation, call, raise, return, await, or yield.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.LayerSerializer.deserialize_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.LayerSerializer.deserialize_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.LayerSerializer.deserialize_layer(file_path: str, metadata: dict[str, Any]) -> dict
```

Read a layer back from disk.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `file_path` | `str` | `yes` | `none` | Required positional or keyword input. |
| `metadata` | `dict[str, Any]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict`

**Exceptions and behavior**

Method `LayerSerializer.deserialize_layer` contains no state mutation, call, raise, return, await, or yield.
No direct `raise` statement appears in this definition.

[View source #L444-L446](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L444-L446).

</details>

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

```python
vllm_mlx.ssd_cache._mx_to_numpy_safe(arr: Any) -> tuple[np.ndarray, str | None]
```

mx.array → np.ndarray, upcasting numpy-unsupported dtypes (bf16) to fp32.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `arr` | `Any` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[np.ndarray, str | None]`
- Direct return expressions: `(np.array(arr), None)`; `(np.array(upcast), original_dtype)`

**Exceptions and behavior**

Function `_mx_to_numpy_safe` calls `np.array`, `str`, `str(arr.dtype).rsplit`, `arr.astype`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

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

</details>

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

```python
vllm_mlx.ssd_cache.KVCacheSerializer()
```

Serializer for KVCache and RotatingKVCache layers.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Constructs: `vllm_mlx.ssd_cache.KVCacheSerializer`

**Exceptions and behavior**

Class `KVCacheSerializer` derives from `LayerSerializer` and declares 3 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L470-L564](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L470-L564).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.KVCacheSerializer.snapshot_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.KVCacheSerializer.snapshot_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.KVCacheSerializer.snapshot_layer(layer: Any) -> dict[str, Any]
```

Copy a KV cache layer into NumPy-backed writer-thread data.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `layer` | `Any` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict[str, Any]`
- Direct return expressions: `snapshot`

**Exceptions and behavior**

Method `KVCacheSerializer.snapshot_layer` calls `_mx_to_numpy_safe`, `getattr`, `hasattr`; returns `snapshot`.
No direct `raise` statement appears in this definition.

[View source #L481-L515](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L481-L515).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.KVCacheSerializer.serialize_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.KVCacheSerializer.serialize_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.KVCacheSerializer.serialize_layer(snapshot: dict[str, Any], layer_idx: int, file_path: str) -> dict[str, Any]
```

Write one KV layer to safetensors and return reconstruction metadata.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `snapshot` | `dict[str, Any]` | `yes` | `none` | Required positional or keyword input. |
| `layer_idx` | `int` | `yes` | `none` | Required positional or keyword input. |
| `file_path` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict[str, Any]`
- Direct return expressions: `metadata`

**Exceptions and behavior**

Method `KVCacheSerializer.serialize_layer` calls `save_file`; returns `metadata`.
No direct `raise` statement appears in this definition.

[View source #L517-L542](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L517-L542).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.KVCacheSerializer.deserialize_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.KVCacheSerializer.deserialize_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.KVCacheSerializer.deserialize_layer(file_path: str, metadata: dict[str, Any]) -> dict
```

Load one KV layer as arrays plus cache reconstruction metadata.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `file_path` | `str` | `yes` | `none` | Required positional or keyword input. |
| `metadata` | `dict[str, Any]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict`
- Direct return expressions: `result`

**Exceptions and behavior**

Method `KVCacheSerializer.deserialize_layer` calls `load_file`; returns `result`.
No direct `raise` statement appears in this definition.

[View source #L544-L564](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L544-L564).

</details>

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

```python
vllm_mlx.ssd_cache.ArraysCacheSerializer()
```

Serializer for ArraysCache (Mamba/linear attention) layers.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Constructs: `vllm_mlx.ssd_cache.ArraysCacheSerializer`

**Exceptions and behavior**

Class `ArraysCacheSerializer` derives from `LayerSerializer` and declares 3 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L567-L627](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L567-L627).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.ArraysCacheSerializer.snapshot_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.ArraysCacheSerializer.snapshot_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.ArraysCacheSerializer.snapshot_layer(layer: Any) -> dict[str, Any]
```

Copy an arrays-cache state into NumPy-backed writer-thread data.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `layer` | `Any` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict[str, Any]`
- Direct return expressions: `snapshot`

**Exceptions and behavior**

Method `ArraysCacheSerializer.snapshot_layer` calls `_mx_to_numpy_safe`, `state_np.append`, `original_dtypes.append`, `any`; returns `snapshot`.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.ArraysCacheSerializer.serialize_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.ArraysCacheSerializer.serialize_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.ArraysCacheSerializer.serialize_layer(snapshot: dict[str, Any], layer_idx: int, file_path: str) -> dict[str, Any]
```

Write arrays-cache state to safetensors and return its metadata.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `snapshot` | `dict[str, Any]` | `yes` | `none` | Required positional or keyword input. |
| `layer_idx` | `int` | `yes` | `none` | Required positional or keyword input. |
| `file_path` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict[str, Any]`
- Direct return expressions: `metadata`

**Exceptions and behavior**

Method `ArraysCacheSerializer.serialize_layer` calls `enumerate`, `save_file`, `len`; returns `metadata`.
No direct `raise` statement appears in this definition.

[View source #L589-L610](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L589-L610).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.ArraysCacheSerializer.deserialize_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.ArraysCacheSerializer.deserialize_layer</code> · method</summary>

```python
vllm_mlx.ssd_cache.ArraysCacheSerializer.deserialize_layer(file_path: str, metadata: dict[str, Any]) -> dict
```

Load arrays-cache state and any original dtype hints.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `file_path` | `str` | `yes` | `none` | Required positional or keyword input. |
| `metadata` | `dict[str, Any]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `dict`
- Direct return expressions: `result`

**Exceptions and behavior**

Method `ArraysCacheSerializer.deserialize_layer` calls `load_file`, `range`, `state.append`; returns `result`.
No direct `raise` statement appears in this definition.

[View source #L612-L627](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L612-L627).

</details>

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

```python
vllm_mlx.ssd_cache.get_serializer_for_layer(layer: Any) -> LayerSerializer
```

Return the appropriate serializer for a cache layer.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `layer` | `Any` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `LayerSerializer`
- Direct return expressions: `KVCacheSerializer()`; `ArraysCacheSerializer()`

**Exceptions and behavior**

Function `get_serializer_for_layer` calls `hasattr`, `KVCacheSerializer`, `isinstance`, `getattr`; can raise `ValueError`; has 2 explicit return paths.
Directly raised exceptions: `ValueError`.

[View source #L630-L646](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L630-L646).

</details>

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

```python
vllm_mlx.ssd_cache.SSDCacheTier(config: SSDCacheConfig)
```

Cold-tier disk cache for KV cache entries.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `config` | `SSDCacheConfig` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Constructs: `vllm_mlx.ssd_cache.SSDCacheTier`

**Exceptions and behavior**

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

[View source #L649-L1248](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L649-L1248).

</details>

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

```python
vllm_mlx.ssd_cache.SSDCacheTier.__init__(config: SSDCacheConfig) -> None
```

Method `SSDCacheTier.__init__` updates `self._config`, `self._closed`, `self._writer_thread`, `self._cache_dir`; calls `ValueError`, `os.path.join`, `os.makedirs`, `SSDIndex`; can raise `ValueError`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `config` | `SSDCacheConfig` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDCacheTier.__init__` updates `self._config`, `self._closed`, `self._writer_thread`, `self._cache_dir`; calls `ValueError`, `os.path.join`, `os.makedirs`, `SSDIndex`; can raise `ValueError`.
Directly raised exceptions: `ValueError`.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier._entry_hash" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier._entry_hash</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier._entry_hash(tokens: tuple[int, ...]) -> str
```

Compute deterministic hash for a token sequence.

**Parameters**

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

**Returns**

- Type: `str`
- Direct return expressions: `_tokens_hash(tokens)`

**Exceptions and behavior**

Method `SSDCacheTier._entry_hash` calls `_tokens_hash`; returns `_tokens_hash(tokens)`.
No direct `raise` statement appears in this definition.

[View source #L708-L710](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L708-L710).

</details>

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

```python
vllm_mlx.ssd_cache.SSDCacheTier.get_stats() -> dict
```

Return current SSD cache statistics.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict`
- Direct return expressions: `self._stats.to_dict()`

**Exceptions and behavior**

Method `SSDCacheTier.get_stats` calls `self._stats.to_dict`; returns `self._stats.to_dict()`.
No direct `raise` statement appears in this definition.

[View source #L712-L714](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L712-L714).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier.start_writer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier.start_writer</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier.start_writer() -> None
```

Start the background spill writer thread.

**Parameters**

This callable has no explicit inputs.

**Returns**

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

**Exceptions and behavior**

Method `SSDCacheTier.start_writer` updates `self._writer_thread`; calls `self._writer_stop.clear`, `threading.Thread`, `self._writer_thread.start`, `logger.info`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L716-L725](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L716-L725).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier._writer_loop" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier._writer_loop</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier._writer_loop() -> None
```

Drain spill queue and persist entries.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDCacheTier._writer_loop` calls `self._writer_stop.is_set`, `self._spill_queue.get`, `self._write_entry`, `logger.exception`.
No direct `raise` statement appears in this definition.

[View source #L727-L744](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L727-L744).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier.enqueue_spill" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier.enqueue_spill</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier.enqueue_spill(tokens: tuple[int, ...], cache: list[Any], memory_bytes: int) -> bool
```

Enqueue a cache entry for async spill to SSD.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |
| `cache` | `list[Any]` | `yes` | `none` | Required positional or keyword input. |
| `memory_bytes` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

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

**Exceptions and behavior**

Method `SSDCacheTier.enqueue_spill` calls `any`, `_is_quantized_layer`, `isinstance`, `converted.extend`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L746-L867](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L746-L867).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier.enqueue_spill._is_quantized_layer" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier.enqueue_spill._is_quantized_layer</code> · nested function</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier.enqueue_spill._is_quantized_layer(layer) -> not annotated
```

Nested Function `SSDCacheTier.enqueue_spill._is_quantized_layer` calls `isinstance`, `getattr`; has 2 explicit return paths.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `layer` | `not annotated` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `not annotated`
- Direct return expressions: `True`; `isinstance(keys, (tuple, list))`

**Exceptions and behavior**

Nested Function `SSDCacheTier.enqueue_spill._is_quantized_layer` calls `isinstance`, `getattr`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L772-L776](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L772-L776).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier._write_entry" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier._write_entry</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier._write_entry(tokens_key: tuple[int, ...], layer_snapshots: list[tuple[LayerSerializer, dict[str, Any]]], memory_bytes: int) -> None
```

Atomically persist one entry (writer thread; numpy-only input).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens_key` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |
| `layer_snapshots` | `list[tuple[LayerSerializer, dict[str, Any]]]` | `yes` | `none` | Required positional or keyword input. |
| `memory_bytes` | `int` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDCacheTier._write_entry` updates `self._stats.spill_count`, `self._stats.spill_bytes`; calls `self._entry_hash`, `os.path.join`, `os.path.exists`, `shutil.rmtree`.
No direct `raise` statement appears in this definition.

[View source #L869-L944](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L869-L944).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier.lookup_ssd" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier.lookup_ssd</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier.lookup_ssd(tokens: tuple[int, ...]) -> dict | None
```

Synchronous check whether tokens exist in SSD tier.

**Parameters**

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

**Returns**

- Type: `dict | None`
- Direct return expressions: `result`; `None`

**Exceptions and behavior**

Method `SSDCacheTier.lookup_ssd` calls `self._index.lookup_exact`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L946-L958](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L946-L958).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier.lookup_ssd_prefix" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier.lookup_ssd_prefix</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier.lookup_ssd_prefix(tokens: tuple[int, ...]) -> dict | None
```

Find the longest prefix match in the SSD tier.

**Parameters**

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

**Returns**

- Type: `dict | None`
- Direct return expressions: `results[0]`; `None`

**Exceptions and behavior**

Method `SSDCacheTier.lookup_ssd_prefix` calls `self._index.lookup_prefix`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L960-L968](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L960-L968).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier.async_promote" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier.async_promote</code> · method</summary>

```python
async vllm_mlx.ssd_cache.SSDCacheTier.async_promote(tokens: tuple[int, ...], reserve_budget_fn, release_budget_fn) -> list | None
```

Promote an entry from SSD to RAM asynchronously.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `tuple[int, ...]` | `yes` | `none` | Token sequence to promote. |
| `reserve_budget_fn` | `not annotated` | `yes` | `none` | Callable(nbytes) -> bool. Must return True if budget is available and reserved, False otherwise. |
| `release_budget_fn` | `not annotated` | `yes` | `none` | Callable(nbytes) -> None. Called to release budget on failure. |

**Returns**

- Type: `list | None`
- Direct return expressions: `None`; `cache_layers`

**Exceptions and behavior**

Method `SSDCacheTier.async_promote` updates `self._stats.ssd_misses`, `self._stats.promotion_failures`, `self._stats.ssd_hits`, `self._stats.reload_latency_sum`; calls `self._index.lookup_exact`, `reserve_budget_fn`, `logger.warning`, `time.time`; awaits asynchronous work; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L970-L1076](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L970-L1076).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier._read_entry" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier._read_entry</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier._read_entry(tokens: tuple[int, ...], relative_path: str) -> list | None
```

Read a cache entry from disk.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |
| `relative_path` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `list | None`
- Direct return expressions: `None`; `cache_layers`

**Exceptions and behavior**

Method `SSDCacheTier._read_entry` calls `os.path.join`, `open`, `json.load`, `logger.warning`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L1078-L1121](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1078-L1121).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier._quarantine_entry" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier._quarantine_entry</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier._quarantine_entry(tokens: tuple[int, ...], relative_path: str) -> None
```

Move a corrupt entry to quarantine and remove from index.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokens` | `tuple[int, ...]` | `yes` | `none` | Required positional or keyword input. |
| `relative_path` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDCacheTier._quarantine_entry` calls `os.path.join`, `os.path.exists`, `os.makedirs`, `os.path.dirname`.
No direct `raise` statement appears in this definition.

[View source #L1123-L1142](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1123-L1142).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier._enforce_capacity" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier._enforce_capacity</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier._enforce_capacity() -> None
```

Evict oldest SSD entries until within capacity limits.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `SSDCacheTier._enforce_capacity` calls `self._index.get_entry_count`, `self._index.get_total_bytes`, `self._index.get_lru`, `_blob_to_tokens`.
No direct `raise` statement appears in this definition.

[View source #L1144-L1181](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1144-L1181).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier.reconcile" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier.reconcile</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier.reconcile() -> int
```

Reconcile index with files on disk.

**Parameters**

This callable has no explicit inputs.

**Returns**

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

**Exceptions and behavior**

Method `SSDCacheTier.reconcile` calls `self._index.all_entries`, `os.path.join`, `os.path.isdir`, `os.path.exists`; returns `cleaned`.
No direct `raise` statement appears in this definition.

[View source #L1183-L1229](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1183-L1229).

</details>

<details class="api-contract" id="contract-vllm_mlx.ssd_cache.SSDCacheTier.close" markdown="1">
<summary><code>vllm_mlx.ssd_cache.SSDCacheTier.close</code> · method</summary>

```python
vllm_mlx.ssd_cache.SSDCacheTier.close() -> None
```

Close the SSD cache tier and release resources.

**Parameters**

This callable has no explicit inputs.

**Returns**

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

**Exceptions and behavior**

Method `SSDCacheTier.close` updates `self._closed`, `self._writer_thread`; calls `self._writer_stop.set`, `self._spill_queue.put_nowait`, `self._writer_thread.join`, `self._index.close`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L1231-L1248](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1231-L1248).

</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 |
| --- | --- | --- | --- | --- |
| [`SSDCacheConfig`](#contract-vllm_mlx.ssd_cache.SSDCacheConfig) | class | `SSDCacheConfig(cache_dir: str \| None = None, max_size_gb: float = 10.0, max_entries: int = 10000, file_permissions: int = 384, dir_permissions: int = 448, spill_queue_size: int = 64, retention_seconds: int \| None = None)` | Configuration for SSD cache tier. | [#L43-L78](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L43-L78) |
| [`SSDCacheConfig.__post_init__`](#contract-vllm_mlx.ssd_cache.SSDCacheConfig.__post_init__) | method | `SSDCacheConfig.__post_init__() -> None` | Method `SSDCacheConfig.__post_init__` calls `ValueError`; can raise `ValueError`. | [#L65-L73](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L65-L73) |
| [`SSDCacheConfig.max_size_bytes`](#contract-vllm_mlx.ssd_cache.SSDCacheConfig.max_size_bytes) | method | `SSDCacheConfig.max_size_bytes() -> int` | Maximum cache size in bytes. | [#L76-L78](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L76-L78) |
| [`SSDCacheStats`](#contract-vllm_mlx.ssd_cache.SSDCacheStats) | class | `SSDCacheStats(spill_count: int = 0, spill_bytes: int = 0, ssd_hits: int = 0, ssd_misses: int = 0, reload_latency_sum: float = 0.0, reload_bytes: int = 0, promotion_failures: int = 0)` | Statistics for SSD cache tier — exposed from day one. | [#L82-L123](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L82-L123) |
| [`SSDCacheStats.to_dict`](#contract-vllm_mlx.ssd_cache.SSDCacheStats.to_dict) | method | `SSDCacheStats.to_dict() -> dict` | Return spill, lookup, reload, and promotion statistics. | [#L103-L123](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L103-L123) |
| [`_tokens_to_blob`](#contract-vllm_mlx.ssd_cache._tokens_to_blob) | function | `_tokens_to_blob(tokens: tuple[int, ...]) -> bytes` | Serialize token tuple to a compact binary blob for SQLite storage. | [#L126-L132](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L126-L132) |
| [`_blob_to_tokens`](#contract-vllm_mlx.ssd_cache._blob_to_tokens) | function | `_blob_to_tokens(blob: bytes) -> tuple[int, ...]` | Deserialize binary blob back to token tuple. | [#L135-L139](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L135-L139) |
| [`_tokens_hash`](#contract-vllm_mlx.ssd_cache._tokens_hash) | function | `_tokens_hash(tokens: tuple[int, ...]) -> str` | Compute SHA-256 hex digest of a token sequence for use as primary key. | [#L142-L144](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L142-L144) |
| [`_prefix_hash`](#contract-vllm_mlx.ssd_cache._prefix_hash) | function | `_prefix_hash(tokens: tuple[int, ...]) -> str` | Hash the bounded token prefix used to prefilter prefix lookups. | [#L147-L149](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L147-L149) |
| [`SSDIndex`](#contract-vllm_mlx.ssd_cache.SSDIndex) | class | `SSDIndex(cache_dir: str)` | SQLite-backed index for SSD cache entries. | [#L152-L405](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L152-L405) |
| [`SSDIndex.__init__`](#contract-vllm_mlx.ssd_cache.SSDIndex.__init__) | method | `SSDIndex.__init__(cache_dir: str) -> None` | Method `SSDIndex.__init__` updates `self._cache_dir`, `self._db_lock`, `self._conn`, `self._conn.row_factory`; calls `threading.Lock`, `os.path.join`, `sqlite3.connect`, `self._conn.execute`. | [#L165-L173](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L165-L173) |
| [`SSDIndex._create_tables`](#contract-vllm_mlx.ssd_cache.SSDIndex._create_tables) | method | `SSDIndex._create_tables() -> None` | Method `SSDIndex._create_tables` calls `self._conn.executescript`, `self._ensure_column`, `self._conn.execute`, `cur.fetchone`. | [#L175-L213](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L175-L213) |
| [`SSDIndex._ensure_column`](#contract-vllm_mlx.ssd_cache.SSDIndex._ensure_column) | method | `SSDIndex._ensure_column(table: str, column: str, definition: str) -> None` | Method `SSDIndex._ensure_column` calls `self._conn.execute`, `cur.fetchall`. | [#L215-L218](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L215-L218) |
| [`SSDIndex._backfill_prefix_hashes`](#contract-vllm_mlx.ssd_cache.SSDIndex._backfill_prefix_hashes) | method | `SSDIndex._backfill_prefix_hashes() -> None` | Method `SSDIndex._backfill_prefix_hashes` calls `self._conn.execute`, `cur.fetchall`, `_blob_to_tokens`, `_prefix_hash`. | [#L220-L230](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L220-L230) |
| [`SSDIndex.insert_entry`](#contract-vllm_mlx.ssd_cache.SSDIndex.insert_entry) | method | `SSDIndex.insert_entry(tokens_key: tuple[int, ...], file_path: str, memory_bytes: int, num_tokens: int) -> None` | Insert or replace a cache entry in the index. | [#L232-L263](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L232-L263) |
| [`SSDIndex.lookup_exact`](#contract-vllm_mlx.ssd_cache.SSDIndex.lookup_exact) | method | `SSDIndex.lookup_exact(tokens_key: tuple[int, ...]) -> dict \| None` | Look up an exact token sequence. | [#L265-L280](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L265-L280) |
| [`SSDIndex.lookup_prefix`](#contract-vllm_mlx.ssd_cache.SSDIndex.lookup_prefix) | method | `SSDIndex.lookup_prefix(query_tokens: tuple[int, ...]) -> list[dict]` | Find entries whose token sequence is a prefix of query_tokens. | [#L282-L324](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L282-L324) |
| [`SSDIndex.delete_entry`](#contract-vllm_mlx.ssd_cache.SSDIndex.delete_entry) | method | `SSDIndex.delete_entry(tokens_key: tuple[int, ...]) -> None` | Delete an entry by token sequence. | [#L326-L333](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L326-L333) |
| [`SSDIndex.get_lru`](#contract-vllm_mlx.ssd_cache.SSDIndex.get_lru) | method | `SSDIndex.get_lru(limit: int = 10) -> list[dict]` | Get the least recently used entries, ordered oldest first. | [#L335-L355](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L335-L355) |
| [`SSDIndex.get_total_bytes`](#contract-vllm_mlx.ssd_cache.SSDIndex.get_total_bytes) | method | `SSDIndex.get_total_bytes() -> int` | Get total memory_bytes across all entries. | [#L357-L363](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L357-L363) |
| [`SSDIndex.get_entry_count`](#contract-vllm_mlx.ssd_cache.SSDIndex.get_entry_count) | method | `SSDIndex.get_entry_count() -> int` | Get number of entries in the index. | [#L365-L369](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L365-L369) |
| [`SSDIndex.touch`](#contract-vllm_mlx.ssd_cache.SSDIndex.touch) | method | `SSDIndex.touch(tokens_key: tuple[int, ...]) -> None` | Update accessed_at timestamp for an entry (marks as recently used). | [#L371-L379](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L371-L379) |
| [`SSDIndex.all_entries`](#contract-vllm_mlx.ssd_cache.SSDIndex.all_entries) | method | `SSDIndex.all_entries() -> list[dict]` | Return all entries (for startup reconciliation). | [#L381-L400](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L381-L400) |
| [`SSDIndex.close`](#contract-vllm_mlx.ssd_cache.SSDIndex.close) | method | `SSDIndex.close() -> None` | Close the SQLite connection. | [#L402-L405](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L402-L405) |
| [`LayerSerializer`](#contract-vllm_mlx.ssd_cache.LayerSerializer) | class | `LayerSerializer()` | Interface for per-layer cache serialization. | [#L419-L446](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L419-L446) |
| [`LayerSerializer.snapshot_layer`](#contract-vllm_mlx.ssd_cache.LayerSerializer.snapshot_layer) | method | `LayerSerializer.snapshot_layer(layer: Any) -> dict[str, Any]` | Producer-thread CPU snapshot of an MLX-backed cache layer. | [#L429-L431](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L429-L431) |
| [`LayerSerializer.serialize_layer`](#contract-vllm_mlx.ssd_cache.LayerSerializer.serialize_layer) | method | `LayerSerializer.serialize_layer(snapshot: dict[str, Any], layer_idx: int, file_path: str) -> dict[str, Any]` | Writer-thread: persist a snapshot to safetensors at file_path. | [#L434-L441](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L434-L441) |
| [`LayerSerializer.deserialize_layer`](#contract-vllm_mlx.ssd_cache.LayerSerializer.deserialize_layer) | method | `LayerSerializer.deserialize_layer(file_path: str, metadata: dict[str, Any]) -> dict` | Read a layer back from disk. | [#L444-L446](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L444-L446) |
| [`_mx_to_numpy_safe`](#contract-vllm_mlx.ssd_cache._mx_to_numpy_safe) | function | `_mx_to_numpy_safe(arr: Any) -> tuple[np.ndarray, str \| None]` | mx.array → np.ndarray, upcasting numpy-unsupported dtypes (bf16) to fp32. | [#L449-L467](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L449-L467) |
| [`KVCacheSerializer`](#contract-vllm_mlx.ssd_cache.KVCacheSerializer) | class | `KVCacheSerializer()` | Serializer for KVCache and RotatingKVCache layers. | [#L470-L564](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L470-L564) |
| [`KVCacheSerializer.snapshot_layer`](#contract-vllm_mlx.ssd_cache.KVCacheSerializer.snapshot_layer) | method | `KVCacheSerializer.snapshot_layer(layer: Any) -> dict[str, Any]` | Copy a KV cache layer into NumPy-backed writer-thread data. | [#L481-L515](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L481-L515) |
| [`KVCacheSerializer.serialize_layer`](#contract-vllm_mlx.ssd_cache.KVCacheSerializer.serialize_layer) | method | `KVCacheSerializer.serialize_layer(snapshot: dict[str, Any], layer_idx: int, file_path: str) -> dict[str, Any]` | Write one KV layer to safetensors and return reconstruction metadata. | [#L517-L542](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L517-L542) |
| [`KVCacheSerializer.deserialize_layer`](#contract-vllm_mlx.ssd_cache.KVCacheSerializer.deserialize_layer) | method | `KVCacheSerializer.deserialize_layer(file_path: str, metadata: dict[str, Any]) -> dict` | Load one KV layer as arrays plus cache reconstruction metadata. | [#L544-L564](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L544-L564) |
| [`ArraysCacheSerializer`](#contract-vllm_mlx.ssd_cache.ArraysCacheSerializer) | class | `ArraysCacheSerializer()` | Serializer for ArraysCache (Mamba/linear attention) layers. | [#L567-L627](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L567-L627) |
| [`ArraysCacheSerializer.snapshot_layer`](#contract-vllm_mlx.ssd_cache.ArraysCacheSerializer.snapshot_layer) | method | `ArraysCacheSerializer.snapshot_layer(layer: Any) -> dict[str, Any]` | Copy an arrays-cache state into NumPy-backed writer-thread data. | [#L573-L587](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L573-L587) |
| [`ArraysCacheSerializer.serialize_layer`](#contract-vllm_mlx.ssd_cache.ArraysCacheSerializer.serialize_layer) | method | `ArraysCacheSerializer.serialize_layer(snapshot: dict[str, Any], layer_idx: int, file_path: str) -> dict[str, Any]` | Write arrays-cache state to safetensors and return its metadata. | [#L589-L610](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L589-L610) |
| [`ArraysCacheSerializer.deserialize_layer`](#contract-vllm_mlx.ssd_cache.ArraysCacheSerializer.deserialize_layer) | method | `ArraysCacheSerializer.deserialize_layer(file_path: str, metadata: dict[str, Any]) -> dict` | Load arrays-cache state and any original dtype hints. | [#L612-L627](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L612-L627) |
| [`get_serializer_for_layer`](#contract-vllm_mlx.ssd_cache.get_serializer_for_layer) | function | `get_serializer_for_layer(layer: Any) -> LayerSerializer` | Return the appropriate serializer for a cache layer. | [#L630-L646](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L630-L646) |
| [`SSDCacheTier`](#contract-vllm_mlx.ssd_cache.SSDCacheTier) | class | `SSDCacheTier(config: SSDCacheConfig)` | Cold-tier disk cache for KV cache entries. | [#L649-L1248](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L649-L1248) |
| [`SSDCacheTier.__init__`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.__init__) | method | `SSDCacheTier.__init__(config: SSDCacheConfig) -> None` | Method `SSDCacheTier.__init__` updates `self._config`, `self._closed`, `self._writer_thread`, `self._cache_dir`; calls `ValueError`, `os.path.join`, `os.makedirs`, `SSDIndex`; can raise `ValueError`. | [#L667-L705](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L667-L705) |
| [`SSDCacheTier._entry_hash`](#contract-vllm_mlx.ssd_cache.SSDCacheTier._entry_hash) | method | `SSDCacheTier._entry_hash(tokens: tuple[int, ...]) -> str` | Compute deterministic hash for a token sequence. | [#L708-L710](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L708-L710) |
| [`SSDCacheTier.get_stats`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.get_stats) | method | `SSDCacheTier.get_stats() -> dict` | Return current SSD cache statistics. | [#L712-L714](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L712-L714) |
| [`SSDCacheTier.start_writer`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.start_writer) | method | `SSDCacheTier.start_writer() -> None` | Start the background spill writer thread. | [#L716-L725](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L716-L725) |
| [`SSDCacheTier._writer_loop`](#contract-vllm_mlx.ssd_cache.SSDCacheTier._writer_loop) | method | `SSDCacheTier._writer_loop() -> None` | Drain spill queue and persist entries. | [#L727-L744](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L727-L744) |
| [`SSDCacheTier.enqueue_spill`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.enqueue_spill) | method | `SSDCacheTier.enqueue_spill(tokens: tuple[int, ...], cache: list[Any], memory_bytes: int) -> bool` | Enqueue a cache entry for async spill to SSD. | [#L746-L867](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L746-L867) |
| [`SSDCacheTier.enqueue_spill._is_quantized_layer`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.enqueue_spill._is_quantized_layer) | nested function | `SSDCacheTier.enqueue_spill._is_quantized_layer(layer) -> not annotated` | Nested Function `SSDCacheTier.enqueue_spill._is_quantized_layer` calls `isinstance`, `getattr`; has 2 explicit return paths. | [#L772-L776](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L772-L776) |
| [`SSDCacheTier._write_entry`](#contract-vllm_mlx.ssd_cache.SSDCacheTier._write_entry) | method | `SSDCacheTier._write_entry(tokens_key: tuple[int, ...], layer_snapshots: list[tuple[LayerSerializer, dict[str, Any]]], memory_bytes: int) -> None` | Atomically persist one entry (writer thread; numpy-only input). | [#L869-L944](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L869-L944) |
| [`SSDCacheTier.lookup_ssd`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.lookup_ssd) | method | `SSDCacheTier.lookup_ssd(tokens: tuple[int, ...]) -> dict \| None` | Synchronous check whether tokens exist in SSD tier. | [#L946-L958](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L946-L958) |
| [`SSDCacheTier.lookup_ssd_prefix`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.lookup_ssd_prefix) | method | `SSDCacheTier.lookup_ssd_prefix(tokens: tuple[int, ...]) -> dict \| None` | Find the longest prefix match in the SSD tier. | [#L960-L968](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L960-L968) |
| [`SSDCacheTier.async_promote`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.async_promote) | method | `async SSDCacheTier.async_promote(tokens: tuple[int, ...], reserve_budget_fn, release_budget_fn) -> list \| None` | Promote an entry from SSD to RAM asynchronously. | [#L970-L1076](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L970-L1076) |
| [`SSDCacheTier._read_entry`](#contract-vllm_mlx.ssd_cache.SSDCacheTier._read_entry) | method | `SSDCacheTier._read_entry(tokens: tuple[int, ...], relative_path: str) -> list \| None` | Read a cache entry from disk. | [#L1078-L1121](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1078-L1121) |
| [`SSDCacheTier._quarantine_entry`](#contract-vllm_mlx.ssd_cache.SSDCacheTier._quarantine_entry) | method | `SSDCacheTier._quarantine_entry(tokens: tuple[int, ...], relative_path: str) -> None` | Move a corrupt entry to quarantine and remove from index. | [#L1123-L1142](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1123-L1142) |
| [`SSDCacheTier._enforce_capacity`](#contract-vllm_mlx.ssd_cache.SSDCacheTier._enforce_capacity) | method | `SSDCacheTier._enforce_capacity() -> None` | Evict oldest SSD entries until within capacity limits. | [#L1144-L1181](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1144-L1181) |
| [`SSDCacheTier.reconcile`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.reconcile) | method | `SSDCacheTier.reconcile() -> int` | Reconcile index with files on disk. | [#L1183-L1229](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1183-L1229) |
| [`SSDCacheTier.close`](#contract-vllm_mlx.ssd_cache.SSDCacheTier.close) | method | `SSDCacheTier.close() -> None` | Close the SSD cache tier and release resources. | [#L1231-L1248](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/ssd_cache.py#L1231-L1248) |