# `vllm_mlx.utils.harmony_render`

Harmony-format prompt rendering for GPT-OSS via ``openai-harmony``.

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

## 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.utils.harmony_render
    options:
      members:
        - logger
        - _harmony_encoding
        - is_harmony_parser_name
        - _build_tools
        - _content_to_text
        - _convert_message
        - _resolve_tool_names
        - render_messages
      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.utils.harmony_render._harmony_encoding" markdown="1">
<summary><code>vllm_mlx.utils.harmony_render._harmony_encoding</code> · function</summary>

```python
vllm_mlx.utils.harmony_render._harmony_encoding() -> Any
```

Load the harmony encoding once and reuse it across requests.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `Any`
- Direct return expressions: `_oh.load_harmony_encoding(_oh.HarmonyEncodingName.HARMONY_GPT_OSS)`

**Exceptions and behavior**

Function `_harmony_encoding` calls `_oh.load_harmony_encoding`; returns `_oh.load_harmony_encoding(_oh.HarmonyEncodingName.HARMONY_GPT_OSS)`.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.utils.harmony_render.is_harmony_parser_name" markdown="1">
<summary><code>vllm_mlx.utils.harmony_render.is_harmony_parser_name</code> · function</summary>

```python
vllm_mlx.utils.harmony_render.is_harmony_parser_name(parser_name: str | None) -> bool
```

Return True when the active --tool-call-parser is a harmony alias.

**Parameters**

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

**Returns**

- Type: `bool`
- Direct return expressions: `parser_name in {'harmony', 'gpt-oss'}`

**Exceptions and behavior**

Function `is_harmony_parser_name` returns `parser_name in {'harmony', 'gpt-oss'}`.
No direct `raise` statement appears in this definition.

