# `vllm_mlx.constrained.cache`

Cache of ``TokenEnforcerTokenizerData`` objects keyed by tokenizer identity.

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

## 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.constrained.cache
    options:
      members:
        - logger
        - _CACHE
        - _CACHE_LOCK
        - _resolve_inner_tokenizer
        - _build_regular_tokens_list
        - _get_eos_token_id
        - _get_vocab_size
        - _decode_function
        - get_tokenizer_data
        - clear_cache
      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.constrained.cache._resolve_inner_tokenizer" markdown="1">
<summary><code>vllm_mlx.constrained.cache._resolve_inner_tokenizer</code> · function</summary>

```python
vllm_mlx.constrained.cache._resolve_inner_tokenizer(tokenizer: Any) -> Any
```

VLM processors wrap the actual tokenizer under ``processor.tokenizer``.

**Parameters**

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

**Returns**

- Type: `Any`
- Direct return expressions: `tokenizer`

**Exceptions and behavior**

Function `_resolve_inner_tokenizer` calls `getattr`, `hasattr`; returns `tokenizer`.
No direct `raise` statement appears in this definition.

[View source #L26-L53](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L26-L53).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.cache._build_regular_tokens_list" markdown="1">
<summary><code>vllm_mlx.constrained.cache._build_regular_tokens_list</code> · function</summary>

```python
vllm_mlx.constrained.cache._build_regular_tokens_list(tokenizer: Any, vocab_size: int) -> list[tuple[int, str, bool]]
```

Enumerate the regular (non-special) tokens in the vocabulary and produce the ``(token_id, decoded_with_leading_space_marker, is_word_start)`` tuples required by ``TokenEnforcerTokenizerData``.

**Parameters**

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

**Returns**

- Type: `list[tuple[int, str, bool]]`
- Direct return expressions: `regular_tokens`

**Exceptions and behavior**

Function `_build_regular_tokens_list` calls `set`, `tokenizer.encode`, `range`, `tokenizer.decode`; returns `regular_tokens`.
No direct `raise` statement appears in this definition.

[View source #L56-L95](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L56-L95).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.cache._get_eos_token_id" markdown="1">
<summary><code>vllm_mlx.constrained.cache._get_eos_token_id</code> · function</summary>

```python
vllm_mlx.constrained.cache._get_eos_token_id(tokenizer: Any) -> int | list[int]
```

Function `_get_eos_token_id` calls `getattr`, `isinstance`, `list`; has 3 explicit return paths.

**Parameters**

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

**Returns**

- Type: `int | list[int]`
- Direct return expressions: `list(eos_list)`; `eos`; `0`

**Exceptions and behavior**

Function `_get_eos_token_id` calls `getattr`, `isinstance`, `list`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L98-L111](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L98-L111).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.cache._get_vocab_size" markdown="1">
<summary><code>vllm_mlx.constrained.cache._get_vocab_size</code> · function</summary>

```python
vllm_mlx.constrained.cache._get_vocab_size(tokenizer: Any) -> int
```

Function `_get_vocab_size` calls `getattr`, `isinstance`, `len`, `callable`; can raise `ValueError`; has 3 explicit return paths.

**Parameters**

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

**Returns**

- Type: `int`
- Direct return expressions: `vs`; `len(tokenizer)`; `len(get_vocab())`

**Exceptions and behavior**

Function `_get_vocab_size` calls `getattr`, `isinstance`, `len`, `callable`; can raise `ValueError`; has 3 explicit return paths.
Directly raised exceptions: `ValueError`.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.cache._decode_function" markdown="1">
<summary><code>vllm_mlx.constrained.cache._decode_function</code> · function</summary>

```python
vllm_mlx.constrained.cache._decode_function(tokenizer: Any, tokens: list[int]) -> str
```

Function `_decode_function` calls `tokenizer.decode`, `isinstance`, `decoded.rstrip`; has 2 explicit return paths.

**Parameters**

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

**Returns**

- Type: `str`
- Direct return expressions: `''`; `decoded.rstrip('�') if isinstance(decoded, str) else ''`

**Exceptions and behavior**

Function `_decode_function` calls `tokenizer.decode`, `isinstance`, `decoded.rstrip`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L128-L133](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L128-L133).

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.cache.get_tokenizer_data" markdown="1">
<summary><code>vllm_mlx.constrained.cache.get_tokenizer_data</code> · function</summary>

