# `vllm_mlx.prompt_warmup`

Prompt warm-up for vllm-mlx.

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

## 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.prompt_warmup
    options:
      members:
        - logger
        - load_warmup_file
        - _ensure_user_terminator
        - _build_strict_prefix_string
        - warm_prefix_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.prompt_warmup.load_warmup_file" markdown="1">
<summary><code>vllm_mlx.prompt_warmup.load_warmup_file</code> · function</summary>

```python
vllm_mlx.prompt_warmup.load_warmup_file(path: str) -> list[list[dict[str, Any]]]
```

Load and validate a warm-up prompts JSON file.

**Parameters**

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

**Returns**

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

**Exceptions and behavior**

Function `load_warmup_file` calls `Path(path).expanduser`, `Path`, `p.exists`, `FileNotFoundError`; can raise `FileNotFoundError`, `ValueError`; returns `data`.
Directly raised exceptions: `FileNotFoundError`, `ValueError`.

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

</details>

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

```python
vllm_mlx.prompt_warmup._ensure_user_terminator(messages: list[dict[str, Any]]) -> list[dict[str, Any]]
```

Ensure the message list ends with a user message.

**Parameters**

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

**Returns**

- Type: `list[dict[str, Any]]`
- Direct return expressions: `messages`; `[*messages, {'role': 'user', 'content': ' '}]`

**Exceptions and behavior**

Function `_ensure_user_terminator` calls `messages[-1].get`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L79-L91](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L79-L91).

</details>

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

```python
vllm_mlx.prompt_warmup._build_strict_prefix_string(tokenizer: Any, messages: list[dict[str, Any]], enable_thinking: bool = True) -> str | None
```

Build a STRING prefix that is a prefix of any real request's rendered chat template for the same system and empty chat history.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tokenizer` | `Any` | `yes` | `none` | Required positional or keyword input. |
| `messages` | `list[dict[str, Any]]` | `yes` | `none` | Required positional or keyword input. |
| `enable_thinking` | `bool` | `no` | `True` | Optional positional or keyword input; defaults to `True`. |

**Returns**

- Type: `str | None`
- Direct return expressions: `None`; `a[:boundary]`

**Exceptions and behavior**

Function `_build_strict_prefix_string` calls `getattr`, `apply`, `_with_user`, `kwargs.pop`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L94-L176](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L94-L176).

</details>

<details class="api-contract" id="contract-vllm_mlx.prompt_warmup._build_strict_prefix_string._with_user" markdown="1">
<summary><code>vllm_mlx.prompt_warmup._build_strict_prefix_string._with_user</code> · nested function</summary>

```python
vllm_mlx.prompt_warmup._build_strict_prefix_string._with_user(user_content: str) -> list[dict[str, Any]]
```

Nested Function `_build_strict_prefix_string._with_user` calls `dict`, `msgs[-1].get`; returns `msgs`.

**Parameters**

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

**Returns**

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

**Exceptions and behavior**

Nested Function `_build_strict_prefix_string._with_user` calls `dict`, `msgs[-1].get`; returns `msgs`.
No direct `raise` statement appears in this definition.

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

</details>

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

```python
async vllm_mlx.prompt_warmup.warm_prefix_cache(engine: Any, prompts: list[list[dict[str, Any]]], *, max_tokens: int = 1) -> dict[str, Any]
```

Run each prompt through the engine to populate the prefix cache.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `engine` | `Any` | `yes` | `none` | The vllm-mlx engine (exposes ``stream_chat`` and optionally ``tokenizer`` + ``stream_generate``). |
| `prompts` | `list[list[dict[str, Any]]]` | `yes` | `none` | List of message arrays. |
| `max_tokens` | `int` | `no` | `1` | Tokens to generate per warm-up. 1 is enough. |

**Returns**

- Type: `dict[str, Any]`
- Direct return expressions: `{'count': completed, 'skipped': skipped, 'elapsed_ms': elapsed_ms, 'total_prompt_tokens': total_prompt_tokens, 'mode': …`

**Exceptions and behavior**

Function `warm_prefix_cache` calls `getattr`, `hasattr`, `time.perf_counter`, `asyncio.gather`; awaits asynchronous work; returns `{'count': completed, 'skipped': skipped, 'elapsed_ms': elapsed_ms, 'total_prompt_tokens': total_prompt_tokens, 'mode': …`.
No direct `raise` statement appears in this definition.