[View source #L56-L61](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L56-L61).

</details>

<details class="api-contract" id="contract-vllm_mlx.utils.harmony_render._build_tools" markdown="1">
<summary><code>vllm_mlx.utils.harmony_render._build_tools</code> · function</summary>

```python
vllm_mlx.utils.harmony_render._build_tools(tools: list[dict] | None) -> list[Any] | None
```

Function `_build_tools` calls `t.get`, `fn.get`, `tool_descs.append`, `_oh.ToolDescription.new`; has 2 explicit return paths.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tools` | `list[dict] \| None` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `list[Any] | None`
- Direct return expressions: `None`; `tool_descs or None`

**Exceptions and behavior**

Function `_build_tools` calls `t.get`, `fn.get`, `tool_descs.append`, `_oh.ToolDescription.new`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L64-L80](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L64-L80).

</details>

<details class="api-contract" id="contract-vllm_mlx.utils.harmony_render._content_to_text" markdown="1">
<summary><code>vllm_mlx.utils.harmony_render._content_to_text</code> · function</summary>

```python
vllm_mlx.utils.harmony_render._content_to_text(content: Any) -> str
```

Flatten OpenAI content (str | list[dict]) to plain text.

**Parameters**

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

**Returns**

- Type: `str`
- Direct return expressions: `''`; `content`; `'\n'.join(parts)`; `str(content)`

**Exceptions and behavior**

Function `_content_to_text` calls `isinstance`, `item.get`, `parts.append`, `'\n'.join`; has 4 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L83-L97](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L83-L97).

</details>

<details class="api-contract" id="contract-vllm_mlx.utils.harmony_render._convert_message" markdown="1">
<summary><code>vllm_mlx.utils.harmony_render._convert_message</code> · function</summary>

```python
vllm_mlx.utils.harmony_render._convert_message(msg: dict) -> list[Any]
```

Convert one OpenAI-format message to one or more ``openai_harmony.Message``.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `msg` | `dict` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `list[Any]`
- Direct return expressions: `[]`; `out`

**Exceptions and behavior**

Function `_convert_message` calls `msg.get`, `_content_to_text`, `out.append`, `_oh.Message.from_role_and_content`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L100-L182](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L100-L182).

</details>

<details class="api-contract" id="contract-vllm_mlx.utils.harmony_render._resolve_tool_names" markdown="1">
<summary><code>vllm_mlx.utils.harmony_render._resolve_tool_names</code> · function</summary>

```python
vllm_mlx.utils.harmony_render._resolve_tool_names(messages: list[dict]) -> list[dict]
```

Stamp ``name=functions.X`` on each ``role=tool`` message by tracing back the most recent assistant ``tool_call_id`` -> function name.

**Parameters**

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

**Returns**

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

**Exceptions and behavior**

Function `_resolve_tool_names` calls `isinstance`, `out.append`, `m.get`, `tc.get`; returns `out`.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-vllm_mlx.utils.harmony_render.render_messages" markdown="1">
<summary><code>vllm_mlx.utils.harmony_render.render_messages</code> · function</summary>

```python
vllm_mlx.utils.harmony_render.render_messages(messages: list[dict], tools: list[dict] | None = None, reasoning_effort: str | None = None) -> str
```

Render OpenAI-format messages as a harmony-format prompt string.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `messages` | `list[dict]` | `yes` | `none` | OpenAI chat-completions messages. |
| `tools` | `list[dict] \| None` | `no` | `None` | OpenAI-format tools list (each item ``{"type":"function","function":{...}}``). |
| `reasoning_effort` | `str \| None` | `no` | `None` | ``"low"``, ``"medium"``, or ``"high"``. Defaults to medium. |

**Returns**

- Type: `str`
- Direct return expressions: `enc.decode(token_ids)`

**Exceptions and behavior**

Function `render_messages` calls `RuntimeError`, `_resolve_tool_names`, `isinstance`, `other_msgs.append`; can raise `RuntimeError`; returns `enc.decode(token_ids)`.
Directly raised exceptions: `RuntimeError`.

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

</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 |
| --- | --- | --- | --- | --- |
| [`_harmony_encoding`](#contract-vllm_mlx.utils.harmony_render._harmony_encoding) | function | `_harmony_encoding() -> Any` | Load the harmony encoding once and reuse it across requests. | [#L45-L53](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L45-L53) |
| [`is_harmony_parser_name`](#contract-vllm_mlx.utils.harmony_render.is_harmony_parser_name) | function | `is_harmony_parser_name(parser_name: str \| None) -> bool` | Return True when the active --tool-call-parser is a harmony alias. | [#L56-L61](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L56-L61) |
| [`_build_tools`](#contract-vllm_mlx.utils.harmony_render._build_tools) | function | `_build_tools(tools: list[dict] \| None) -> list[Any] \| None` | Function `_build_tools` calls `t.get`, `fn.get`, `tool_descs.append`, `_oh.ToolDescription.new`; has 2 explicit return paths. | [#L64-L80](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L64-L80) |
| [`_content_to_text`](#contract-vllm_mlx.utils.harmony_render._content_to_text) | function | `_content_to_text(content: Any) -> str` | Flatten OpenAI content (str \| list[dict]) to plain text. | [#L83-L97](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L83-L97) |
| [`_convert_message`](#contract-vllm_mlx.utils.harmony_render._convert_message) | function | `_convert_message(msg: dict) -> list[Any]` | Convert one OpenAI-format message to one or more ``openai_harmony.Message``. | [#L100-L182](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L100-L182) |
| [`_resolve_tool_names`](#contract-vllm_mlx.utils.harmony_render._resolve_tool_names) | function | `_resolve_tool_names(messages: list[dict]) -> list[dict]` | Stamp ``name=functions.X`` on each ``role=tool`` message by tracing back the most recent assistant ``tool_call_id`` -> function name. | [#L185-L214](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L185-L214) |
| [`render_messages`](#contract-vllm_mlx.utils.harmony_render.render_messages) | function | `render_messages(messages: list[dict], tools: list[dict] \| None = None, reasoning_effort: str \| None = None) -> str` | Render OpenAI-format messages as a harmony-format prompt string. | [#L217-L303](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/utils/harmony_render.py#L217-L303) |