```python
vllm_mlx.constrained.cache.get_tokenizer_data(tokenizer: Any) -> Any | None
```

Return a cached ``TokenEnforcerTokenizerData`` for ``tokenizer``.

**Parameters**

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

**Returns**

- Type: `Any | None`
- Direct return expressions: `None`; `cached`; `data`

**Exceptions and behavior**

Function `get_tokenizer_data` calls `_resolve_inner_tokenizer`, `id`, `_CACHE.get`, `_get_vocab_size`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.constrained.cache.clear_cache" markdown="1">
<summary><code>vllm_mlx.constrained.cache.clear_cache</code> · function</summary>

```python
vllm_mlx.constrained.cache.clear_cache() -> None
```

Drop the cache (mainly for tests).

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Function `clear_cache` calls `_CACHE.clear`.
No direct `raise` statement appears in this definition.

[View source #L183-L186](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L183-L186).

</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 |
| --- | --- | --- | --- | --- |
| [`_resolve_inner_tokenizer`](#contract-vllm_mlx.constrained.cache._resolve_inner_tokenizer) | function | `_resolve_inner_tokenizer(tokenizer: Any) -> Any` | VLM processors wrap the actual tokenizer under ``processor.tokenizer``. | [#L26-L53](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L26-L53) |
| [`_build_regular_tokens_list`](#contract-vllm_mlx.constrained.cache._build_regular_tokens_list) | function | `_build_regular_tokens_list(tokenizer: Any, vocab_size: int) -> list[tuple[int, str, bool]]` | Enumerate the regular (non-special) tokens in the vocabulary and produce the ``(token_id, decoded_with_leading_space_marker, is_word_start)`` tuples required by ``TokenEnforcerTokenizerData``. | [#L56-L95](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L56-L95) |
| [`_get_eos_token_id`](#contract-vllm_mlx.constrained.cache._get_eos_token_id) | function | `_get_eos_token_id(tokenizer: Any) -> int \| list[int]` | Function `_get_eos_token_id` calls `getattr`, `isinstance`, `list`; has 3 explicit return paths. | [#L98-L111](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L98-L111) |
| [`_get_vocab_size`](#contract-vllm_mlx.constrained.cache._get_vocab_size) | function | `_get_vocab_size(tokenizer: Any) -> int` | Function `_get_vocab_size` calls `getattr`, `isinstance`, `len`, `callable`; can raise `ValueError`; has 3 explicit return paths. | [#L114-L125](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L114-L125) |
| [`_decode_function`](#contract-vllm_mlx.constrained.cache._decode_function) | function | `_decode_function(tokenizer: Any, tokens: list[int]) -> str` | Function `_decode_function` calls `tokenizer.decode`, `isinstance`, `decoded.rstrip`; has 2 explicit return paths. | [#L128-L133](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L128-L133) |
| [`get_tokenizer_data`](#contract-vllm_mlx.constrained.cache.get_tokenizer_data) | function | `get_tokenizer_data(tokenizer: Any) -> Any \| None` | Return a cached ``TokenEnforcerTokenizerData`` for ``tokenizer``. | [#L136-L180](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L136-L180) |
| [`clear_cache`](#contract-vllm_mlx.constrained.cache.clear_cache) | function | `clear_cache() -> None` | Drop the cache (mainly for tests). | [#L183-L186](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/constrained/cache.py#L183-L186) |