[View source #L179-L275](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L179-L275).

</details>

<details class="api-contract" id="contract-vllm_mlx.prompt_warmup.warm_prefix_cache._one_strict" markdown="1">
<summary><code>vllm_mlx.prompt_warmup.warm_prefix_cache._one_strict</code> · nested function</summary>

```python
async vllm_mlx.prompt_warmup.warm_prefix_cache._one_strict(idx: int, messages: list[dict[str, Any]]) -> tuple[int, int, str | None]
```

Nested Function `warm_prefix_cache._one_strict` calls `_build_strict_prefix_string`, `_one_chat`, `engine.stream_generate`, `int`; awaits asynchronous work; has 3 explicit return paths.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `idx` | `int` | `yes` | `none` | Required positional or keyword input. |
| `messages` | `list[dict[str, Any]]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[int, int, str | None]`
- Direct return expressions: `await _one_chat(idx, messages)`; `(1, int(output.prompt_tokens or 0), None)`; `(0, 0, 'no finished output')`

**Exceptions and behavior**

Nested Function `warm_prefix_cache._one_strict` calls `_build_strict_prefix_string`, `_one_chat`, `engine.stream_generate`, `int`; awaits asynchronous work; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L217-L235](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L217-L235).

</details>

<details class="api-contract" id="contract-vllm_mlx.prompt_warmup.warm_prefix_cache._one_chat" markdown="1">
<summary><code>vllm_mlx.prompt_warmup.warm_prefix_cache._one_chat</code> · nested function</summary>

```python
async vllm_mlx.prompt_warmup.warm_prefix_cache._one_chat(idx: int, messages: list[dict[str, Any]]) -> tuple[int, int, str | None]
```

Nested Function `warm_prefix_cache._one_chat` calls `_ensure_user_terminator`, `engine.stream_chat`, `int`, `type`; has 3 explicit return paths.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `idx` | `int` | `yes` | `none` | Required positional or keyword input. |
| `messages` | `list[dict[str, Any]]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[int, int, str | None]`
- Direct return expressions: `(1, int(output.prompt_tokens or 0), None)`; `(0, 0, 'no finished output')`; `(0, 0, err)`

**Exceptions and behavior**

Nested Function `warm_prefix_cache._one_chat` calls `_ensure_user_terminator`, `engine.stream_chat`, `int`, `type`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L237-L253](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L237-L253).

</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 |
| --- | --- | --- | --- | --- |
| [`load_warmup_file`](#contract-vllm_mlx.prompt_warmup.load_warmup_file) | function | `load_warmup_file(path: str) -> list[list[dict[str, Any]]]` | Load and validate a warm-up prompts JSON file. | [#L41-L76](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L41-L76) |
| [`_ensure_user_terminator`](#contract-vllm_mlx.prompt_warmup._ensure_user_terminator) | function | `_ensure_user_terminator(messages: list[dict[str, Any]]) -> list[dict[str, Any]]` | Ensure the message list ends with a user message. | [#L79-L91](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L79-L91) |
| [`_build_strict_prefix_string`](#contract-vllm_mlx.prompt_warmup._build_strict_prefix_string) | function | `_build_strict_prefix_string(tokenizer: Any, messages: list[dict[str, Any]], enable_thinking: bool = True) -> str \| None` | Build a STRING prefix that is a prefix of any real request's rendered chat template for the same system and empty chat history. | [#L94-L176](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L94-L176) |
| [`_build_strict_prefix_string._with_user`](#contract-vllm_mlx.prompt_warmup._build_strict_prefix_string._with_user) | nested function | `_build_strict_prefix_string._with_user(user_content: str) -> list[dict[str, Any]]` | Nested Function `_build_strict_prefix_string._with_user` calls `dict`, `msgs[-1].get`; returns `msgs`. | [#L121-L127](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L121-L127) |
| [`warm_prefix_cache`](#contract-vllm_mlx.prompt_warmup.warm_prefix_cache) | function | `async warm_prefix_cache(engine: Any, prompts: list[list[dict[str, Any]]], *, max_tokens: int = 1) -> dict[str, Any]` | Run each prompt through the engine to populate the prefix cache. | [#L179-L275](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L179-L275) |
| [`warm_prefix_cache._one_strict`](#contract-vllm_mlx.prompt_warmup.warm_prefix_cache._one_strict) | nested function | `async warm_prefix_cache._one_strict(idx: int, messages: list[dict[str, Any]]) -> tuple[int, int, str \| None]` | Nested Function `warm_prefix_cache._one_strict` calls `_build_strict_prefix_string`, `_one_chat`, `engine.stream_generate`, `int`; awaits asynchronous work; has 3 explicit return paths. | [#L217-L235](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L217-L235) |
| [`warm_prefix_cache._one_chat`](#contract-vllm_mlx.prompt_warmup.warm_prefix_cache._one_chat) | nested function | `async warm_prefix_cache._one_chat(idx: int, messages: list[dict[str, Any]]) -> tuple[int, int, str \| None]` | Nested Function `warm_prefix_cache._one_chat` calls `_ensure_user_terminator`, `engine.stream_chat`, `int`, `type`; has 3 explicit return paths. | [#L237-L253](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/prompt_warmup.py#L237-L253) |