# `vllm_mlx.vision_embedding_cache`

Vision Embedding Cache for MLLM continuous batching.

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

## 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.vision_embedding_cache
    options:
      members:
        - logger
        - VisionCacheStats
        - PixelCacheEntry
        - PixelOnlyCacheEntry
        - EncodingCacheEntry
        - compute_image_hash
        - compute_images_hash
        - VisionEmbeddingCache
      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.vision_embedding_cache.VisionCacheStats" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionCacheStats</code> · class</summary>

```python
vllm_mlx.vision_embedding_cache.VisionCacheStats(pixel_cache_hits: int = 0, pixel_cache_misses: int = 0, encoding_cache_hits: int = 0, encoding_cache_misses: int = 0, total_time_saved: float = 0.0, total_images_processed: int = 0)
```

Statistics for vision cache performance.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `pixel_cache_hits` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `pixel_cache_misses` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `encoding_cache_hits` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `encoding_cache_misses` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |
| `total_time_saved` | `float` | `no` | `0.0` | Optional constructor field; defaults to `0.0`. |
| `total_images_processed` | `int` | `no` | `0` | Optional constructor field; defaults to `0`. |

**Returns**

- Constructs: `vllm_mlx.vision_embedding_cache.VisionCacheStats`

**Exceptions and behavior**

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

[View source #L30-L66](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L30-L66).

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionCacheStats.pixel_hit_rate" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionCacheStats.pixel_hit_rate</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionCacheStats.pixel_hit_rate() -> float
```

Return successful pixel-cache lookups divided by all pixel lookups.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `float`
- Direct return expressions: `self.pixel_cache_hits / total if total > 0 else 0.0`

**Exceptions and behavior**

Method `VisionCacheStats.pixel_hit_rate` returns `self.pixel_cache_hits / total if total > 0 else 0.0`.
No direct `raise` statement appears in this definition.

[View source #L41-L45](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L41-L45).

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionCacheStats.encoding_hit_rate" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionCacheStats.encoding_hit_rate</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionCacheStats.encoding_hit_rate() -> float
```

Return successful encoding lookups divided by all encoding lookups.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `float`
- Direct return expressions: `self.encoding_cache_hits / total if total > 0 else 0.0`

**Exceptions and behavior**

Method `VisionCacheStats.encoding_hit_rate` returns `self.encoding_cache_hits / total if total > 0 else 0.0`.
No direct `raise` statement appears in this definition.

[View source #L48-L52](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L48-L52).

</details>

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

```python
vllm_mlx.vision_embedding_cache.VisionCacheStats.to_dict() -> dict
```

Return pixel, encoding, timing, and image counters.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict`
- Direct return expressions: `{'pixel_cache_hits': self.pixel_cache_hits, 'pixel_cache_misses': self.pixel_cache_misses, 'pixel_hit_rate': self.pixel…`

**Exceptions and behavior**

Method `VisionCacheStats.to_dict` returns `{'pixel_cache_hits': self.pixel_cache_hits, 'pixel_cache_misses': self.pixel_cache_misses, 'pixel_hit_rate': self.pixel…`.
No direct `raise` statement appears in this definition.

[View source #L54-L66](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L54-L66).

</details>

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

```python
vllm_mlx.vision_embedding_cache.PixelCacheEntry(pixel_values: mx.array, input_ids: mx.array, attention_mask: Optional[mx.array], image_grid_thw: Optional[mx.array], extra_kwargs: Dict[str, Any], processing_time: float = 0.0)
```

Cached pixel values from prepare_inputs.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `pixel_values` | `mx.array` | `yes` | `none` | Required constructor field. |
| `input_ids` | `mx.array` | `yes` | `none` | Required constructor field. |
| `attention_mask` | `Optional[mx.array]` | `yes` | `none` | Required constructor field. |
| `image_grid_thw` | `Optional[mx.array]` | `yes` | `none` | Required constructor field. |
| `extra_kwargs` | `Dict[str, Any]` | `yes` | `none` | Required constructor field. |
| `processing_time` | `float` | `no` | `0.0` | Optional constructor field; defaults to `0.0`. |

**Returns**

- Constructs: `vllm_mlx.vision_embedding_cache.PixelCacheEntry`

**Exceptions and behavior**

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

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

</details>

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

```python
vllm_mlx.vision_embedding_cache.PixelOnlyCacheEntry(pixel_values: mx.array, image_grid_thw: Optional[mx.array], processing_time: float = 0.0)
```

Cached pixel values only (prompt-independent).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `pixel_values` | `mx.array` | `yes` | `none` | Required constructor field. |
| `image_grid_thw` | `Optional[mx.array]` | `yes` | `none` | Required constructor field. |
| `processing_time` | `float` | `no` | `0.0` | Optional constructor field; defaults to `0.0`. |

**Returns**

- Constructs: `vllm_mlx.vision_embedding_cache.PixelOnlyCacheEntry`

**Exceptions and behavior**

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

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

</details>

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

```python
vllm_mlx.vision_embedding_cache.EncodingCacheEntry(logits: mx.array, first_token: int, logprobs: mx.array, encoding_time: float = 0.0)
```

Cached vision encoding output.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `logits` | `mx.array` | `yes` | `none` | Required constructor field. |
| `first_token` | `int` | `yes` | `none` | Required constructor field. |
| `logprobs` | `mx.array` | `yes` | `none` | Required constructor field. |
| `encoding_time` | `float` | `no` | `0.0` | Optional constructor field; defaults to `0.0`. |

**Returns**

- Constructs: `vllm_mlx.vision_embedding_cache.EncodingCacheEntry`

**Exceptions and behavior**

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

[View source #L96-L102](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L96-L102).

</details>

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

```python
vllm_mlx.vision_embedding_cache.compute_image_hash(image_path: str) -> str
```

Compute hash of image content.

**Parameters**

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

**Returns**

- Type: `str`
- Direct return expressions: `hashlib.sha256(content).hexdigest()[:16]`; `hashlib.sha256(image_path.encode()).hexdigest()[:16]`; `hashlib.sha256(str(image_path).encode()).hexdigest()[:16]`

**Exceptions and behavior**

Function `compute_image_hash` calls `Path`, `path.exists`, `path.is_file`, `open`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L105-L124](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L105-L124).

</details>

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

```python
vllm_mlx.vision_embedding_cache.compute_images_hash(images: List[str]) -> str
```

Compute combined hash for multiple images.

**Parameters**

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

**Returns**

- Type: `str`
- Direct return expressions: `'no_images'`; `hashlib.sha256('_'.join(hashes).encode()).hexdigest()[:16]`

**Exceptions and behavior**

Function `compute_images_hash` calls `sorted`, `compute_image_hash`, `hashlib.sha256('_'.join(hashes).encode()).hexdigest`, `hashlib.sha256`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

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

</details>

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

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache(max_pixel_entries: int = 100, max_encoding_entries: int = 50, enabled: bool = True)
```

Two-level cache for vision processing in MLLM.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `max_pixel_entries` | `int` | `no` | `100` | Max entries in pixel cache (LRU eviction) |
| `max_encoding_entries` | `int` | `no` | `50` | Max entries in encoding cache |
| `enabled` | `bool` | `no` | `True` | Whether caching is enabled |

**Returns**

- Constructs: `vllm_mlx.vision_embedding_cache.VisionEmbeddingCache`

**Exceptions and behavior**

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

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

</details>

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

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.__init__(max_pixel_entries: int = 100, max_encoding_entries: int = 50, enabled: bool = True) -> not annotated
```

Initialize the vision embedding cache.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `max_pixel_entries` | `int` | `no` | `100` | Max entries in pixel cache (LRU eviction) |
| `max_encoding_entries` | `int` | `no` | `50` | Max entries in encoding cache |
| `enabled` | `bool` | `no` | `True` | Whether caching is enabled |

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Method `VisionEmbeddingCache.__init__` updates `self.max_pixel_entries`, `self.max_encoding_entries`, `self.enabled`, `self._pixel_cache`; calls `OrderedDict`, `VisionCacheStats`.
No direct `raise` statement appears in this definition.

[View source #L162-L185](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L162-L185).

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache._make_key" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionEmbeddingCache._make_key</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache._make_key(images: List[str], prompt: str) -> str
```

Create cache key from images and prompt.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `images` | `List[str]` | `yes` | `none` | Required positional or keyword input. |
| `prompt` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `f'{img_hash}_{prompt_hash}'`

**Exceptions and behavior**

Method `VisionEmbeddingCache._make_key` calls `compute_images_hash`, `hashlib.sha256(prompt.encode()).hexdigest`, `hashlib.sha256`, `prompt.encode`; returns `f'{img_hash}_{prompt_hash}'`.
No direct `raise` statement appears in this definition.

[View source #L187-L192](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L187-L192).

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache._make_image_only_key" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionEmbeddingCache._make_image_only_key</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache._make_image_only_key(images: List[str]) -> str
```

Create cache key from images only (prompt-independent).

**Parameters**

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

**Returns**

- Type: `str`
- Direct return expressions: `compute_images_hash(images)`

**Exceptions and behavior**

Method `VisionEmbeddingCache._make_image_only_key` calls `compute_images_hash`; returns `compute_images_hash(images)`.
No direct `raise` statement appears in this definition.

[View source #L194-L196](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L194-L196).

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_pixel_cache" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_pixel_cache</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_pixel_cache(images: List[str], prompt: str) -> Optional[PixelCacheEntry]
```

Get cached pixel values for images+prompt.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `images` | `List[str]` | `yes` | `none` | Required positional or keyword input. |
| `prompt` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Optional[PixelCacheEntry]`
- Direct return expressions: `None`; `entry`

**Exceptions and behavior**

Method `VisionEmbeddingCache.get_pixel_cache` updates `self.stats.pixel_cache_hits`, `self.stats.total_time_saved`, `self.stats.pixel_cache_misses`; calls `self._make_key`, `self._pixel_cache.pop`, `logger.debug`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L200-L229](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L200-L229).

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_pixel_cache" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_pixel_cache</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_pixel_cache(images: List[str], prompt: str, pixel_values: mx.array, input_ids: mx.array, attention_mask: Optional[mx.array] = None, image_grid_thw: Optional[mx.array] = None, extra_kwargs: Optional[Dict[str, Any]] = None, processing_time: float = 0.0) -> None
```

Store pixel values in cache.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `images` | `List[str]` | `yes` | `none` | Required positional or keyword input. |
| `prompt` | `str` | `yes` | `none` | Required positional or keyword input. |
| `pixel_values` | `mx.array` | `yes` | `none` | Required positional or keyword input. |
| `input_ids` | `mx.array` | `yes` | `none` | Required positional or keyword input. |
| `attention_mask` | `Optional[mx.array]` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `image_grid_thw` | `Optional[mx.array]` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `extra_kwargs` | `Optional[Dict[str, Any]]` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `processing_time` | `float` | `no` | `0.0` | Optional positional or keyword input; defaults to `0.0`. |

**Returns**

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

**Exceptions and behavior**

Method `VisionEmbeddingCache.set_pixel_cache` updates `self.stats.total_images_processed`; calls `self._make_key`, `len`, `next`, `iter`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L231-L264](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L231-L264).

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_pixel_values" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_pixel_values</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_pixel_values(images: List[str]) -> Optional[PixelOnlyCacheEntry]
```

Get cached pixel values for images (prompt-independent).

**Parameters**

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

**Returns**

- Type: `Optional[PixelOnlyCacheEntry]`
- Direct return expressions: `None`; `entry`

**Exceptions and behavior**

Method `VisionEmbeddingCache.get_pixel_values` updates `self.stats.pixel_cache_hits`, `self.stats.total_time_saved`, `self.stats.pixel_cache_misses`; calls `self._make_image_only_key`, `self._pixel_only_cache.pop`, `logger.debug`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L268-L299](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L268-L299).

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_pixel_values" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_pixel_values</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_pixel_values(images: List[str], pixel_values: mx.array, image_grid_thw: Optional[mx.array] = None, processing_time: float = 0.0) -> None
```

Store pixel values in cache (prompt-independent).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `images` | `List[str]` | `yes` | `none` | Required positional or keyword input. |
| `pixel_values` | `mx.array` | `yes` | `none` | Required positional or keyword input. |
| `image_grid_thw` | `Optional[mx.array]` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `processing_time` | `float` | `no` | `0.0` | Optional positional or keyword input; defaults to `0.0`. |

**Returns**

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

**Exceptions and behavior**

Method `VisionEmbeddingCache.set_pixel_values` calls `self._make_image_only_key`, `len`, `next`, `iter`; returns `None`.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_encoding_cache" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_encoding_cache</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_encoding_cache(images: List[str], prompt: str) -> Optional[EncodingCacheEntry]
```

Get cached vision encoding output.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `images` | `List[str]` | `yes` | `none` | Required positional or keyword input. |
| `prompt` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Optional[EncodingCacheEntry]`
- Direct return expressions: `None`; `entry`

**Exceptions and behavior**

Method `VisionEmbeddingCache.get_encoding_cache` updates `self.stats.encoding_cache_hits`, `self.stats.total_time_saved`, `self.stats.encoding_cache_misses`; calls `self._make_key`, `self._encoding_cache.pop`, `logger.debug`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_encoding_cache" markdown="1">
<summary><code>vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_encoding_cache</code> · method</summary>

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_encoding_cache(images: List[str], prompt: str, logits: mx.array, first_token: int, logprobs: mx.array, encoding_time: float = 0.0) -> None
```

Store vision encoding output in cache.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `images` | `List[str]` | `yes` | `none` | Required positional or keyword input. |
| `prompt` | `str` | `yes` | `none` | Required positional or keyword input. |
| `logits` | `mx.array` | `yes` | `none` | Required positional or keyword input. |
| `first_token` | `int` | `yes` | `none` | Required positional or keyword input. |
| `logprobs` | `mx.array` | `yes` | `none` | Required positional or keyword input. |
| `encoding_time` | `float` | `no` | `0.0` | Optional positional or keyword input; defaults to `0.0`. |

**Returns**

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

**Exceptions and behavior**

Method `VisionEmbeddingCache.set_encoding_cache` calls `self._make_key`, `len`, `next`, `iter`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L360-L388](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L360-L388).

</details>

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

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_stats() -> dict
```

Get cache statistics.

**Parameters**

This callable has no explicit inputs.

**Returns**

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

**Exceptions and behavior**

Method `VisionEmbeddingCache.get_stats` calls `self.stats.to_dict`, `len`; returns `stats`.
No direct `raise` statement appears in this definition.

[View source #L392-L398](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L392-L398).

</details>

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

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.clear() -> None
```

Clear all caches and reset stats.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `VisionEmbeddingCache.clear` updates `self.stats`; calls `self._pixel_cache.clear`, `self._pixel_only_cache.clear`, `self._encoding_cache.clear`, `VisionCacheStats`.
No direct `raise` statement appears in this definition.

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

</details>

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

```python
vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.__repr__() -> str
```

Method `VisionEmbeddingCache.__repr__` calls `len`; returns `f'<VisionEmbeddingCache pixel={len(self._pixel_cache)}/{self.max_pixel_entries} pixel_only={len(self._pixel_only_cache)…`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `str`
- Direct return expressions: `f'<VisionEmbeddingCache pixel={len(self._pixel_cache)}/{self.max_pixel_entries} pixel_only={len(self._pixel_only_cache)…`

**Exceptions and behavior**

Method `VisionEmbeddingCache.__repr__` calls `len`; returns `f'<VisionEmbeddingCache pixel={len(self._pixel_cache)}/{self.max_pixel_entries} pixel_only={len(self._pixel_only_cache)…`.
No direct `raise` statement appears in this definition.

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

</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 |
| --- | --- | --- | --- | --- |
| [`VisionCacheStats`](#contract-vllm_mlx.vision_embedding_cache.VisionCacheStats) | class | `VisionCacheStats(pixel_cache_hits: int = 0, pixel_cache_misses: int = 0, encoding_cache_hits: int = 0, encoding_cache_misses: int = 0, total_time_saved: float = 0.0, total_images_processed: int = 0)` | Statistics for vision cache performance. | [#L30-L66](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L30-L66) |
| [`VisionCacheStats.pixel_hit_rate`](#contract-vllm_mlx.vision_embedding_cache.VisionCacheStats.pixel_hit_rate) | method | `VisionCacheStats.pixel_hit_rate() -> float` | Return successful pixel-cache lookups divided by all pixel lookups. | [#L41-L45](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L41-L45) |
| [`VisionCacheStats.encoding_hit_rate`](#contract-vllm_mlx.vision_embedding_cache.VisionCacheStats.encoding_hit_rate) | method | `VisionCacheStats.encoding_hit_rate() -> float` | Return successful encoding lookups divided by all encoding lookups. | [#L48-L52](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L48-L52) |
| [`VisionCacheStats.to_dict`](#contract-vllm_mlx.vision_embedding_cache.VisionCacheStats.to_dict) | method | `VisionCacheStats.to_dict() -> dict` | Return pixel, encoding, timing, and image counters. | [#L54-L66](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L54-L66) |
| [`PixelCacheEntry`](#contract-vllm_mlx.vision_embedding_cache.PixelCacheEntry) | class | `PixelCacheEntry(pixel_values: mx.array, input_ids: mx.array, attention_mask: Optional[mx.array], image_grid_thw: Optional[mx.array], extra_kwargs: Dict[str, Any], processing_time: float = 0.0)` | Cached pixel values from prepare_inputs. | [#L70-L78](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L70-L78) |
| [`PixelOnlyCacheEntry`](#contract-vllm_mlx.vision_embedding_cache.PixelOnlyCacheEntry) | class | `PixelOnlyCacheEntry(pixel_values: mx.array, image_grid_thw: Optional[mx.array], processing_time: float = 0.0)` | Cached pixel values only (prompt-independent). | [#L82-L92](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L82-L92) |
| [`EncodingCacheEntry`](#contract-vllm_mlx.vision_embedding_cache.EncodingCacheEntry) | class | `EncodingCacheEntry(logits: mx.array, first_token: int, logprobs: mx.array, encoding_time: float = 0.0)` | Cached vision encoding output. | [#L96-L102](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L96-L102) |
| [`compute_image_hash`](#contract-vllm_mlx.vision_embedding_cache.compute_image_hash) | function | `compute_image_hash(image_path: str) -> str` | Compute hash of image content. | [#L105-L124](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L105-L124) |
| [`compute_images_hash`](#contract-vllm_mlx.vision_embedding_cache.compute_images_hash) | function | `compute_images_hash(images: List[str]) -> str` | Compute combined hash for multiple images. | [#L127-L132](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L127-L132) |
| [`VisionEmbeddingCache`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache) | class | `VisionEmbeddingCache(max_pixel_entries: int = 100, max_encoding_entries: int = 50, enabled: bool = True)` | Two-level cache for vision processing in MLLM. | [#L135-L413](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L135-L413) |
| [`VisionEmbeddingCache.__init__`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.__init__) | method | `VisionEmbeddingCache.__init__(max_pixel_entries: int = 100, max_encoding_entries: int = 50, enabled: bool = True) -> not annotated` | Initialize the vision embedding cache. | [#L162-L185](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L162-L185) |
| [`VisionEmbeddingCache._make_key`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache._make_key) | method | `VisionEmbeddingCache._make_key(images: List[str], prompt: str) -> str` | Create cache key from images and prompt. | [#L187-L192](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L187-L192) |
| [`VisionEmbeddingCache._make_image_only_key`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache._make_image_only_key) | method | `VisionEmbeddingCache._make_image_only_key(images: List[str]) -> str` | Create cache key from images only (prompt-independent). | [#L194-L196](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L194-L196) |
| [`VisionEmbeddingCache.get_pixel_cache`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_pixel_cache) | method | `VisionEmbeddingCache.get_pixel_cache(images: List[str], prompt: str) -> Optional[PixelCacheEntry]` | Get cached pixel values for images+prompt. | [#L200-L229](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L200-L229) |
| [`VisionEmbeddingCache.set_pixel_cache`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_pixel_cache) | method | `VisionEmbeddingCache.set_pixel_cache(images: List[str], prompt: str, pixel_values: mx.array, input_ids: mx.array, attention_mask: Optional[mx.array] = None, image_grid_thw: Optional[mx.array] = None, extra_kwargs: Optional[Dict[str, Any]] = None, processing_time: float = 0.0) -> None` | Store pixel values in cache. | [#L231-L264](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L231-L264) |
| [`VisionEmbeddingCache.get_pixel_values`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_pixel_values) | method | `VisionEmbeddingCache.get_pixel_values(images: List[str]) -> Optional[PixelOnlyCacheEntry]` | Get cached pixel values for images (prompt-independent). | [#L268-L299](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L268-L299) |
| [`VisionEmbeddingCache.set_pixel_values`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_pixel_values) | method | `VisionEmbeddingCache.set_pixel_values(images: List[str], pixel_values: mx.array, image_grid_thw: Optional[mx.array] = None, processing_time: float = 0.0) -> None` | Store pixel values in cache (prompt-independent). | [#L301-L326](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L301-L326) |
| [`VisionEmbeddingCache.get_encoding_cache`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_encoding_cache) | method | `VisionEmbeddingCache.get_encoding_cache(images: List[str], prompt: str) -> Optional[EncodingCacheEntry]` | Get cached vision encoding output. | [#L330-L358](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L330-L358) |
| [`VisionEmbeddingCache.set_encoding_cache`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.set_encoding_cache) | method | `VisionEmbeddingCache.set_encoding_cache(images: List[str], prompt: str, logits: mx.array, first_token: int, logprobs: mx.array, encoding_time: float = 0.0) -> None` | Store vision encoding output in cache. | [#L360-L388](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L360-L388) |
| [`VisionEmbeddingCache.get_stats`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.get_stats) | method | `VisionEmbeddingCache.get_stats() -> dict` | Get cache statistics. | [#L392-L398](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L392-L398) |
| [`VisionEmbeddingCache.clear`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.clear) | method | `VisionEmbeddingCache.clear() -> None` | Clear all caches and reset stats. | [#L400-L405](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L400-L405) |
| [`VisionEmbeddingCache.__repr__`](#contract-vllm_mlx.vision_embedding_cache.VisionEmbeddingCache.__repr__) | method | `VisionEmbeddingCache.__repr__() -> str` | Method `VisionEmbeddingCache.__repr__` calls `len`; returns `f'<VisionEmbeddingCache pixel={len(self._pixel_cache)}/{self.max_pixel_entries} pixel_only={len(self._pixel_only_cache)…`. | [#L407-L413](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/vision_embedding_cache.py#L407-L413) |